Form Update

The Form Update command performs a form-initiated background save (update) operation. This command may be initiated for any number of reasons.

• Page change save
• Milestone completion
• Add an attachment
• Specify an attachment to be added manually
• Remove an attachment

Support

Form Update was introduced in Transact Manager 17.10, and continues to be available in later Transact Manager and Journey Manager releases.

Options

All options are optional unless otherwise indicated.

Option	Description
userSaved	boolean Specify whether to set the submission.user_saved flag so that submission abandonment will not occur automatically.
sendEmailSavedForm	boolean Specify whether to send a Form Saved email message to the specified emailAddress parameter.
emailAddress	string The email address of the recipient of the Form Saved email message.
addAttachmentFile	JSON The add file attachment metadata. See addAttachmentFile Option for details.
addAttachmentManually	JSON The add file attachment metadata for an attachment that will be submitted manually. See addAttachmentManually Option for details.
removeAttachment	JSON The remove file attachment metadata. See removeAttachment Option for details.
milestone	string (Maximum length 100 characters) A transaction milestone event to record with the transaction. Milestones are used to store transaction analytics information only. Do not store sensitive or PII data in milestones. These milestones are recorded in the transaction history table for business reporting, and are also published to the Journey Manager licensing service to support custom licensing agreements.

Example

An example formUpdate command JSON is shown below. This example:

• sets the submission.user_saved flag so that automatic submission abandonment will not occur;
• adds a Form Saved email to the email queue, using the email address specified in the form data and the configured Contact Email Address XPath; and
• records a Contact Details Completed milestone event against the transaction.

{
   "type": "formUpdate",
   "requestKey": "96b45311175fc320d875483950b2847c",
   "options": {
      "userSaved": true,
      "sendEmailSavedForm": true,
      "milestone": "Contact Details Completed"
   }
} 

addAttachmentFile Option

Use the addAttachmentFile option if the save command also contains a file attachment to add to the transaction. The metadata specified in the addAttachmentFile object is the same as the existing HTTP Form API addAttachmentFile object but with two new members.

• path - Specifies the form data element path. This is used when returning validation errors to the client if the addAttachmentFile operation fails.
• attachmentKey - A file attachment GUID which will be used to store the new file attachment in TM.

{
    "type": "formUpdate",
    "requestKey": "96b45311175fc320d875483950b2847c",
    "options": {
        "addAttachmentFile": {
            "path": "/SmartForm/Applicant/IDV/Passport",
            "attachmentKey": "37960fb77666702f1227966859fc9678",
            "attachmentName": "Drivers License",
            "description": "This is my current drivers license",
            "maxSize": 1048576,
            "fileTypes": "*.jpg, *.gif, *.png"
        }
    }
}

If the Form Version has attachment rules specified on the server, then validation rules do not need to be specified in the addAttachmentFile element. In this case, the command request is simplified.

{
    "type": "formUpdate",
    "requestKey": "96b45311175fc320d875483950b2847c",
    "options": {
        "addAttachmentFile": {
            "path": "/SmartForm/Applicant/IDV/Passport",
            "attachmentKey": "37960fb77666702f1227966859fc9678",
            "attachmentName": "Drivers License",
            "description": "This is my current drivers license"
        }
    }
}

addAttachmentManually Option

The addAttachmentManually option specifies that the named required attachment will be submitted manually by the user via post, fax or some other method and is not provided as a file attachment with the application.

{
    "type": "formUpdate",
    "requestKey": "96b45311175fc320d875483950b2847c",
    "options": {
        "addAttachmentManually": {
            "path": "/SmartForm/PrimaryApplicant/DriversLicense",
            "attachmentKey": "3e827a3316c1a1cd43c87e746b6c2203",
            "attachmentName": "Drivers License"
        }
    }
}

As with file attachments, the browser form application is responsible for populating the attachmentKey GUID.

removeAttachment Option

The removeAttachment option specifies that the attachment is to be removed from the TM server. This maps to the submission.attachment entity relationship; file_upload child entities associated with the submission.attachment will be deleted as well.

{
    "type": "formUpdate",
    "requestKey": "96b45311175fc320d875483950b2847c",
    "options": {
        "removeAttachment": {
            "attachmentKey": "3e827a3316c1a1cd43c87e746b6c2203"
        }
    }
}

Response

info

The response to this command is based on the standard Open UX API HTTP response. For more information, see HTTP Response.

A response to a formUpdate command may include an optional revisionNumber attribute that specifies the current TM revision number. An example formUpdate JSON response is shown below.

{
   "formStatus": "Saved",
   "revisionNumber": 6
}

Revision Numbers

Manager uses a transaction revision number to ensure that multiple concurrent sessions against the same transaction do not overwrite each other. Attempts to update a transaction with an older revision number will be rejected. Client application code must ensure the revision number is kept up to date.

If the server returns the formData in the response, the revision number will be automatically included in the XML data and a revisionNumber attribute will not be specified.

However if the response does not include the formData then revisionNumber will be specified and the Client application must copy this value in the XML <SystemProfile>/<RevisionNumber> element. For example:

<SystemProfile>
    <RevisionNumber>8</RevisionNumber>
</SystemProfile>

200 OK

On a successful response, the server returns the form data which was stored in the database. The TM services may update the form data; for example, injecting user account details based on an external lookup service. This can then be returned and the Maestro form binds this data into the relevant fields.

info

If the form is rendered with encrypted form prefill, the returned formData value will also be encrypted.

{
    "formStatus": "Saved",
    "formData": ">AvokaSmartForm>>GettingStarted>>Eligible>>AboutYou>>FirstName>..>/AvokaSmartForm>"
}

200 Redirect

The server may specify that the user's browser should redirect to another location; for example, to a third-party payment gateway to complete a payment for the transaction.

{
    "formStatus": "Saved",
    "redirectUrl": "https://www.braintreepayments.com/en-au/"
}

400 Bad Request

On an invalid response, the server sends a JSON error message.

The JSON error message includes any validation errors. The form application can map these validation errors back to the view components that the user needs to address.

{
    "formStatus": "Saved",
    "formData": ">AvokaSmartForm>>GettingStarted>>Eligible>>AboutYou>>FirstName>..>/AvokaSmartForm>",
    "validationErrors": [
        {
            "path": "//SmartForm/GettingStarted/Eligible/ContactDetails/EmailAddress",
            "errorKey": "emailFormat"
        },
        {
            "path": "//SmartForm/GettingStarted/Eligible/ContactDetails/ContactNumber",
            "errorKey": "mandatory"
        }
    ]
}