Deze Connector kan interessant voor je zijn als je toegang hebt tot technisch personeel (softwareontwikkelaars) en je nauw wilt integreren met ons platform.

De REST Connector stuurt automatisch formulierinvoergegevens in XML- of JSON-indeling naar jouw specifieke webserviceadres.

Dit stelt je in staat om met ons te integreren op eventi-niveau – dat wil zeggen dat je de gegevens ontvangt via de nominale REST-verb wanneer we een nieuwe formulierinvoer ontvangen – bijvoorbeeld POST.

Jouw webservice moet de API implementeren die wij specificeren om de gegevens die we standaard verzenden te begrijpen.

Technisch personeel dient onze Form Entries API-documentatie te raadplegen (te vinden in het Integration-gedeelte van onze helpsite).

Je kunt ook jouw aangepaste request body definiëren om aan bestaande API-eindpunten te voldoen waarnaar je formulierinvoergegevens wilt sturen.

De Connector toevoegen

Volg deze stappen om de connector aan jouw specifieke formulier toe te voegen:

1. Navigeer naar App Workshop > Forms.
2. Beweeg je muis over jouw gewenste formulier en klik op het Connect-pictogram.
3. Klik op de Add Connector-knop (rechtsboven).
4. Selecteer REST uit de opties.

Opmerking: De pagina wordt vernieuwd met de toegevoegde connector. Wijzigingen zijn niet live totdat je op Save klikt.

Tip voor snelle toegang

Als je al in de Form Builder of Settings-weergave bent, hoef je niet terug naar het hoofdmenu. Klik gewoon op het Connectors-tabblad dat zich direct onder de formuliertitel aan de bovenkant van het scherm bevindt.

De Connector configureren

Dit gedeelte beschrijft de essentiële stappen om jouw REST-connector te configureren, inclusief het instellen van de HTTP-actie, bestemmings-URL en andere belangrijke configuraties.

HTTP Action

Geef de API-verb aan die je wilt gebruiken om met de API te communiceren. We ondersteunen POST, GET, PUT, DELETE en PATCH. Je kunt ook de tekstindeling voor jouw API-aanvraag kiezen.

We ondersteunen de volgende indelingen voor API-integratie:

XML, JSON, CSV, HTML, URL Encoded, Excel, Word of Text.

Destination URL

Je moet de bestemmings-URL opgeven waarnaar ons platform gegevens POST’et.

Je kunt een volledige URL handmatig invoeren of de {{GLOBAL}}-placeholder gebruiken om een deel van het adres te vervangen door jouw organisatie’s Global Forms REST URL, als dit in jouw organisatie-instellingen is geconfigureerd.

Voorbeeld: {{GLOBAL}}/api/endpoint

Standaardquerystring-parameters uitschakelen (selectievakje)

Standaard worden bepaalde querystring-parameters aan de URL toegevoegd. Deze parameters kunnen worden gebruikt om de oorsprong van een aanvraag te authenticeren – bijvoorbeeld de waarde van jouw organisatie’s Private Token.

Schakel dit selectievakje in als je niet wilt dat deze informatie wordt verzonden.

Persoonlijke gegevens anonimiseren (selectievakje)

Als dit is ingeschakeld, worden gegevens van velden die als persoonlijke gegevens zijn gemarkeerd, naar een niet-leesbare indeling omgezet ter ondersteuning van privacy.

Aanvullende instellingen

Dit gedeelte legt geavanceerde opties uit die kunnen worden geconfigureerd via de pictogrammen in de hoek rechtsboven van de REST-connectorconfiguratie. Met deze instellingen kunt je het gedrag van de connector aanpassen en uitvoeringsvoorwaarden definiëren.

Headers

Geef aangepaste request-headers op die als onderdeel van deze REST-aanvraag moeten worden verzonden.

De volgende placeholders kunnen worden gebruikt om de inloggegevens van de gebruiker in te voegen:
{{USEREMAIL}}
{{USERPASSWORD}}
{{ORGID}}

Body

Voer een aangepaste payload in JSON of XML in (afhankelijk van het geselecteerde inhoudstype).
Je kunt onze data-templating syntax gebruiken om formulierveldplaceholders in te voegen en herhalende secties te definiëren.

Backslashes (\) en dubbele aanhalingstekens (“) die in formulierantwoorden worden gevonden, worden automatisch ontsnapt voor JSON-payloads.

Dit kan een probleem zijn als je een JSON-array wilt injecteren met de waarde van een enkel formulierveldantwoord.

