Form Connector – REST 2-Step Scenario

Form Connector – REST 2-Step Scenario

It’s common to encounter a scenario where you wish to interface with one API endpoint and then use the response as input data for another API interaction. To achieve this, our REST Field and REST Form Connectors support up to two steps in REST API interactions.

This article will explore how to utilize the REST step feature to achieve this 2-step functionality.

Scenario

We’ve put together a simple example with practical, real-world usage potential to illustrate how to use this functionality.

Let’s assume we want the user to open a form and enter a mobile number and a text message. When they submit the form, this message is relayed through an SMS gateway’s REST API for delivery to the recipient specified. When the message is sent to the SMS gateway, we want to log the SMS gateway’s response, details of the message sent, and the SMS gateway’s response, so you have an audit trail to identify any messages sent or not sent.

The following steps will show you how to achieve this using the REST Form Connector’s 2-step feature.

Data Source

A data source must be created to log the information captured by the form and the response from the SMS gateway.

The data source column names will be needed in the 2-Step’s JSON Body, along with an external ID that can be set on the data source’s Settings Page, your Company ID, and an Integration Key acquired from your Organisation Setup area.

Below is a list of all the columns used in the data source for this scenario:

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

Data Entry Form

For this example, we’ll create a simple form in the designer where we will allow the user to specify:

  • A field for generating a GUID as the unique message identifier;
  • The mobile number of the recipient (where the SMS text message will be sent when the form is submitted);
  • A field for the actual message to send to the recipient;
  • A field for automatically capturing the name of the logged-in user;
  • A field for adding the custom message text to the message;
  • A field for logging the date and time when the SUBMIT button is pressed.

Below is an example of what a form could look like that will capture data to submit to the API:

REST Connector – First Step

Once the form is complete, you can create the REST Form Connector to communicate with your SMS Gateway API.

Once you’ve added the REST form connector, be sure to press the “Add REST Step” icon (top right of the connector) to add an additional REST body section where you can specify a 2nd REST connection to a separate API endpoint.

The first step of the REST form connector will send the data to the SMS Gateway and is configured as shown in the screenshot below:

When the form communicates with the SMS gateway, the SMS gateway will respond with an HTTP code of 202 to signify that communication with the API was successful. This will differ for each API endpoint and is only used in this instance as an example.

The JSON body response from the connector’s communication with the API (first step) is copied below as an example of what data we will have access to. We can now use this data when communicating with the Data Source API to write to a data source (second step).

API Response JSON Body

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

So now we have our API response from the first API call to send the SMS. The next part is to configure the REST body in the connector’s second step.

REST Connector – Second Step

For the second step, we need to communicate with the Appenate data source API endpoint to write a row to the data source, log the message, and receive a gateway response.

The second step will always trigger immediately after receiving an HTTP response from the first REST API call.

We’ll create a JSON Body to submit to the second API endpoint, as shown in the screenshot below:

The actual JSON body text used in this example is copied below for your perusal:

{
  "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"
}

You’ll notice that some of the values are extracted directly from the form data using our regular {{dataname}} syntax. To extract the values returned from the initial REST API connection’s JSON body response, we use the JSONVAL() function.

The JSONVAL function allows you to parse the API response body returned from the API call in the first step and extract specific node values in the JSON body for use in this new JSON body.

To extract the value for “apiMessageId” from the JSON body, we use the syntax below:

{(JSONVAL($response, '$.messages[0].apiMessageId'))}

The syntax to navigate a JSON body to find specific values is caled JSON Path. The website JSONPathFinder.com allows you to paste a JSON body and then select the nodes you want to access and use the syntax it returns in your JSON body.

Once you’ve constructed your JSON body for use in the second step of the connector, your form will be ready for testing.

Your completed REST form connector with both steps should look similar to what is shown in the screenshot below:

    • Related Articles

    • Form Connector – REST

      This Connector will be interesting if you have access to technical personnel (software developers) and want to tightly integrate with our platform. The REST Connector will automatically send form entry data in XML or JSON format to your specific web ...

    • REST Connector – Integrating with Zapier

      While our platform offers many native integrations, you can connect to over 5,000 apps by routing your form data through Zapier. By using our REST Connector as the trigger, you gain professional-level control over your data flow, including custom ...

    • Workflow A Form Entry Between Users (Process Steps)

      Often, a business process requires more than one person to complete it. In these scenarios, just capturing a Form entry is not enough: multiple users must review, approve, reject, or update it. The Process Step field type found in the Form Designer ...

    • Workflow Process Step Formulas

      Now that you’re familiar with the basics of creating a 2-Step Workflow using the Process Field. We’ll look deeper into the 3-Step Workflow and formulas used to control read-only and visibility properties at different process steps. And, Form ...

    • REST Field

      The REST field type enables you to issue a REST request in JSON or XML to an external web service and pull data from any API. The result of the request is stored in the REST field, and you can then access the result’s values through our existing ...