HTTP Data Destination

---

When to use an HTTP Data Destination

Use an HTTP Data Destination when you want to :

• Automate data sharing and storage: Route data collected in the field directly to your customers, back-office systems, or other cloud services.

• Integrate with external systems: Create, replace, or update records in any service with a documented API endpoint that accepts HTTP requests.

  Tip:The HTTP Data Destination supports the use of POST, PUT, and PATCH methods.

• Deploy low-code custom integrations: Connect to a system that can receive HTTP requests but doesn’t have an out-of-the-box TrueContext connection.

• Enable structured data delivery: Deliver information in structured formats such as JSON or XML, which are often required by APIs and cloud services.

• Set up chained workflows: Use the response from one system (such as a record ID or URL) in subsequent, automated steps. This enables more complex, multistep integrations, such as creating a record in one system and then sending a notification or storing a file in another.

Typical scenarios include:

• Pushing data to a CRM, ERP, or ticketing system immediately upon submission.
• Sending data to a custom web service for further processing or storage.
• Triggering workflows in other business systems based on field data collection.

---

Step-by-Step: Set up an HTTP Data Destination

Prerequisites

• You must have Admin or Can Create permissions in your FormSpace FormSpaces are where forms are stored and organized in the TrueContext Web Portal. A TrueContext Team may have multiple FormSpaces, depending on their needs. Admins can set FormSpace permissions to control which users have access to the forms in that FormSpace..
• Your team needs an HTTP Connection set up in TrueContext.
• Your team must be on the Advanced or Enterprise tier.
• You must know how to work with your third-party API and understand the structure of HTTP requests and responses.

---

Create or Edit the Data Destination

1. Go to Forms & Integrations > Data Destinations.

   • To create: Select Create Data Destination and choose the HTTP type.

   • To edit: Select the existing Data Destination and choose Edit Data Destination.

Set up Destination Basics, Filtering, and Connection

• Follow the guidance in the topic Creating and Managing Data Destinations

Set up the request

1. On the Request Configuration tab, choose the HTTP method. The method depends on your external system requirements, which you can find in their API documentation.

   • POST: Create a new object.

   • PUT: Replace an existing object.

   • PATCH: Update (modify) an existing object.

2. In the URL Suffix field, enter the value to add to the Connection Base URL.

   Tip: The Base URL is the part of an API endpoint that all endpoints for a system have in common. You specify the Base URL in the Connection, and then you specify endpoints in Data Sources 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. and Destinations. This way, you can reuse your Connection for multiple integrations with the same system.

   For example, if your API endpoint is https://api.thirdparty.com/1.0/data/{dataId}, then your Base URL is https://api.thirdparty.com/.

   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 generate the suffix.

   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.

3. Set up the Request Headers key-value pairs that your system requires.

   Note:Do not include authentication headers here—use an HTTP Connection for authentication.

   For example:

   Key	Value	Purpose
   Content-Type	application/json; charset=utf-8	Tells the server the request body format (JSON, in this example).
   Accept	application/json	Tells the server how to format the response.
   Date	Wed, 01 Oct 2023 00:00:00 GMT	Indicates the date/time of the request.

4. Set up the request body. Did you select PUT or PATCH as the HTTP Method?

   • If yes, you’ll need to create a JSON or XML document that contains the request body. You can use a standard format (all answers) or custom templates (DREL, FreeMarker, or Handlebars) to match the external system requirements.

     Tip:To use a document for the request body, attach the document when you add the destination to a form.

     Go to the section Response Configuration.

   • If no, and you selected the POST method, you can choose how you want to set up the request body.

     Option	How It Works	When to Use	Advantages	Limitations
     Automatically send all answers using POST Parameters	All answers from the submitted record are automatically included as URL-encoded key-value pairs in the POST body. No need to reference individual questions.	When you want to send all answers as POST parameters and don’t need a custom structure.	Fastest setup Ensures all answers are included No manual mapping needed	Can’t exclude specific answers, not suitable if you need a custom data structure.
     Use the legacy format	With the option to automatically send all answers selected, you can use the legacy format to send all answers as a single, comma-separated string using unique IDs for each answer, rather than as individual POST parameters.	Rarely, only for backward compatibility with older systems that require this format.	Compatible with legacy integrations.	Not recommended for forms with: Attachments Barcode data Multiselect questions Repeatable sections
     POST Parameters (manual selection)	Use the parameter builder to specify which answers to include. Each parameter has a key (name) and a value expression (using DREL to reference specific answers). Binary data is Base64-encoded.	When you need to send only selected answers or map answers to specific parameter names.	Can be used with the automatic option to override the automatic parameter mapping More control over which answers are sent and how they’re named Supports dynamic mapping using DREL to reference values from a submitted record	Requires manual setup More complex for large forms Must maintain mapping if the form changes
     Attach a Document that defines the request body	Attach a JSON or XML document as the POST body when you add the destination to a form. You can use a standard format (all answers) or custom templates (DREL, FreeMarker, or Handlebars) to match the external system’s requirements.	When the receiving system requires data in a structured document (JSON/XML).	Highly customizable format Can include and exclude specific data based on conditional statements Supports complex structures and Supports embedding another document as a string of Base64-encoded bytes—use the documents() function in a FreeMarker template for a JSON document	More setup required Must create and maintain templates Not available for legacy endpoints that expect only parameters

     Tip:To use a document for the request body, attach the document when you add the destination to a form.

---

Response Configuration

1. Set the success criteria using the following options:

   • Select the HTTP response codes that indicate success.

   • Define a regular expression to match content in the response body. The request is considered successful if the pattern is found anywhere in the response body.

   If you use both, the request is successful if either condition is met.

2. Set up Response Data Handling. TrueContext can use stored responses from the external system for use in other Data Destinations.

---

Testing and troubleshooting

• Always test Data Destinations before production use to ensure correct data transfer.
• Most error codes come from the external system and are surfaced by TrueContext. Consult the external system API documentation when you need to interpret an error.

---