REST - Form Connector

This connector is ideal for those with technical personnel, such as software developers, who aim for a tight integration with our platform. The REST Connector will automatically transmit form entry data in XML or JSON format to your specified web service address.

This feature enables event-level integration; whenever a new form entry is received, the data will be sent using the standard REST verb (e.g., POST). Your web service should implement the API we provide to correctly interpret the data sent by default.

Technical staff should refer to our Form Entries API documentation, available in the Integration section of our help site. Alternatively, you can define a custom request body to align with your existing API endpoints for form entry data transmission.

ARTICLE CONTENTS

• Adding the Connector
• Configuring the Connector
• Global Forms REST URL
• Customizing the Request Body
• Setting up a Dynamic Request URL
• Adding Custom HTTP Headers
• Adding a Run Condition
• Adding a REST Step
• Troubleshooting

Adding the Connector

The Connectors page can be accessed from the Screens page by mousing over the Form row or from the From Design or Settings page. 

Screens Page

Form Design

Once you are on the Connectors page, setting up a REST Connector is easy:

Hover over the "Add Connector" button on the top right corner to see all available Connectors.

Click the REST option.

This will refresh the page and display your Connector, ready for configuration. 

Configuring the Connector

HTTP Action

Specify the API verb you wish to use to interface with the API. We support POST, GET, PUT, DELETE and PATCH. You can also choose the text format for your API request.

We support the following formats for API integration:

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

Destination URL

You need to specify the destination URL to which our platform will POST data.

You can enter an address directly into the given field or "Use Global Forms REST URL" if set up on your organization setup page.

Disable default query string parameters (checkbox)

By default, specific query string parameters are appended to the URL, which can be used to authenticate the origin of a request - e.g., your Organization's Private Token value.

Enable this checkbox if you do not require this information to be sent.

Headers

Provide custom request headers to be sent as part of this REST request.

The following placeholders can be used to inject the user's login details:
{{USEREMAIL}}
{{USERPASSWORD}}
{{ORGID}} 

Body

Enter a custom payload in JSON or XML (depending on the content type selected).
You can use our data templating syntax to inject Form field placeholders and define repeating sections.

{
   "myjsonproperty": "{{myformfield}}",
   "myjsonarray": [
       {{!REPEATSTART}}
       {
      "myarrayproperty": "{{myrepeatfield}}",
      "arrayprop2": "{{repeatfield2}}"              
  },
  {{!REPEATEND}}
    ]
}

To specify that the REST connector must use the Form REST Connector set in the Global Service Endpoint, use the {{GLOBAL}} placeholder as the Destination URL on the REST Form connector.

Customizing the Request Body

The "Body" option allows you to set up your own custom JSON or XML data payloads and inject form answer values using our standard {{fieldname}} syntax.

You can even cater to repeating data in your body using our {{!REPEATSTART}} {{!REPEATEND}} syntax that is normally reserved for data templates.

For example, you might have a JSON body that repeats timesheet rows like so:

{
    "timeEntries": [
        {{!REPEATSTART}}
        {
            "entryDate":"{{entryDate}}",
            "startTime":"{{startTime}}",
            "finishTime":"{{finishTime}}",
            "timeTotal":"{{timeTotal}}",
            "description":"{{entryDescription}}"
        },
        {{!REPEATEND}}
    ],
    "entryCount":"{{hiddenEntryCount}}",
    "headerSummary":"{{headerSummary}}",
    "entrySummary":"{{entrySummary}}"
}

http://somewhere.com/service/{{myfield}}/contact?option={{myoption}}

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

Sometimes, you may have a Connector that requires data from an external web service to be used in the request. This is where our "Add REST Step" option may be helpful.

The added REST step triggers first, allowing for retrieved data to be used in the request.

The result from the REST step is returned as a $response for use in the subsequent request below.

Access properties or lists of elements from JSON responses via the JSONVAL() and JSONLIST() formula functions.

Similarly, for XML responses, use XMLVAL() and XMLLIST().

e.g. {(JSONVAL($response, 'path.to.property'))}

Troubleshooting

Timeouts on your REST connector jobs  

You may encounter situations where timeout errors are reported for your REST connector when it runs on a Form entry.

This will be because your REST web service is not responding with a 200 OK status within 10 seconds of our platform sending the REST request.

The 10-second timeout applies to the time to execute the REST request, deliver the data, and get a response.
Any PDF file sent as part of the request will be generated before commencing the request timeout clock.

Note that we don't send any actual media files captured in a Form entry with REST requests; instead, we send the file names so you can retrieve the files separately via our API.

Thus, the only images sent with a REST connector request would be those within a generated PDF file.

Our data center has gigabit connections and transmits quite fast. Your servers should have similarly fast transport links.

Raising the timeout value could create huge backlogs on our connector job queues when the target REST web services have an issue and do not respond. In that scenario, our connector process will sit, waiting for the entire timeout period for a response. That would be 20, 30, 40, etc., seconds that a connector process is doing nothing when it could be processing the next job.

When this happens at scale (i.e., with thousands of connector jobs), then this can create significant backlogs on our connector infrastructure.

At this point, we have no plans to increase the timeout beyond 10 seconds.

 If you regularly hit the timeout limit, we recommend you examine your web service and make changes to process incoming requests faster.

A simple way to do this is to store the incoming request on a queue/database and respond with a 200 OK immediately.

Then, do any time-consuming processing (e.g., database inserts) asynchronously by having a separate process pick up the incomings from the queue/database.