Open UX HTTP API

The Form HTTP API uses multi-part POST messages for all communications.

HTTP Request

The request fields are as follows. All fields are optional unless otherwise indicated.

Field	Description
command	String Required. A JSON command message.
formData	String Form XML data which, by default, is compressed and encrypted.
fileAttachment	String A file attachment for Form Update commands which is neither compressed nor encrypted.

Request Command Message

The request command message specifies the form operation to be performed. The following example message shows the general structure of a request command message.

{
   "type": "type",
   "requestKey": "96b45311175fc320d875483950b2847c",
   "options": {
      "opt name": "opt value"
   },
   "parameters": {
      "param name": "param value"
   }
}

Field	Description
type	String Required. An Open UX command type. This must be one of the following. "formError": A form-initiated operation to make a record in the server Error Log of an unexpected JavaScript error that occurs in the form. "formFunction": A form-initiated call to execute a named Fluent Function service, providing equivalent functionality to a Form Dynamic Data call. "formIneligible": A form-initiated operation to abandon a transaction for a user that has been determined to be ineligible to complete the form. "formInit": A form-initiated operation to record when the form has finished initializing and is ready for user interaction. "formStart": A form-initiated operation to record the user form start. The form should send this message when the user has first completed a field on the form. "formUpdate": A form-initiated background save operation; for example, page change, script-based, timer-based, milestone, attachment operation. "userCancel": A user-initiated form abandonment operation. The form should display a Cancel Confirmation modal page after this operation. "userSave": A user-initiated save and close operation. The form should display a Save Confirmation modal page after this operation. "userSubmit": A user-initiated submit operation. The form should display a Submission Confirmation modal page after this operation.
requestKey	String A form session UUID which also serves as a session-scope anti-CSRF token.
options	String Options for the command type in the form of name/value pairs. The available options for each command type are listed in the command's documentation.
parameters	String Arbitrary parameters in the form of name/value pairs. Parameters can be used for dynamic calls or custom code.

An example userSave command is shown below.

{
   "type": "userSave",
   "requestKey": "96b45311175fc320d875483950b2847c",
   "options": {
      "sendEmailSavedForm": true,
      "emailAddress": "[email protected]"
   }
}

HTTP Response

The Form HTTP API uses standard HTTP status codes.

• 200 Success
• 400 Bad Request
• 401 Not Authorized
• 500 Internal Server Error

note

Only operations with a 200 Success status code are successful in committing changes to the server. For all other HTTP status codes, changes to the transaction are not stored.

Error Messages

A standardized JSON error message format is used for all command errors. The message has two parts. The first message part consists of error messages that are generally not recoverable in the form session. The second message part is a validation error message that the user can deal with in the form. Validation errors include things like server-side attachment validation rules or server-side data validation rules.

An example non-recoverable HTTP 400 error message that occurs if the form data submitted is malformed is shown below.

{
   "formStatus": "Saved",
   "error": "Form Data Invalid",
   "errorKey": "formDataInvalid"
}

The error message has three components:

• formStatus: The transaction form status.
• error: A general English language error message.
• errorKey: A localization error message key that the form can use to resolve a localized error message for the particular locale of the current form user.

The example HTTP 400 error below indicates the form session has timed out and the user must go through a save challenge flow to resume. The additional redirectUrl field specifies the URL the browser should redirect to.

{
   "formStatus": "Saved",
   "error": "Form Save Challenge Required",
   "errorKey": "formSaveChallengeRequired",
   "redirectUrl": "https://maguire.com/web-plugin/servlet/SmartForm.html?formCode=CCA-MAESTRO&saveChallenge=true&referenceNumber=KSP6KH"
}

An example HTTP 200 form validation error is shown below.

{
    "formStatus": "Saved",
    "validationErrors": [
        {
            "path": "//SmartForm/Applicant/Employment/Attachment",
            "errorKey": "fileAttachmentTooLarge",
            "parameters": {
                "fileSize": 2234991,
                "maxSize": 1048576
            }
        },
        {
            "path": "//SmartForm/Applicant/EmailAddress",
            "errorKey": "emailFormat"
        },
        {
            "path": "//SmartForm/Applicant/Mobile",
            "errorKey": "mandatory"
        }
   ]
}

This error message contains three validation errors.

• An uploaded file attachment is too large: it must be 1,048,576 bytes (1MB) or less but is 2,234,991 bytes.
• Email address data has an email format validation error.
• Mobile data has a mandatory (required value) validation error.

The components of each validation error are as follows.

• path: Required. Specifies the XPath of the data element with the validation error.
• errorKey: Required. Specifies the localized error message key.
• parameters: Specifies optional parameters which can be displayed in a localized error message.