iFormBuilder Data

Table of Contents

• What is Post Data?
• How do I create a Post Data endpoint? 
• Endpoint Modes
• How do I edit a Post Data endpoint?
• How do I delete a Post Data endpoint?
• How do I add a digital signature (secure signature) to my form data?
• JSON v10 Post Data Change
• How do I create a Post Data endpoint with the original interface?
• What are the differences between JSON v9 and JSON v10?

What is Post Data?

Post Data is similar to the e-mail report in that it pushes a copy of the record data out of iFormBuilder to a user-defined web page (while maintaining the original record on the iFormBuilder database). This action takes place every time a new record is successfully uploaded to the server, or an existing record is updated. 

As of Dec. 6, 2022, we have created a new post data endpoint interface. The original version will still be available for a few more months. You can view instructions at the bottom of the page.

How do I create a Post Data endpoint?

To create a Post Data endpoint, please follow the instructions below.

STEP 1. From the admin portal, hover over the Forms tab and select Form Builder. If you have the new mega menu, go to Forms and then select Form Builder.

STEP 2. There are two ways of accessing the new Post Data Endpoint interface.

Search for the form you want to add a post data endpoint to and click on the post data endpoint icon as seen below.

You can also get to the post data endpoint interface by going inside of a form and clicking the post data endpoint icon on the top right.

STEP 3. Click on the (+) plus sign icon.

STEP 4. Enter the details of your endpoint.

• Name: The name of the POST service.
• Endpoint URL: The address iFormBuilder will send data to when a record is called for POST process
• Post Data Format: The data format you want to be delivered to the endpoint (XML, JSON).
• Post Body Content Type: Encoding format of the data being sent to the endpoint. Options will vary depending on Post Data format.
• Use Labels: With this option turned on, the data will use the column labels as tags instead of data column names.
• Mode: An endpoint mode is what triggers data to be sent.  There are three different modes that can be selected: Insert/Update, Assign, and Delete.
• Error Email: An e-mail address that will receive an e-mail if the request fails after the number of retries is exceeded (5 days).
• Notification Email: An e-mail address that will receive an e-mail each time a request fails with a 400 or 500 level code and has not exceeded the maximum number of tries for Guaranteed Delivery.
• Guaranteed Delivery: With this option turned on when a POST request fails to reach the destination, it will be returned to a queue and will try again with the following schedule (1 minute, 5 minutes, 30 minutes, 6 hours, 24 hours).
• Request Time Limit: The amount of time before a request times out. The default is set to 10 seconds.
• Trigger Post Email: An e-mail address that will receive an e-mail when the Trigger Post Process has been completed (with guaranteed delivery enabled).
• Secure Signature: Digital Signature is a signing mechanism that when data is sent from our system to the endpoint, the receiver can validate the data being processed is in fact from the correct source, and not an imposter. You can now view a preview of the signature key under Read Only Signature Key.

PLEASE NOTE: 

• As of October 2018, we have removed access to Guaranteed Delivery and Request Time Limit to all users except for those with Server Admin access.
• JSON v1 and XML v1 are no longer supported for the new post data endpoints that you want to create from this interface. However, if you already have one, you can continue using it.
• For "Error email", "Trigger Post Email", "Notification Email", the maximum number of emails that can be entered is 5.

STEP 5. Click Save.

PLEASE NOTE: With a dedicated database, you are able to post data to multiple endpoints. By allowing for more than one POST destination, data from records can meet multiple needs instead of just one. If you are using app.iformbuilder.com, then you are only allowed 1 post data endpoint per form.

Endpoint Modes

As mentioned above, there are three endpoint modes to choose from: Insert/Update, Assign and Delete. Each of the post will have a 'hook-action' inside a header.  The hook action will tell you which mode has sent the data.

Insert/Update: This means that every time a record is uploaded from a device or edited in the admin console, it will send a post to the endpoint.  API does not automatically trigger this on POST or PUT requests. You will need to do a trigger post processing call for those records to be sent.

Assign: Anytime a record is assigned, it will send a post to the endpoint. The record can be assign through mobile, admin console, webforms or API.  All of them will trigger this post. The data will be the same as Insert/Update but it will also contain additional data called 'assign_params'.  It will look something like: 

     "assign_params": {

        "DEST_PAGE_ID": 6819,

        "DEST_USER_ID": [81649,12345],

        "TOTAL_COUNT": 4,

        "GLOBAL_ASSIGN_ID": "iForm-6819-81649-16fbfc531888",

        "MODE": "assign",

        "TIME_OF_ASSIGNMENT": "2021-03-26 21:48:21",

        "PROFILE_ID": 12345

      }

DEST_PAGE_ID is the page that's being assigned. DEST_USER_ID is the array of users that the record is being assigned to. TOTAL_COUNT is the record count of all the records that was assigned in the same call. GLOBAL_ASSIGN_ID is a unique id that's tied to all the assigned records that was made in one call. TIME_OF_ASSIGNMENT is when the record(s) was actually assigned. PROFILE_ID is the profile that it is assigned in.

Delete: Whenever a record is deleted, it will send data to that endpoint.  

How do I edit a Post Data Endpoint?

Inside the Post Data Endpoint interface of the form of your choosing, click on the pencil icon to the left of the endpoint to edit.

If you have post data endpoints from the legacy interface, you will be able to view and edit them here.

How do I delete a Post Data Endpoint?

STEP 1. Inside the Post Data Endpoint interface of the form of your choosing, click on the pencil icon to the left of the endpoint to edit.

STEP 2. Click on the DELETE button.

STEP 3. A prompt will appear asking you to confirm the deletion. 

How do I add a digital signature (secure signature) to my form data?

We have a separate article on how to add a secure signature that you can view here.

JSON v10 Post Data Change

As of January 14, 2021

We changed a longstanding behavior in iForm Post Data endpoints that use the JSON v10 format. Currently, numeric data types (Number, Counter, Range, Timer) post a value of zero “0” when the field is null. This is different than our v9 format which correctly posts “null”. To ensure data is correctly reported, we will be changing the behavior of JSON v10 endpoints to post a value of “null” when the field is empty. This change will affect all customers.  We understand that previously collected data may have been inaccurately reported on and existing integrations may need to be updated as a result of this change and are here to help.

Please see the attached PDF in the article linked above explaining in more detail what changes were made. If you have any additional questions, we are here to help.

How do I create a Post Data endpoint with the original interface?

STEP 1. From the admin portal, hover over the Forms tab and select Form Assignment.

STEP 2. Highlight the form you'll be working with and click Assign.

STEP 3. Scroll down to the Post Data section and click + New Endpoint.

STEP 4. Enter the details of your endpoint.

STEP 5. Click Create Endpoint.

What are the differences between JSON v9 and JSON v10?

A similarity that we want to note is that both are nested in an array.

"ID":
"PARENT_RECORD_ID":
"PARENT_PAGE_ID":
"PARENT_ELEMENT_ID":

"id":
"parent_record_id":
"parent_page_id":
"parent_element_id":

"CREATED_DATE": "2023-09-19 16:25:57",

"created_date": "2023-09-19T16:25:57-04:00",

"ID": "1",
"PARENT_RECORD_ID": "0",
"PARENT_PAGE_ID": "0",
"PARENT_ELEMENT_ID": "0",

"id": 1,
"parent_record_id": 0,
"parent_page_id": 0,
"parent_element_id": 0,

"location": {
  "type": "point",
   "coordinate": [
      28.230974,
      -82.674688

[
  {
    "record": {
      "ID": "1"
    },
    "location": {}
  }
]

[
  {
    "id": 1
  }
]