REST - Form Connector

The REST Connector will automatically send form entry data in XML or JSON format to your specific web service address.

This allows you to integrate with us on an event level - i.e., whenever we receive a new Form entry, you will receive the data on the nominal REST verb - e.g., POST.

Your web service should implement the API we specify to understand the data we send by default.

Technical staff should see our Form Entries API documentation (found in the Integration section of our help site).

Alternatively, you can define your custom request body to match existing API endpoints to which you wish to send form entry data.

Adding the Connector

The Connectors page can be accessed from your Form design settings or the Screens page

Screens PageForm DesignOnce you are in the Connectors page, setting up a REST Connector is easy:

1. Hover over the "Add Connector" button to see a list of the available Connectors. Click the REST option.
2. This will refresh the page and display your Connector, ready for configuration.
   • Note that at this stage nothing has been saved: you must click the Save button to save your Connector after you've finished setting it up.

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.

e.g.

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

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 for repeating data in your body by 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}}"
}

Setting up a Dynamic Request URL

You can also inject answer values to dynamically build up the URL to which the request will be sent. So, for example, your target URL could look like: 

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

Click on the hammer next to the Destination URL box to open the Text Builder window to construct your dynamic destination URL. 

Adding Custom HTTP Headers

Use the "customize headers" option to add HTTP request headers onto the REST request that is sent out by the platform. This is useful for external API services that require you to authenticate using Auth headers that contain your username/password combinations. Header values can be dynamic as well: you can inject form field values using the usual {{myfieldname}} syntax.

NOTE: HTTP Headers are NOT a way to send your form field names to the target API. Research HTTP Headers to understand what these are and how to use them.

Below are some HTTP Headers you might use when connecting to your desired API endpoints. 

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

Add a Run Condition

Sometimes you may have a Connector that you only want to fire in the event that the Form entry has a given answer value. For example, you may have an Audit Form which has a risk rating question with options like "Low," "Medium" and "High." If the user answers the risk rating as "High," then you want an email to be sent to a supervisor for follow-up and action.

This is where a Run Condition comes in. Run Conditions are defined by creating a true/false formula. The Connector will only run if the formula you define in the Run Condition has a true result. So, in the example above, the Run Condition formula would be something like:

{{riskRating}} = 'High'

The Run Condition field has a hammer icon next to it. Clicking the hammer will take you into the Formula Builder, which helps you to put together the formula you desire.

See the Creating a Formula page to learn more about form formulas.

Add a REST Step

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.

 You can browse all REST connector failures through the notification logs.

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.