Form New

The Form New command specifies that a new form transaction and session should be created to support a follow up formLoad command to load the form prefill data, and follow on commands.

This command is provide to support the use case where Journey Manager is not rendering the HTML application, but instead it is being rendered separately by another system such as a Content Management System (CSM) or another application.

Support

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

HTTP Requests

The Form New command should be made using the /app/ path under the hosted portal context. For example, with the Web Plug-in portal this might be:

POST https://apps.mybank.com/web-plugin/app/

If the user is authenticated, the POST call should be made using the /secure/app/ path. For example:

POST https://apps.mybank.com/web-plugin/secure/app/

As with all Open UX API commands, Form New commands should be performed as Mult-Part POST requests that provide improved security posture and support file attachments.

Options

All options are optional unless otherwise indicated.

Name	Description
formCode	string Required (when creating a new transaction). The globally unique application form code identifier to create a new transaction for. For example, "credit-card".
formVersion	string The application form version number to use. For example, "1.0.3". If not specified, the current form version will be used for the transaction.
trackingCode	string The existing application tracking code or reference number. For example, "S2NVWQL". Specify this value when opening a previously saved form application.

Example

The following example creates a new Credit Card form application transaction using the current form version.

{
   "type": "formNew",
   "options": {
       "formCode": "credit-card"
   }
}

The following example creates a new Credit Card form application transaction, using the form version "1.0.3".

{
   "type": "formNew",
   "options": {
       "formCode": "credit-card",
       "formVersion": "1.0.3"
   }
}

The following example opens an existing application specified by the trackingCode. The formCode or formVersion does not need to be specified as they will be resolved from the application transaction.

{
   "type": "formNew",
   "options": {
       "trackingCode": "S2NVWQL"
   }
}

Response

info

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 the existing JSON specifying the form status and the new transaction form session requestKey. Use this requestKey attribute value in subsequent Open UX API commands for the opened form session.

{
   "formStatus": "Opened",
   "requestKey": "96b45311175fc320d875483950b2847c"
}

400 Bad Request

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

404 Not Found

If the form code or form version was not found, an HTTP 404 Not Found status code is returned with a JSON error message.

{
  "error": "Form Not Found",
  "errorKey": "stdErrs.formNotFound"
}