Om te voorkomen dat dubbele aanhalingstekens ontsnapt worden in een formulierantwoord, gebruik je een formule voor dynamische waarde zoals SUBSTITUTE() in je formulierontwerp om de dubbele aanhalingstekens te laten voorafgaan door een backslash.

Bijvoorbeeld: verander je formulierantwoord van “orange”, “apple” in \”orange\”, \”apple\”.

Vervang aanduidingen door weergegeven tekst (selectievakje)

Standaard worden aanduidingen vervangen door de onbewerkte antwoordwaarde van de forminvoer. Bijvoorbeeld datumwaarden worden in UTC opgeslagen in ISO 8601-onbewerkte indeling, bijvoorbeeld 2015-10-23T15:05:07Z.

Selecteer deze optie als je het in plaats daarvan wilt vervangen door door de gebruiker weergegeven tekst, bijvoorbeeld 23-Oct-2015 05:05:07, ervan uitgaande dat je tijdzone UTC-10 is

Voer deze actie alleen uit wanneer

Voeg een formule toe die bepaalt of deze Connector moet worden uitgevoerd wanneer een forminvoer wordt ingediend. Gebruik het hamerpictogram om de Formula Builder te starten en bouw een formule met een waar/onwaar-resultaat.

Voer uit na Connector

Creëert een afhankelijkheid voor de uitvoering van deze connector op basis van de uitkomst van de geselecteerde connector. Als je bijvoorbeeld Succes (eigenschapoptie) kiest, wordt deze connector alleen uitgevoerd als de uitkomst van de geselecteerde connector succesvol is.

Globale service-eindpunten

De sectie Globale configuratie op de pagina Organisatie-instellingen (Menu > Organisatie-instellingen > Integraties) stelt je in staat om gecentraliseerde instellingen te definiëren die opnieuw kunnen worden gebruikt in meerdere connectors en componenten op het platform. Dit vereenvoudigt het onderhoud en zorgt voor consistentie tussen integraties.

Je kunt globale eindpunten definiëren voor het volgende connectortype:

Formulier REST-connectors

Geef een globaal REST-eindpunt op dat wordt gebruikt door alle formulier-REST-connectors die verwijzen naar de {{GLOBAL}}-aanduiding.

Deze benadering is bijzonder nuttig voor het handhaven van een consistente API-basis-URL voor formulieren en voor het vereenvoudigen van updates wanneer eindpunten veranderen.

Taak REST-connectors

Geef een globaal REST-eindpunt op dat wordt gebruikt door alle taak-REST-connectors die verwijzen naar de {{GLOBAL}}-aanduiding.

Datasync

Geef een webserviceeindpunt op dat wereldwijd kan worden gebruikt door Platform Sync en connectors in Gegevensbronnen.

Toewijzingstegels voor app

Door het systeem geleverde kaarttegels worden standaard in de app gebruikt om kaarten aan gebruikers weer te geven.

Als je je eigen aangepaste kaarttegels wilt gebruiken (bijvoorbeeld uit een GIS-systeem), geef je hier een URL-sjabloon op.

De URL moet (z), (x) en (y) aanduidingen bevatten, die respectievelijk het zoomniveau, X en Y decimale coördinaten vertegenwoordigen die aan je tegelbroneenprovider moeten worden doorgegeven.

Voorbeelden:

• https://tile.openstreetmap.org/{z}/{x}/{y}.png
• https://[host]/arcgis/rest/serv/map/tile/{z}/{x}/{y}.png

Aangepaste HTTP-headers toevoegen

Gebruik de optie “Headers” om HTTP-aanvraagheaders toe te voegen aan de REST-aanvraag van het platform.

Dit is nuttig voor externe API-services die vereisen dat je verificatie uitvoert met behulp van Auth-headers die je gebruikersnaam en wachtwoord bevatten.

Headerwaarden kunnen ook dynamisch zijn – je kunt formulierveldwaarden injecteren met de gebruikelijke {{myfieldname}}-syntaxis.

Hieronder staan enkele HTTP-headers die je kunt gebruiken bij het verbinden met je gewenste API-eindpunten.

Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
Content-Type: application/x-www-form-urlencoded

Het aanvraagbody aanpassen

Met de optie “Body” kun je je eigen aangepaste JSON- of XML-datanettoladingen instellen en formulierantwoordwaarden injecteren met behulp van onze standaard {{fieldname}}-syntaxis.

Je kunt zelfs tegemoet komen aan herhalende gegevens in je body met behulp van onze {{!REPEATSTART}} {{!REPEATEND}}-syntaxis die normaal gesproken is gereserveerd voor datasjablonen.

Je zou bijvoorbeeld een JSON-body kunnen hebben die urenstaterijen herhaalt, zoals:

