JSON Documents

Contents

About

Output data from your submitted forms in a JSON format, perfect for integration with your backend system. There are different options for structuring and customizing your JSON format.

JSON documents can be sent to cloud and enterprise services, web services, and more. A number of document types are available, and multiple documents can be sent with a single form submission.

Note:If a JSON document is linked to a Multi-Language Form, the document displays in the languages configured when attached to a Data DestinationClosed 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.. The document shows translated form content based on the form’s translation file. The key names and question Unique IDs don’t change. For your integrations, map to the question Unique IDClosed A Unique ID refers to the specific identifier of a question, form page, form section, or Data Destination. Unique IDs are used as reference points when pulling data for conditional logic, Analytics projects, Data Destinations, and Documents., which doesn’t change, and not the question text.

Settings

Create a Document

Documents are created in the Web Portal, not the Form Builder. To create a document:

  1. Hover over Forms & Integrations, and then select Documents.

    The Forms & Integrations menu with Documents highlighted.

  2. From the Documents page, select Create Document.

  3. Choose a document type.

  4. Fill out the details required for your document type.

Document Basics

Name/Description

Give the document a unique name. Optionally provide a description.

Filename

This name applies to all instances of the document, including downloaded documents and documents sent by Data Destinations.

Tip:A recognizable file name can help you quickly search for and identify files when:
  • You download files from multiple form submissions so that you can work locally.

  • You or your customers receive multiple messages generated by Email Destinations.

  • Use Data Reference Expression Language to reference answers in your forms.
  • Static text can also be included.
  • For example, %r -- %a[Customer Name] would name the file like "20140812-180001002 -- John Smith."

filename.png

  • Some data destinations will overwrite files with duplicate names. Make sure file names are unique by including one or more of:
    • %r - the submission's reference number -- e.g. 20140920-1815562464
    • %r[id] - the submission's ID - e.g. 1815562464
    • %t - the time the form was submitted

Document Time Zone Source

Choose a document time zone source. This is the time zone for the shifted dates and times in your document.

  • Team Preference Setting—Displays times using the Team Time Zone. This applies to the shifted time and not the provided time.

  • Form Submission—Displays times using the device time zone.

    Note:The device time zone refers to the device setting, not the user profile locale settings in the TrueContext Mobile App account details.

  • Custom—Choose a time zone. Custom time zones apply to the shifted time and not the provided time.

Document Time Zone Source

Auto-Link new forms to this document

Selecting this option will add the document as an "Additional Document" to forms created or imported after this option is set. Submissions made against these forms will be downloadable in this document format from the "Data" tab of the portal.

autolink.png

JSON Document Configuration

Form Model Version

We currently support v2 forms only:

  • If you still have a v1 document set up, you can change it to v2. Once you change the Form Model Version to v2, you can't change it back.
  • If this is a v2 document, the Form Model Version won’t be displayed.

Embed attachments within the Form Submission Document

This will include the attachment "bytes" property, which is necessary if you need to use the images collected at any point.

Data Node Format

This setting changes how the nodes containing question/answer information are named.

Choose one of the following options:

  • Standard—This option provides the form elements in an array that you can loop over. Use this option when you want to apply generic logic to all elements of your form.

  • All Labels as Node Names—Uses the page, section, and answer unique IDs (labels) instead of the generic names.

    Tip:This option gives you precise labels you can use to reference specific nodes in the submitted record. Use this option when you want to place specific answers in specific places in your template output. The examples in this topic all use this setting.

  • Flat Answer List—Changes the hierarchical tree structure into a flat data structure (list). Use this option when you want to loop over answers and don’t need to reference the full form structure (pages, sections, or Repeatable Sections).

For more details on these options, please read: Form Submission Formats: Standard vs. Labels as Node Names.

Image Compression Ratio

Enter a value between 0 and 1 to compress images embedded in this document. Compression will reduce the size of the document, at the cost of image quality. 0 is completely compressed, 1 is no compression.

Wrapping JSON Options

If your downstream service requires that JSON documents be wrapped in either a JSON object or array, select the appropriate option. You may need to use this option if the endpoint is not built by you, and may have requirements for the incoming data that TrueContext does not adhere to without these wrappers. An example of this is the Salesforce Apex REST Data Destination.

2017-09-18-JSONDocOptions01.png

Example Wrapped Outputs

JSON Object = on, JSON Array = off
"<JSON Object Name>" : {
{ <data record json> }
}
JSON Object = off, JSON Array = on
[
{ <data record json> }
]
JSON Object = on, JSON Array = on
"<JSON Object Name>" : { [
{ <data record json> }
] }
JSON Object = off, JSON Array = off
{ <data record json> }

When set up is complete, select Create. Link the document to a form in order to use it.

"Create" and "Cancel" an event document

JSON Document Samples

The following examples show the structure of Regular and Repeatable SectionClosed A Repeatable Section is a subform that contains a set of related questions. The data captured is “repeating”, because the field user can complete the same subform more than once, which creates multiple entries. data and metadata in a JSON document.

Note:Changes to the JSON Format:

For TrueContext REST APIs and JSON/XML document formats, we maintain a practice of not deleting existing properties or objects. A mechanism for versioning is used to facilitate deletions to our JSON/XML formats when necessary. Customers will be contacted in advance if they will be affected.

We will occasionally, however, add new properties to existing APIs to support new features in the TrueContext Platform. We do not create a new version of our APIs for new properties, and we advise that clients of our APIs are resilient to additions by ignoring unknown properties. Client applications should ignore any properties that are not relevant to their use case.

JSON example of a Regular Section

This JSON example contains data and metadata from a Regular SectionClosed A Regular Section is a set of related questions grouped together for easy reference. The data captured is “non-repeating”. That is, field users enter a single instance of each answer., referred to in the JSON as type “Flow”.

"pages": [{
        "label": "LI",
        "name": "Labor Information",
        "sections": [{
            "type": "Flow",
            "label": "WP",
            "name": "Work Performed",
            "answers": [{
                "label": "DescWork",
                "dataType": "FreeText",
                "question": "Description of Work",
                "values": ["This is another test description."]
            },
            {
                "label": "Comments",
                "dataType": "FreeText",
                "question": "Comment(s)",
                "values": ["This is another test comment. "]
            },
            {
                "label": "PoI",
                "dataType": "Image",
                "question": "Photos/Sketch of Interest",
                "values": [{
                    "identifier": "7da58b3b-cb3e-4895-8b8e-a9a3f6bc9f9f",
                    "filename": "PoI_1.jpg",
                    "contentType": "image/jpg"
                }]
            }]
        }]

JSON example of a Repeatable Section

This JSON example contains data and metadata from a Repeatable Section, referred to in the JSON as type “Repeat”.

"pages": [{
    "label": "Job Information",
    "name": "Job Information",
    "sections": [{
        "type": "Repeat",
        "label": "Equipment details",
        "name": "Collect details about equipment",
        "rows": [{
            "pages": [{
                "label": "ED",
                "name": "Equipment Details",
                "sections": [{
                    "type": "Flow",
                    "label": "New Section 3",
                    "name": "null",
                    "answers": [{
                        "label": "Make",
                        "dataType": "FreeText",
                        "question": "Make",
                        "values": ["Equipment Make 4"]
                    },
                    {
                        "label": "Model",
                        "dataType": "FreeText",
                        "question": "Model",
                        "values": ["4A"]
                    },
                    ]
                }]
            }{
                "label": "ED",
                "name": "Equipment Details",
                "sections": [{
                    "type": "Flow",
                    "label": "New Section 3",
                    "name": "null",
                    "answers": [{
                        "label": "Make",
                        "dataType": "FreeText",
                        "question": "Make",
                        "values": ["Equipment Make 3"]
                    },
                    {
                        "label": "Model",
                        "dataType": "FreeText",
                        "question": "Model",
                        "values": ["2A"]
                    },
                    ]
                }]
            }]
        }]
"footer": {
            "answers": []
        }
    }]