Formulierconnector – REST 2-stapsscenario

Het is gebruikelijk dat je een scenario tegenkomt waarin je met één API-eindpunt wilt communiceren en vervolgens de respons als invoergegevens voor een ander API-interactie wilt gebruiken. Om dit te bereiken, ondersteunen onze REST Field en REST Form Connectors tot twee stappen in REST API-interacties.

Dit artikel gaat verkennen hoe je de REST-stapfunctie kunt gebruiken om deze 2-stapfunctionaliteit te bereiken.

Scenario

We hebben een eenvoudig voorbeeld samengesteld met praktisch, real-world gebruikspotentieel om te illustreren hoe je deze functionaliteit kunt gebruiken.

Stel dat je wilt dat de gebruiker een formulier opent en een mobiel nummer en een tekstbericht invoert. Wanneer ze het formulier indienen, wordt dit bericht via de REST API van een SMS-gateway voor aflevering naar de opgegeven ontvanger doorgestuurd. Wanneer het bericht naar de SMS-gateway wordt verzonden, willen we de respons van de SMS-gateway, details van het verzonden bericht en de reactie van de SMS-gateway vastleggen, zodat je een audittrail hebt om te zien welke berichten zijn verzonden of niet.

De volgende stappen laten je zien hoe je dit kunt bereiken met behulp van de 2-stapfunctie van de REST Form Connector.

Gegevensbron

Er moet een gegevensbron worden gemaakt om de informatie die door het formulier en de respons van de SMS-gateway is vastgelegd, in te loggen.

De kolomnamen van de gegevensbron zijn nodig in de 2-Stap’s JSON Body, samen met een externe ID die op de pagina Instellingen van de gegevensbron kan worden ingesteld, je Bedrijfs-ID en een Integratietoets verkregen uit je Organisatie Setup-gebied.

Hieronder staat een lijst met alle kolommen die in de gegevensbron voor dit scenario worden gebruikt:

• MessageID
• Date
• Message_text
• Sent_By
• Recipient_Number
• API_MessageID
• Status
• Error_Code
• Error
• Error_Description

Gegevensinvoerformulier

Voor dit voorbeeld maken we een eenvoudig formulier in de designer waarin we de gebruiker laten opgeven:

• Een veld voor het genereren van een GUID als unieke berichtidentificatie;
• Het mobiele nummer van de ontvanger (waar het SMS-tekstbericht wordt verzonden wanneer het formulier wordt ingediend);
• Een veld voor het werkelijke bericht dat naar de ontvanger moet worden verzonden;
• Een veld voor het automatisch vastleggen van de naam van de ingelogde gebruiker;
• Een veld voor het toevoegen van de aangepaste berichttekst aan het bericht;
• Een veld voor het vastleggen van de datum en tijd wanneer op de knop VERZENDEN wordt geklikt.

Hieronder is een voorbeeld van hoe een formulier er uit kan zien waarmee gegevens worden vastgelegd om naar de API in te dienen:

REST Connector – Eerste stap

Zodra het formulier compleet is, kun je de REST Form Connector maken om met je SMS Gateway API te communiceren.

Zorg er na het toevoegen van de REST-formulierconnector voor dat je op het pictogram “REST-stap toevoegen” (rechtsboven van de connector) klikt om een aanvullende REST-bodysectie toe te voegen waar je een 2e REST-verbinding naar een ander API-eindpunt kunt opgeven.

De eerste stap van de REST-formulierconnector stuurt de gegevens naar de SMS-gateway en is geconfigureerd zoals weergegeven in de screenshot hieronder:

Wanneer het formulier met de SMS-gateway communiceert, zal de SMS-gateway reageren met een HTTP-code van 202 om aan te geven dat de communicatie met de API succesvol was. Dit zal voor elk API-eindpunt verschillen en wordt in deze instantie alleen als voorbeeld gebruikt.

De JSON-body-respons van de communicatie van de connector met de API (eerste stap) is hieronder gekopieerd als een voorbeeld van welke gegevens we kunnen gebruiken. We kunnen deze gegevens nu gebruiken bij communicatie met de Data Source API om naar een gegevensbron te schrijven (tweede stap).

API-respons JSON Body

{
  "messages": [
    {
      "apiMessageId": "1a20c64440ca4e8e880393a6334b5cb8",
      "accepted": true,
      "to": "27123456789",
      "errorCode": 0,
      "error": "NONE",
      "errorDescription": "NONE"
    }
  ]
}

Nu hebben we onze API-respons van de eerste API-aanroep om de SMS te verzenden. Het volgende gedeelte is het configureren van de REST-body in de tweede stap van de connector.

REST Connector – Tweede stap

Voor de tweede stap moeten we communiceren met het TaskForm gegevensbron API-eindpunt om een rij naar de gegevensbron te schrijven, het bericht in te loggen en een gatewayrespons te ontvangen.

De tweede stap wordt altijd onmiddellijk na ontvangst van een HTTP-respons van de eerste REST API-aanroep geactiveerd.

We maken een JSON Body om naar het tweede API-eindpunt in te dienen, zoals weergegeven in de screenshot hieronder:

De werkelijke JSON-body-tekst die in dit voorbeeld wordt gebruikt, is hieronder gekopieerd ter kennisgeving:

{
  "ExternalId": "extid_logging_ds",
  "Headers": [
    {
      "Name": "MessageID",
      "DisplayAt": "None"
    },
    {
      "Name": "Date",
      "DisplayAt": "None"
    },
    {
      "Name": "Message_text",
      "DisplayAt": "None"
    },
        {
      "Name": "Sent_By",
      "DisplayAt": "None"
    },
        {
      "Name": "Recipient_Number",
      "DisplayAt": "None"
    },
        {
      "Name": "API_MessageID",
      "DisplayAt": "None"
    },
        {
      "Name": "Status",
      "DisplayAt": "None"
    },
        {
      "Name": "Error_Code",
      "DisplayAt": "None"
    },
        {
      "Name": "Error",
      "DisplayAt": "None"
    },
        {
      "Name": "Error_Description",
      "DisplayAt": "None"
    }
  ],
  "NewRows": [
    [
    "{{h_message_id}}",
    "{{h_date_time_sent}}",
    "{{message_text}}",
    "{{h_sending_user}}",
    "{{recipient_mobile_number}}",
    "{(JSONVAL($response, '$.messages[0].apiMessageId'))}",
    "{(JSONVAL($response, '$.messages[0].accepted'))}",
    "{(JSONVAL($response, '$.messages[0].errorCode'))}",
    "{(JSONVAL($response, '$.messages[0].error'))}",
    "{(JSONVAL($response, '$.messages[0].errorDescription'))}"
    ]
  ],
  "CompanyId": 12345678,
  "IntegrationKey": "58881aa193964dfbb9bdcf8af1a1d248"
}

Je zult merken dat sommige waarden rechtstreeks uit de formuliergegevens worden geëxtraheerd met onze reguliere {{dataname}}-syntaxis. Om de waarden die zijn geretourneerd uit de JSONhttps://www.jsonpathfinder.com/” rel=”noreferrer noopener” target=”_blank”>JSONPathFinder.com stelt je in staat om een JSON-body in te plakken en vervolgens de knooppunten te selecteren die je wilt benaderen en de syntaxis die het retourneert in je JSON-body te gebruiken.

Zodra je je JSON-body voor stap twee van de connector hebt samengesteld, is je formulier klaar voor testen.

Je voltooide REST-formulierconnector met beide stappen zou er vergelijkbaar uit moeten zien als wat in de onderstaande schermafbeelding wordt weergegeven: