Form JSON Definitions

Example

An example Form definition file is shown below.

form-def.json

{
    "name": "Loan App",
    "formCode": "loan-app",
    "transactInsights": false,
    "logFormXml": false,
    "currentFormVersionNumber": "1.0.0",
    "trackingReceiptNoMode": "Tracking Code Only",
    "formSpaces": [
        {
            "name": "Web Plug-in",
            "anonAccess": true,
            "authAccess": true
        }
    ],
    "formGroups": [
        {
            "name" :"Job Reviewers",
            "description" :"Authorized Job Reviewers",
            "reassignTask" : false,
            "savedAssignedForm" : true,
            "completedForm" : true,
            "newForm" : false,
            "workGroupShare" : true
        },
        {
            "name" :"Job Managers",
            "description" :"Authorized Job Managers",
            "reassignTask" : false,
            "savedAssignedForm" : true,
            "completedForm" : true,
            "newForm" : false,
            "workGroupShare" : true
        }
    ],
    "formVersions": [
        {
            "versionNumber": "1.0.0",
            "formType": "Maestro Form",
            "usesFormFunctions": true,
            "unifiedAppData": true,
            "formDataEncryption": true,
            "strictHeaderSecurity": true,
            "maxAttachmentsNumber": 10,
            "maxAttachmentsSize": 5242880,
            "formVersionFile": "home-loan-v1.0.0.zip",
            "formDataConfig": {
                "formDataFile": "formdata.xml",
                "contactEmailXPath": "//Email",
                "dataExtractMapping": [
                    {
                        "name": "First Name",
                        "xpath": "//FirstName",
                    },
                    {
                        "name": "Last Name",
                        "xpath": "//LastName",
                    },
                    {
                        "name": "Email",
                        "xpath": "//Email",
                    }
                ],
                "requestParamPrefillMapping": []
            },
            "attachmentRules": [
                {
                    "name": "Drivers License",
                    "fileTypes": "*.pdf, *.jpg, *.png",
                    "maxNumber": 2,
                    "maxSize": 10485760,
                    "required": true
                }
            ],
            "formFunctions": [
                {
                    "name": "GetAccounts",
                    "version": "1.0.0",
                    "trigger": "Form Function",
                    "sequence": 1
                },
                {
                    "name": "StpDelivery",
                    "version": "1.0.0",
                    "trigger": "User Submit",
                    "sequence": 1
                },
                {
                    "name": "PrefillFunction",
                    "version": "1.0.0",
                    "trigger": "Form Open",
                    "sequence": 1
                }
            ],
            "properties": [
                {
                    "name": "Form Description",
                    "dataType": "String",
                    "value": "Maguire New Byers Home Loan Application"
                }
            ],
            "services": [
                {
                    "jobController": {
                        "serviceName": "Loan Application RA Job",
                        "serviceVersion": "1.0.3",
                    },
                    "formSecurityFilter": {
                        "serviceName": "Fluent Form Security Filter",
                        "serviceVersion": "1"
                    }
                }
            ]
        }
    ]
}

Schema

Form definitions must comply with the following schema.

Fields are optional unless otherwise indicated.

Attribute	Type
name	string Required. The form's name. This must be unique for the Organization.
formCode	string (Maximum length 20 characters) Required. A globally unique form code identifier. This value is used in URL parameters, so avoid any characters that would be URL-escaped.
currentFormVersionNumber	string Required. A version number. For general information about version numbers, see Version Attributes.
trackingReceiptNoMode	string Required. The tracking code and receipt number generation mode. This must be one of the following: "Tracking Code Only" "Receipt Number Only"
emailConfirmation	string Required. Whether to send the user a confirmation email when the application is completed. This must be one of the following: "None" "Confirmation" "Confirmation and PDF Receipt" "Link to Receipt" By default, a confirmation email is not sent to the applicant.
transactInsights	boolean Whether Transact Insights analytics event publishing is enabled in the form.
logFormXml	boolean Whether to log the form XML for each background save to the Form Transaction History.
redirectUrlSavePage	string The URL to redirect users to after they have explicitly saved their form application.
redirectUrlConfirmPage	string The URL to redirect users to after they complete their form application.
redirectUrlCancelPage	string The URL to redirect users to if they cancel their form application.
pageTrackingIncludePosition	string Specify the page script position in relation to the HTML markup. "Inside HEAD: Place the script inside the <head> element of the HTML markup. "After HTML: Place the script outside/after the HTML markup. For more information about page tracking, see Configure Form Page Tracking.
pageTrackingScriptFile	string Specify the path to the file containing the page tracking script. For more information about page tracking, see Configure Form Page Tracking.
deliveryChannels	object (DeliveryChannels) Required. Associate delivery channels with the form. Delivery channels are used to deliver submissions in various states.
trackingCodeService	object (TrackingCodeService) Required. Associate a tracking code service with the form. A tracking code service is used to generate tracking codes for form transactions.
formSpaces[]	object (FormSpace) Required. Associate one or more form spaces with the form.
formGroups[]	object (FormGroup) Required. Associate zero or more form groups with the form.
formVersions[]	object (FormVersion) Required. Associate one or more form versions with the form.

DeliveryChannels

Use a DeliveryChannels object to associate delivery channels with the form.

For more information about delivery channels, see Associate a Delivery Channel With a Form.

Attribute	Type
abandonDelivery	string Required. Delivery channel for abandoned submissions. Can be empty.
productionDelivery	string Required. Delivery channel for successful submissions. Use this delivery channel to deliver successful submissions for this form when the form is not in test mode. Can be empty.

TrackingCodeService

Use a TrackingCodeService object to associate a tracking code service with the form.

Attribute	Type
serviceName	string Required. The name of a tracking code service.
serviceVersion	string Required. A version number. For general information about version numbers, see Version Attributes.

FormSpace

Use a FormSpace object to associate a form space with a form.

For information about form spaces, see Form Spaces Overview. For more information about form access, see Configure a Form Space.

Attribute	Type
name	string Required. A form space name.
anonAccess	boolean Required. Whether to allow authenticated users to access forms in the form space.
authAccess	boolean Required. Whether to allow anonymous users to access forms in the form space.

FormGroup

Use a FormGroup object to associate a form group with a form.

For information about form groups, see Form Groups. For information about groups generally, see Create a Group.

Attribute	Type
name	string Required. The form group's name.
description	string Required. A brief description of the form group.
reassignTask	boolean Required. Whether group members can reassign task submissions to other users within the form work group.
savedAssignedForm	boolean Required. Whether group members can share tasks assigned to the group as well as incomplete submissions for the form.
completedForm	boolean Required. Whether group members can share the list of completed submissions and access to receipts.
newForm	boolean Required. Whether users can start a new form belonging to the group.
workGroupShare	boolean Required. Whether users of this work group can share a form.

FormVersion

Use a FormVersion object to associate a form version with a form.

For information about form versions, see Form Versions Overview. For information about form version configuration, see Configure a Form Version.

Attribute	Type
versionNumber	string Required. The form version number. This version number should be sequential for the form and must be unique for the form. For general information about version numbers, see Version Attributes.
formType	string Required. The form type. This must be one of the following: "Maestro Form" "Composer Form"
usesFormFunctions	boolean Required. Whether to use Transact namespace functions.
unifiedAppData	boolean Required. Whether to enable the Unified Application Data Document Model in the form version.
strictHeaderSecurity	boolean Required. Whether to enforce a strict header security policy. For more information about this option, see Configure a Form Version.
formDataEncryption	boolean Required. Whether to use form data encryption. For more information about form data encryption, see Configure a Form Version.
maxAttachmentsNumber	integer Required. The maximum number of file attachments.
maxAttachmentsSize	integer Required. The maximum total size of file attachments in bytes.
formVersionFile	string Required. Path to the form archive (ZIP file) for the form version.
htmlDir	string Path to a JS App form content.
formDataConfig	object (FormDataConfig) Required. A form data configuration.
attachmentRules	object (AttachmentRule) Required. Zero or more attachment rules.
formFunctions[]	object (FormFunction) Required. Zero or more form functions.
services[]	object (Service) Required. Zero or more typed service objects. You can specify the following service types: "jobController": The Job Controller service type. This service is called when a form submission creates a new Collaboration Job. "formSecurityFilter": The Form Security Filter service type, used for custom access control logic. This service is called when a form is rendered, before TM access controllers run. This service type is not available when using form functions. Instead, use a function with the trigger types "Form Open" and/or "Form Resume". "formDataPrefill": The Form Data Prefill service type, used to provide the form with XML prefill data when the form is rendered. This service type is not available when using form functions. Instead, use a function with the trigger types "Form Open" and/or "Form Resume". "submissionPreprocessor": The Submission Preprocessor service type, called when a form is submitted that can review and modify or reject a form submission prior top it being stored. This service is called when This service type is not available when using form functions. Instead, use a function with the trigger type "User Submit". "formSavedProcessor": The Form Saved Processor service type, called when a form is saved online. This service type is not available when using form functions. Instead, use a function with the trigger type "User Save". "submissionDataValidator": The Submission Data Validator service type, called to validate the submitted form XML data. This service type is not available when using form functions. Instead, use a function with the trigger types "User Submit" and/or "Form Update". "submissionCompletedProcessor": The Submission Completed Processor service type, called when a submission changes to the "Completed" form status and no more user steps are required. This service type is not available when using form functions. Instead, use a function with the trigger type "User Submit". "receiptRender": The Receipt Render service type, used to render the form submission PDF receipt. "taskExpiry": The Task Expiry service type, used to invoke processes when tasks expire. "email": The Email service type, used for sending submission-related emails to users.
properties[]	object (PropertyDef) Required. Zero or more version property values.