<div data-identifyelement="698">
<pre contenteditable="false" data-code-brush="Html" data-identifyelement="699">http://somewhere.com/service/{{myfield}}/contact?option={{myoption}}</pre>
</div>

Klik op de moersleutel naast het vak Doel-URL om het venster Tekstbouwer te openen en je dynamische doel-URL samen te stellen.

Een uitvoeringsvoorwaarde toevoegen

Soms heb je een Connector die je alleen wilt uitvoeren/activeren als de formulierinvoer een bepaalde antwoordwaarde heeft.

Je hebt bijvoorbeeld een Auditwormulier met een vraag over risicobeoordeling met opties zoals “Laag”, “Gemiddeld” en “Hoog”.

Als de gebruiker “Hoog” selecteert voor de risicobeoordeling, wil je een e-mail naar een supervisor sturen voor vervolgmaatregelen.

Dit is waar een uitvoeringsvoorwaarde van pas komt.

Uitvoeringsvoorwaarden worden gedefinieerd door een waar/onwaar-formule aan te maken.

De Connector wordt alleen uitgevoerd als de formule die je in de uitvoeringsvoorwaarde definieert waar oplevert.

In het voorbeeld hierboven zou de uitvoeringsvoorwaardeformule iets als volgt zijn: {{riskRating}} = ‘High’

Het veld Uitvoeringsvoorwaarde heeft een moersleutel-pictogram ernaast. Dit betekent dat je wanneer je op de moersleutel klikt, een dynamische formule in het pop-upvenster Formulebouwer kunt maken.

Zie de pagina Een formule maken voor meer informatie over formulesformules.

Een REST-stap toevoegen

Soms heb je een Connector die gegevens van een externe webservice nodig heeft voor het verzoek. Dit is waar onze optie “REST-stap toevoegen” nuttig kan zijn.

De toegevoegde REST-stap wordt eerst geactiveerd, waardoor opgehaalde gegevens in het verzoek kunnen worden gebruikt.

Het resultaat van de REST-stap wordt geretourneerd als $response voor gebruik in het volgende verzoek.

Krijg toegang tot eigenschappen of lijsten van elementen uit JSON-reacties via de formule-functies JSONVAL() en JSONLIST().

Op dezelfde manier geldt voor XML-reacties XMLVAL() en XMLLIST().

bijv. {(JSONVAL($response, ‘path.to.property’))}

Probleemoplossing

Time-outs bij je REST-connector-taken

Je kunt situaties tegenkomen waarin je REST-connector time-outfouten rapporteert wanneer deze wordt uitgevoerd op een formulierinvoer.

Dit gebeurt omdat je REST-webservice geen 200 OK-status retourneert binnen 10 seconden nadat ons platform het REST-verzoek heeft verzonden.

De 10-secondes time-out is van toepassing op de tijd om het REST-verzoek uit te voeren, de gegevens af te leveren en een reactie te ontvangen.

Elk PDF-bestand dat als onderdeel van het verzoek wordt verzonden, wordt gegenereerd voordat de time-outklok begint.

De enige afbeeldingen die met een REST-connector-verzoek worden verzonden, zijn dus die in een gegenereerd PDF-bestand.

Ons datacenter heeft gigabit-verbindingen en verzend довольно snel. Je servers moeten even snelle transportschakels hebben.

Het vergroten van de time-outwaarde kan tot aanzienlijke achterstanden in onze connector-taakwachtrijen leiden wanneer de doel-REST-webservices problemen ondervinden en geen reactie geven. In dat scenario blijft ons connector-proces wachten op een reactie voor de hele time-outperiode. Dat zou 20, 30, 40 enzovoort seconden zijn dat een connector-proces niets doet terwijl het de volgende taak zou kunnen verwerken.

Wanneer dit op grote schaal gebeurt (bijvoorbeeld met duizenden connector-taken), kan het tot aanzienlijke achterstanden in onze connector-infrastructuur leiden.

Op dit moment hebben we geen plannen om de time-out voorbij de 10 seconden te verlengen.

Als je regelmatig de time-outlimiet bereikt, raden we je aan om je webservice te controleren en wijzigingen aan te brengen om binnenkomende verzoeken sneller te verwerken.

Een eenvoudige manier om dit te doen is om het binnenkomende verzoek op te slaan in een wachtrij/database en onmiddellijk met een 200 OK te antwoorden.

Voer vervolgens any verbruikt verwerk (bijv. database-invoeging) asynchroon uit door een afzonderlijk proces de inkomende items uit de wachtrij/database op te laten halen.