JSON Documents

 

 

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. 

Please note that V2 documents are not backwards compatible, i.e., they cannot be attached to V1 forms.  Read more about documents here.

 

admin.pngnouser.pngnomobile.png

Settings 

Create a Document

    1. Documents are created in the web portal, not the Form Builder. To create a document: 

      1. Mouse over the Manage Forms tab and select Documents.  
        nav.png
      2. From the Documents page, select the createdocument.png button.
      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 is the name of the file that will be sent through data destinations.  

      • Use Data Record 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

[ top ]

 

Document Timezone Source

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

      • Team Preference Setting: Will use the time zone chosen for the team
      • Data Record: Will use the time zone the form submission is made from (as chosen on the mobile device).
      • Custom: Choose a time zone.

timezonesource.png

[ top ]

 

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

[ top ]

 

JSON Document Configuration

Form Model Version

V1 forms can only use V1 documents. V2 documents have a different format, and they are only compatible with V2 forms. Select the appropriate Form Model Version from the dropdown. If you do not see this option, it means that ProntoForms will automatically create the correct document version for you.

2017-09-18-CreateV2Doc01.png

[ top ]

 

Embed attachments within the Data Record Document 

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

[ top ]

 

Data Node Format

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

  • Standard: Uses generic, standardized node names for page, section, and question nodes. 
  • Question Labels as Node Names: Uses the question label in place of the generic question/answer node name. 
  • All Labels as Node Names: Uses the page, section, and question labels in place of the generic page, section, and question node names.

2018-01-04-V2FB-DocsDataNodeFormat.png

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 competely compressed, 1 is no compression.

[ top ]

 

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 ProntoForms does not adhere to without these wrappers. An example of this is the Salesforce Apex 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, press "Create."  Link the document to a form in order to use it. 

create.png

[ top ]

 

JSON Document Samples

This section contains examples of the V1 and V2 document output to demonstrate the differences between the two formats. In the full JSON, there will be metadata before the form/page data.

 

V1 JSON:

    "pages": [{
        "name": "Inspection Details",
        "answers": [{
            "label": "Inspection Date:",
            "dataType": "Date",
            "question": "Inspection Date:",
            "values": []
        },
        {
            "label": "Project number",
            "dataType": "FreeText",
            "question": "Project number",
            "values": ["1234569"]
        },
        {
            "label": "Client Name",
            "dataType": "FreeText",
            "question": "Client Name",
            "values": ["Allison Paving Co."]
        }]
    }]

[ top ]

 

V2 JSON: This JSON sample contains data from a Regular section, referred to in the JSON as a "Flow" type.

"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"
                }]
            }]
        }]

 

V2 JSON: This JSON sample contains data from a repeat section output.

"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": []
        }
    }]

[ top ]

 

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

Comments