FormDataConfig

Use a FormDataConfig object to associate a form data configuration with a form version.

For information about form data configuration, see Form Data Configuration Overview and Form Configuration Mapping.

Attribute	Type
contactEmailXPath	string A valid XPath in the form XML data identifying the element where the applicant's contact email address is stored.
saveChallengeXPath	string A valid XPath in the form XML data identifying the Save Challenge element.
dataExtractMapping[]	object (DataExtractMapping) Required. One or more data extract mappings associated with the form data configuration.
requestParamPrefillMapping[]	object (RequestParamPrefillMapping) Required.

AttachmentRule

Use an AttachmentRule object to associate an attachment rule with a form version.

For information about configuring attachment rules, see Configure Form Version Attachment Rules.

Attribute	Type
name	string The file attachment name.
description	string A brief description of the file attachment.
fileTypes	object A comma-separated list of valid file types. For example, "*.pdf, *.jpg, *.png".
maxNumber	number The maximum number of files that can be uploaded for this attachment rule.
maxSize	number The maximum total size of files that can be uploaded for this attachment rule.
required	boolean Whether this file attachment is required to complete the application.

DataExtractMapping

Use a DataExtractMapping object to associate a form data extract mapping with a form data configuration.

Form data extract mappings are used to define form XML values to be extracted when form XML data is submitted. This submission data extract information is summarized in the Form Submission Data view. For information about form data extract mappings, see Form Data Extract Mappings and Form Configuration Mapping.

Attribute	Type
name	string Required. The name of a field in the data extract mapping.
xpath	string Required. A valid XPath identifying the mapping field element.
searchable	boolean Required. Whether to enable searching on encrypted data.

RequestParamPrefillMapping

Use a RequestParamPrefillMapping object to associate a request param prefill mapping with a form data configuration.

Request param prefill mappings are used to map JSON prefill data, request URL parameters, cookie values, and session values into the form XML data model when the form is rendered. This feature is supported in the Self Service Portal and Web Plug-in. For information about request param prefill mapping, see Form Request Parameter Prefill Mapping.

Attribute	Type
paramName	string Required. The name by which this request or JSON parameter is identified.
xpath	string Required. A valid XPath identifying the request param prefill mapping element. The element identified by this XPath contains the request or JSON parameter that will generate the value to prefill into the form XML data.

FormFunction

Use a FormFunction object to associate a form function with a form version.

Form Functions are also known as Fluent Functions. For information about form functions, see Transact Functions Overview.

Attribute	Type
serviceName	string Required. The form function's service name.
versionNumber	string Required. The function version number. For general information about version numbers, see Version Attributes.
trigger	string Required. When the function is called. This must be one of the following: "Form Open" "Form Resume" "Form Update" "Form Ineligible" "Form Function" "User Save" "User Submit" "User Cancel" "Background Delivery"
sequence	number The order that functions with the same trigger are to be executed.

Service

Use a Service object to associate a service with a form version.

For information about services, see Services Overview.

Attribute	Type
serviceName	string Required. The service name.
serviceVersion	string Required. The service version number. For general information about version numbers, see Version Attributes.

PropertyDef

Use a PropertyDef object to associate a property definition with a form version.

For information about properties, see Properties Overview.

Attribute	Type
name	string Required. The property name.
description	string A brief description of the property.
dataType	string Required. The property's data type. This must be one of the following: "Boolean" "CSV" "HTML" "Image" "JSON" "List" "Long Text" "Number" "String"
value	string The property's JSON-encoded value. For large values, externalize to a file and use valueFile instead. Note: Either value or valueFile must be specified.
valueFile	string The path to a file that contains the value for this property. Note: Either value or valueFile must be specified.