Formulieren Connector (technisch)

Via {adrez.cloud} kunnen formulieren naar AdreZ sturen en zorgen dat gegevens bij het juiste contact worden bijgewerkt. Met "webhooks" kan de inhoud van een formulier (payload) worden verzonden (gePOST) naar de {adrez.cloud}-server en daar geanalyseerd met een field-mapper-bestand, en verwerkt in de AdreZ-database van de klant.

Er zijn diverse formulieren programma's die webhooks ondersteunen: Typeform, Formdesk, Gravity Forms, Google Forms. Ook is er software beschikbaar als Zapier die bv Google Forms kan verzenden als webhook naar {adrez.cloud}.

Dubbelen

Vooraf bepalen we hoe we een contact met een zogenaamde locator kunnen opzoeken in AdreZ  en verwerken. Vaak is dat het e-mailadres, of de naam " van het contact, of de organisatie. Het is ook mogelijk om het unieke contact-nummer uit AdreZ te gebruiken als dat bv via een uitnodiging uit AdreZ bekend is. Vinden we het contact niet op contactId, e-mailadres of naam; dan wordt het contact toegevoegd.

Adrez.cloud-server

Een formulier wordt ontwikkeld en getest op staging.adrez.cloud/import/hook, en na een technische afstemming tussen bouwer en EM-Cultuur, door de klant getest.

Payload

De structuur van de payload is flexibel en wordt door bouwer en EM-Cultuur bepaald. Dit resulteert in een zogenaamd "field-mapper-bestand" dat de velden uit de formulier-payload vertaalt naar de velden en codes in AdreZ. Per soort formulier wordt een mapper-bestand geschreven (uniek en herkend door de formName). Door gebruik van een andere "event of campagne-code" kan een mapper-bestand voor meerdere formulieren/doeleinden worden ingezet.

{
	"formName" : "myFirstForm",
	"event": "TEST",
	"contactId" : 123456,
	"hashkey" : "38kgeBLmLOW$O7C$naLVTqZte",
	
	"name"  : "Erick de Boer",
	"organisation": "EM-Cultuur",
	"function":  "Directeur",
	"emailddress" : e.deboer@em-cultuur.nl,
	"phone": "123455",<br>
	"street":  "damrak 68 A"
	"city" :  "1012 LM Amsterdam
	"codes": "religion, fireworks, "fish""
	"fields": "urk", "creil", "espel", "tollebeek"
        "memo" : "verder geen opmerkingen"
}

Toelichting payload-velden

Alle velden zijn optioneel, behalve formName 

• formName :  unieke naam voor het formulier
• event: hiermee kan een zelfde formulier, met verschillende toepassingen worden gebruikt: codes/velden krijgen dan een herkenbare prefix: "TEST"
• contactId: het unieke adresnummer in AdreZ dat eventueel via MailingLijst is doorgestuurd aan het formulie
• hashkey: versleuteling die voorkomt dat men het formulier misbruikt  (als contactId/hashkey  niet overeenkomen wordt de payload genegeerd)

locater:  een sleutel waarop een contact wordt gezocht, wordt in overleg met de formulier-bouwer en klant bepaald

- e-mailadres, naam, organisatie, contactId  (als het contact niet wordt gevonden wordt het toegevoegd)

namen:

namen kunnen worden op verschillende manieren worden aangeboden: 

• volledige naam :  "Erick de Boer"
• sorteer naam : "Boer, Erick de"
• opgeknipt  : "Erick" "de" "Boer"

communicatie:

e-mail, telefoon/mobiel, worden door {adrez.cloud} gevalideerd

!: max 1 e-mailadres/telefoonnummer per veld (dus niet meerdere gescheiden door comma)

adres/locatie:

ook hier verschillende vormen:

• opgeknipt: straat, huisnummer, postcode, plaats
• straatNummer:  "Dorpsstraat 88-2",
• postcodePlaats:  "1022 AZ Boerenkoolstronkradeel"

(land alleen nodig indien anders dan Nederland)

codes:

kunnen worden meegegeven als: 

• naam:  "code_functie" : "directeur"
• guids/naam van bestaande adrez-selectiecode : "code" : "DEMO_12345"
• aan/uit:  "code_mailinglijst":  "x"

meerdere codes in 1 veld is mogelijk als ze worden gescheiden door een te bepalen teken (comma, puntcomma)

fields:

kunnen van type:

• logisch (j/n, y/n, t/f)
• datum:  "YYYYMMDD"
• getal:  1234.56
• tekst: "korte tekst, max 255 tekens"
• memo:  langere tekst

extra:

meerkeuze/dropdown-vragen worden door de meeste formulieren programma's als ;-geschieden lijst meegestuurd. Deze lenen zich voor een tekst-field dat in AdreZ als list of multi-list kan worden getoond.