HTTP POST/PUT/PATCH Data Destination

 

About

The HTTP POST/PUT/PATCH Data Destination 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 CRM 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.

[ top ]

 


Basic Set Up

  1. Create the data destination following the instructions here.
  2. Name the destination.  Optionally choose to auto-link forms and documents to this destination.
  3. Add Filtering:  With a filter set up, form submissions will only be sent through the destination if the filter is met.  Read more here.
  4. Connection:Set up an HTTP Connection or choose an existing connection.
  5. Set up the Request/Response Configuration tab as discussed below.

[ top ]

 

Request/Response Configuration

When you are communicating with another system, this is the content of that communication.  

  • The Request is what ProntoForms 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 ProntoForms; 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

ProntoForms supports PATCH, POST, and PUT HTTP methods. 

Screen_Shot_2018-03-01_at_12.31.04_PM.png

  • 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. 


[ top ]

 

Request Headers

Some external systems require you to send additional headers in your request. These provide the system with additional required information that it needs in order to understand your request body.   

For example, here is the API documentation for a 3rd-party system. Note the two -H lines; these are required headers.  

 

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 Record Expression Language to choose the data to send. Use the answer to a question by referencing Unique IDs.

 

Common Request Headers

  • Authorization: For systems that only provide an Authentication token, often they specify that this must be sent as a header.
  • Content-Type:  Many systems require this. It tells the external system what data format they should expect the response body in. 

[ top ]

 

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 Record 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.

POSTparameters.png

 

 

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

2016-03-09-HTTPPOSTLegacy.png

[ top ]

 

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.

ProntoForms has several features that enable this:

  • Standard JSON or XML formats, which include every quest/answer in ProntoForms' 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

[ top ]

Response

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.

[ top ]

 

Testing and Troubleshooting Data Destinations

Data destinations should be configured and tested carefully before using them in production. This is key to ensuring that ProntoForms data is received correctly. Please consult the recommendations for testing and troubleshooting data destinations.


Error Messages

Keep in mind when building a custom integration that ProntoForms technical support may have no experience with the system you are integrating with. Most error codes that you see come back to ProntoForms from that other system; ProntoForms 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. 

[ top ]

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments

  • Avatar
    Andrew Pike

    Is URL-encoding how data is being handled with this HTTP POST method?  If not, what method is being used?

    If URL-encoding is how we're handling the data, is it a safe assumption that it's also using the mutipart/form-data content type as well since we could be dealing with signature images, etc?

    Is there any sample parameter information that could be included for format reference?

  • Avatar
    Sinan Serifov

    HTTP POST uses standard POST formatting, not multipart.

    To send images/signatures, HTTP File Upload is recommended. This sends the entire record in our standard Data Record Document format. Images/signatures/etc are encoded in Base64 in this case. HTTP File Upload performs a standard HTTP request, with the method set to PUT.