Form Load

The Form Load command gets the form prefill XML data at page load time. This command is not required for Maestro forms that have the form prefill data injected into the HTML page. This command is intended to support other types of client applications.

Support

Form Init was introduced in Journey Manager 18.11, and continues to be available in later Journey Manager releases.

Options

This command has no request options for standard new transaction flows. For application save resume flow, additional options are documented later.

Example

{
   "type": "formLoad",
   "requestKey": "96b45311175fc320d875483950b2847c"
}

Response

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

200 OK

On a successful response, the server returns form prefill data. If the form is rendered with encrypted form prefill, the returned formData value is also encrypted.

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

400 Bad Request

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

Application Resume / Save Challenge Support

If an application makes a formLoad request for a previously saved application and a save challenge session key has not been established, the server responds with an HTTP 401 Unauthorized status code with the following JSON message:

401 Unauthorized

{
  "error": "formLoad Save Challenge Required",
  "errorKey": "stdErrs.formSaveChallengeRequired"
}

The basic flow is: if the app understands that save challenge will be required based on the trackingCode URL parameter, then it should show a Save Challenge modal dialog before attempting to load form data. For example:

http://localhost:9080/maguire/app/springboard-app/?trackingCode=6MYD2M

If the URL contains a submitKey the application can assume the TM server has setup the save challenge credentials and a formLoad call can be made.

http://localhost:9080/maguire/app/springboard-app/?submitKey=d76530c5e3a24d50ebb9923e71ed89f2

If the trackingCode is provided in the URL, this value should be used to prefill the save challenge command options. Once the user has provided a standard save challenge answer, this can be specified as a saveChallengeAnswer command option. For example:

{
    "type": "formLoad",
    "requestKey": "96b45311175fc320d875483950b2847c",
    "options": {
        "saveChallengeAnswer": "0438928123",
        "trackingCode": "6MYD2M"
    }
}

In the scenario where a user is opening a different existing saved form (transaction) inside a form, they would specify an alternative trackingCode command option.

For example:

{
    "type": "formLoad",
    "requestKey": "96b45311175fc320d875483950b2847c",
    "options": {
        "saveChallengeAnswer": "0438928123",
        "trackingCode": "8WQLBLB"
    }
}

Alternatively, if the form has a series of custom parameters, this can be specified as a parameters object; for example, a mobile SMS PIN token. Note that a trackingCode must still be specified to identify the correct transaction.

{
    "type": "formLoad",
    "requestKey": "96b45311175fc320d875483950b2847c",
    "options": {
        "trackingCode": "8WQLBLB"
    },
    "parameters": {
        "PIN": "333987"
    }
}

This command type gets the form prefill XML data at page load time. This command is not required for Maestro forms that have the form prefill data injected into the HTML page. This command is intended to support other types of client applications built using other JS frameworks.

Options

Name	Description
saveChallengeAnswer	string The save challenge answer. For example, "0428 914 225".
trackingCode	string The tracking code or reference number. For example: "S2NVWQL". Use this value when presenting a user with a dialog to open another previously saved form.

Response

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

200 OK

On a successful response, the server returns form prefill data. If the form is rendered with encrypted form prefill data, the returned formData value is also encrypted.

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

200 - Standard Errors

If a standard error occurs, a JSON error message is returned with one of the following errors.

errorKey	Description
stdErrs.formTrackingCodeNotFound	The transaction specified by the tracking code was not found.
stdErrs.formSaveChallengeInvalidAnswer	The specified save challenge answer for the tracking code was not correct.
stdErrs.formSaveChallengeTimeout	The save challenge timeout has been exceeded, and no further attempts will be accepted.

An example validation error is shown below.

{
    "formStatus": "Saved",
    "validationErrors": [
        {
            "errorKey": "stdErrs.formSaveChallengeInvalidAnswer"
        }
   ]
}

200 - Error Customized

A "Form Save Challenge" trigger type function can be configured which, when called, handles a save challenge with custom parameters. The options.saveChallengeAnswer is not passed to the server side Transact Function.

{
    "formStatus": "Saved",
    "validationErrors": [
        {
            "errorKey": "missingPinNumber"
        }
   ]
}

200 - Redirect User

In the scenario where a user opens a form and then opens a dialog to resume a previously saved form with a different trackingCode, the server redirects the user to the other form transaction if it is found and is saved. The server in this case does not attempt to validate the saveChallengeAnswer or parameters. The application should redirect the browser to the new URL which will load the new form version (which may be completely different). If the URL contains a trackingCode parameter, the application should display a save challenge dialog with the trackingCode prefilled.

{
    "formStatus": "Saved",
    "redirectUrl": "https://maguire.com/web-plugin/app/doa/1.0.1/?trackingCode=8WQLBLB"
}