HTTP Data Destination
Available on the Advanced and Enterprise tiers:
Contents
About
The HTTP Data Destination
A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats. can send any form submission data to any web app or data storage service accessible through the internet. This makes it an ideal deal for low-code custom integrations.
This destination can send raw data (including files & photos) from submitted forms to an external system, or create or update objects in other systems.
Data destinations automatically send data collected in the field. They reduce the need to visit the web portal by making submitted forms available through the services you already use. The information from your submitted form can be routed to different places: the customer can receive a finished form, and the data from that form can be sent to back-office systems seamlessly. Read here for more information on data destinations.
Basic Set Up
- Create the data destination following the instructions here.
- Set up the Request/Response Configuration tab as discussed below.
Request/Response Configuration
When you are communicating with another system, this is the content of that communication.
- The Request is what TrueContext sends to the other system; it contains information about what action you would like to do in that system (like create a record) and what information it should be updated with (typically, the answers to your form questions). The requirements vary depending on the system you are connecting to, and what you would like to do in it.
- The Response is what the other system sends back to TrueContext; it contains the status of the request (if it was successful or not), information about what happened, and error codes if it didn't work. The response will vary depending on the system you are connecting to.
Request
HTTP Method
TrueContext supports PATCH, POST, and PUT HTTP methods.
- POST: POST uses data from a submitted form to create an object in an external system.
- PUT: PUT uses data from a submitted form to replace an existing object in an external system.
- PATCH: PATCH uses data from a submitted form to update or modify an object in an external system
An object may be as simple as a line of data in a database.
Which method should I use?
If you're using a system with a publicly documented API, the documentation should tell you which method you need to use for the request you are trying to make.
URL Suffix
Enter the URL for the endpoint you want to send data to. You can use a DREL Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms. expression to dynamically generate the URL.
Info:If you use a DREL expression to generate the URL, remember to escape the data you reference. This ensures that the system URL encodes the output generated by the DREL expression.
Request Headers
Include any necessary request headers based on your third-party system’s API documentation specifications, except for authentication headers.
Note:Use an HTTP Connection to authenticate instead of Data Source Data sources, also known as "Lookups", are external sources of data that you upload or connect to TrueContext. You can reference this data in a form to populate answers or answer options. Data sources save typing, reduce errors, and make it easy to provide mobile users with only the relevant, most current data. or Data Destination headers. This keeps credentials and authentication values secure. The topic HTTP Connection includes a list of supported authentication methods.
Building Request Headers
-
Key: The name of the header
-
Value Expression: The value. This can be static. If this needs to be dynamic, and based on the answer to question, use Data Reference Expression Language to choose the data to send. Use the answer to a question by referencing Unique IDs.
Request Body
The Request Body specifies the actual data you will be sending through the data destination. This is usually what contains the actual answers from your form.
There are two methods to define a Request Body:
- POST Parameters (only available for the POST method)
- A separate JSON or XML file containing the Request Body
POST Parameters
Only use these options if you are NOT sending a separate JSON or XML file containing the request body. All of these parameters will be ignored if you attach a document.
When used, these parameters will be sent in the request body in a url-encoded format.
Send all answers
If using POST, selecting this option will automatically add all of the submission's answers to the POST request. This eliminates the need to reference questions individually in the "POST Parameters" section below.
POST Parameters
These parameters are only displayed when using the POST method. Use the parameter builder to choose which individual answers to send.
- Key: The name of the POST parameter that the destination will use.
- Value Expression: Use Data Reference Expression Language to choose the data to send. Use the answer to a question by referencing unique IDs.
- Note: Answer values which are binary data (e.g. data from an image capture or signature) are base64 encoded.
Legacy Format
When this option is selected, the information from answered questions will be sent in an legacy format, using the unique identifier for each answer. This format will send all data as a comma-separated string instead of a list of HTTP POST parameters. This option is not recommended for forms containing:
- Attachment data
- Barcode data
- Multiselect questions
- Repeatable sections
Send a Document with the Request Body
In many cases, a JSON or XML document is required by the web end point you are communicating with.
Note: For PUT/PATCH, you must use this method of defining the request body. For POST, you may need to use this, depending on the requirements of the system you are sending data to.
TrueContext has several features that enable this:
- Standard JSON or XML formats, which include every quest/answer in TrueContext standard data format
- Create your own custom JSON or XML formats through DREL, FreeMarker, or Handlebars document template features; include only specific questions, write conditions, and exactly match the data format required by the system you are connecting to
To make use of one of these document generation options with an HTTP destination, follow the instructions to link a document to a data destination.
Response Configuration
HTTP Call Success Analysis
Select which HTTP response codes indicate a successful call. Optionally, you can use a Regular Expression to analyze the HTTP response body to determine success vs. failure. The Regular Expression results in success if the pattern is found anywhere in the body.
Response Data Handling / Response Outputs
HTTP Destinations allow storing and use of the HTTP Response for use with DREL. For more information on Response Data Handling, please read the documentation: Use Response Data Handling to Store Data Received from a Third-Party System.
Testing and Troubleshooting Data Destinations
Data destinations should be configured and tested carefully before using them in production. This is key to ensuring that TrueContextdata is received correctly. Please consult the recommendations for testing and troubleshooting data destinations.
Error Messages
Keep in mind when building a custom integration that TrueContext technical support may have no experience with the system you are integrating with. Most error codes that you see come back to TrueContext from that other system; TrueContext is just surfacing the message back to you.
If you are working with a documented API, refer to that documentation to learn what various error codes mean.