Skip to main content

Version: 18.05 (EOL)

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 is supported in Transact Manager 17.10 and later releases.

Options​

All options are optional unless otherwise indicated.

OptionDescription
userSavedboolean

Specify whether to set the submission.user_saved flag so that submission abandonment will not occur automatically.

sendEmailSavedFormboolean

Specify whether to send a Form Saved email message to the specified emailAddress parameter.

emailAddressstring

The email address of the recipient of the Form Saved email message.

addAttachmentFileJSON

The add file attachment metadata. See addAttachmentFile Option for details.

addAttachmentManuallyJSON

The add file attachment metadata for an attachment that will be submitted manually. See addAttachmentManually Option for details.

removeAttachmentJSON

The remove file attachment metadata. See removeAttachment Option for details.

milestonestring (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 Transact 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​

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​

The Transact Manager server 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.

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 indicating any validation errors. The form application can then 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"
        }
    ]
}