Core Client API
Transact API Methods
@transact-open-ux/core provides a set of methods to communicate with the Transact Open UX API.
Use these methods to build your application logic.
isReceipt
A boolean variable that indicates whether the app is being opened in receipt mode
formError
This command type enables recording information about an unexpected JavaScript error in the application and storing this information in the TM Error Log for operational support.
For more information, see Form Error in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
stacktrace | string Required. The JavaScript stacktrace, with \n character for new line delimiters. |
context | string Application state / context information to help understand the context of the error. |
Returns
A Promise containing the response object. For more information, see Form Error > Response in the Open UX API documentation.
formFunction
Make a call to execute a named Fluent Function service hosted on Journey Manager.
For more information, see Form Function in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
serviceName | string Required. The form action service definition name. |
serviceVersion | string Required. The form action service definition version number. |
milestone | string (Maximum length 100 characters) A transaction milestone event to record with the transaction. |
params | object The parameters to the specified form function. This is an object where each key is a parameter name. The object value for that key is delivered as the value for that parameter. |
Returns
A Promise containing the response object. For more information, see Form Function > Response in the Open UX API documentation.
formIneligible
Make a call to the form ineligible operation. The app should display a custom page after this operation preventing the user from performing further work.
For more information, see Form Ineligible in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
formData | object Required. An object tree of the form data; e.g. passed in via a Redux selector. |
milestone | string (Maximum length 100 characters) A transaction milestone event to record with the transaction. |
Returns
A Promise containing the response object. For more information, see Form Ineligible > Response in the Open UX API documentation.
formInit
Call the formInit command.
This command type specifies that the form application is fully initialized and ready for user interaction. The role of this command to provide analytics around the performance of forms and understand how long they take to open, and what the impact is on conversion rate and form starts.
This information will be recorded in the TM Request Log table as a millisecond value between the TM HTML document data streamed completed time and the time the formInit event was received
For more information, see Form Init in the Open UX API documentation.
Returns
A Promise containing the response object. For more information, see Form Init > Response in the Open UX API documentation.
formLoad
Make a call to the form load operation to load the application prefill data at load time. You can also load a saved application via a combination of parameters, see examples below. After the data has been retrieved a form initiated operation will be called.
For more information, see Form Load in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
saveChallengeAnswer | string The save challenge answer. |
trackingCode | string The tracking code or reference number. This value should be used when presenting a user with a dialog to open another previously saved form. |
parameters | object Custom parameters; for example, a mobile SMS PIN token. |
Returns
A Promise containing the response object. For more information, see Form Load Response in the Open UX API documentation.
note
The formData property will be an object instead of XML when returned via the core library.
formNew
The formNew command creates a new form transaction or opens an existing transaction.
This call should be followed by the formLoad command.
This command is provided to support the use case where Journey Manager is not rendering the HTML Open UX application, but instead it is being rendered separately by another system such as a Content Management System (CSM) or another application.
For more information, see Form New in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
requestUrl | string Required. The endpoint which will be used for this call and all subsequent Open UX calls. |
formCode | string The globally unique application form code to create a new transaction for. |
formVersion | string The application form version number to use, if not specified then the current form version will be used for the transaction. |
trackingCode | string The tracking code or reference number. Required when opening a previously saved form application. |
Returns
A Promise containing the response object. For more information, see Fom New > Response in the Open UX API documentation.
formStart
Make a call to the form start operation specifying that the user has started interacting with the form.
For more information, see Form Start in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
formData | object Required. An object tree of the form data; e.g. passed in via a Redux selector. |
milestone | string (Maximum length 100 characters) A transaction milestone event to record with the transaction. |
Returns
A Promise containing the response object. For more information, see Form Start > Response in the Open UX API documentation.
formUpdate
Make a call to the form update operation, this performs an app initiated background save.
Reasons to call this command include:
- Page change save
- Timer based save
- Milestone based save
- Add attachment
- Specify attachment to be added manually
- Remove attachment
The parameters addAttachmentManually, removeAttachment and addAttachmentFile can be specified with appropriate metadata using the associated helper methods, detailed separately in the parameter descriptions below. These parameters should be considered mutually exclusive options, and only one (or none) of them should be provided for any one call. The other parameters can either be omitted (if they appear after any other necessary parameters) or provided with a null or undefined value.
For more information, see Form Update in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
formData | object Required. An object tree of the form data; for example, passed in via a Redux selector. |
userSaved | union: false | true Whether to set submission.user_saved_flag so that submission automatic abandonment will not occur. |
sendEmailSavedForm | union: false | true Whether to send a "Form Saved" email message to the specified user emailAddress parameter. |
emailAddress | string The email address of the recipient of the "Form Saved" email. |
milestone | string (Maximum length 100 characters) A transaction milestone event to record with the transaction. |
addAttachmentManually | object The add submit manually file attachment; use the makeAddAttachmentManually method to obtain this. |
removeAttachment | object The remove file attachment metadata; use the makeRemoveAttachment method to obtain this. |
addAttachmentFile | object The add file attachment metadata; use the makeAddAttachmentFile method to obtain this. |
fileContent | File The DOM File object with content. |
Returns
A Promise containing the response object. For more information, see Form Update > Response in the Open UX API documentation.
note
The formData property returned via the core library is an object instead of XML.
getDataXml
Returns a string that contains an XML representation of the data
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
data | object Required. The application data object to serialize to XML. |
prettify | union: false | true Whether to prettify the output. |
Returns
A string that contains an XML representation of the data.
isSaveChallengeRequired
Returns true if Save Challenge is required. User should perform a formLoad with options to resume the form.
Returns
A boolean true if Save Challenge is required, otherwise false.
makeAddAttachmentFile
Return an object suitable for passing to the addAttachmentFile parameter of the formUpdate method.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
path | string Required. Should specify the XPath to the Attachment Field. The path value would be used when returning validation errors to the client if the addAttachmentFile operation fail. |
attachmentKey | string Required. Provides a GUID of the file attachment, this value will be used to store the new file attachment in TM. |
attachmentName | string Required. The name attribute for the meta data. |
description | string Required. The description attribute for the meta data. |
maxSize | number Required. Specifies the maximum file size allowed for the attachment. This is a server-side check. |
fileTypes | string Required. Specifies the file types extensions that will be allowed by the server, for example, .jpg, .gif. Do not use MIME types, such as image/jpeg. |
Returns
An object suitable for passing to the addAttachmentFile parameter of the formUpdate method.
makeAddAttachmentManually
Return an object suitable for passing to the addAttachmentManually parameter of the formUpdate method.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
path | string Required. The XPath to the Attachment field. The path value is used when returning validation errors to the client if the addAttachmentFile operation fails. |
attachmentKey | string Required. Provides a GUID of the file attachment. This value is used to store the new file attachment in TM. |
attachmentName | string Required. The name attribute for the meta data. |
Returns
An object suitable for passing to the addAttachmentManually parameter of the formUpdate method.
makeRemoveAttachment
Return an object suitable for passing to the removeAttachment parameter of the formUpdate method.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
attachmentKey | string Required. The attachmentKey string. |
Returns
An object suitable for passing to the removeAttachment parameter of the formUpdate method.
userCancel
Make a call that performs a user initiated cancel abandonment operation. The app should display a cancel confirmation page after this operation.
For more information, see User Cancel in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
formData | object Required. An object tree of the form data; e.g. passed in via a Redux selector |
milestone | string (Maximum length 100 characters) A transaction milestone event to record with the transaction. |
Returns
A Promise containing the response object. For more information, see User Cancel > Response in the Open UX API documentation.
userSave
Make a call that performs a user initiated save operation. It is recommended that the app displays a save confirmation page after this operation.
For more information, see User Save in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
formData | object Required. An object tree of the form data; e.g. passed in via a Redux selector. |
sendEmailSavedForm | union: false | true Specify whether to send a "Form Saved" email message to the specified user emailAddress parameter. |
sendEmailShareForm | union: false | true Specify whether to send a "Form Shared" email message to the user specified by the emailAddress parameter. |
emailAddress | string The email address of the recipient of the "Form Shared" email. |
milestone | string (Maximum length 100 characters) A transaction milestone event to record with the transaction. |
Returns
A Promise containing the response object. For more information, see User Save > Response in the Open UX API documentation.
userSubmit
Make a call that performs a user initiated submit operation. The app should display a submission confirmation page after this operation.
For more information, see User Submit in the Open UX API documentation.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
formData | object Required. An object tree of the form data; e.g. passed in via a Redux selector. |
sendEmailFormReceipt | union: false | true Specify whether to send an "Form Receipt" email message to the specified user emailAddress parameter. |
emailAddress | string The email address of the recipient of the "Form Receipt" email. |
milestone | string (Maximum length 100 characters) A transaction milestone event to record with the transaction. |
Returns
A Promise containing the response object. For more information, see User Submit > Response in the Open UX API documentation.
Util Methods
@transact-open-ux/core exports a number of its util methods allowing you to perform certain tasks in a more convenient manner.
getDataFromPath
Gets the value from a data object via the part parameter.
Example
import { getDataFromPath } from "transact-open-ux/core";
const formState = {
Applicant: {
FirstName: "David"
}
};
// FirstName === "David
const FirstName = getDataFromPath("Applicant.FirstName", formState);
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
path | string Required. The path to get the data from. |
data | object Required. The object to lookup the path. |
Returns
Returns the value found at the path location within the data object.
getUrlQueryParam
Returns the value of the URL parameter, or null if it does not exist.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
key | string Required. The URL parameter name. |
Returns
The value of the URL parameter, or null if it does not exist.
getUrlQueryParams
Returns an object of the current URL parameters. The keys are the parameter names.
Returns
An object of the current URL parameters. The keys are the parameter names.
jsonify
Returns a JSON string from an object, stripping out any keys that start with a dollar sign ($).
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
object | object Required. The object to transform to a JSON string |
prettify | union: false | true A boolean value indicating whether to prettify the output. |
Returns
A JSON string representation of an object, stripping out any keys that start with a dollar sign ($).
redirect
Redirects the app to another target URL.
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
redirectTarget | string Required. The URL to redirect to. |
setDataFromPath
Sets the data path to the value.
Example
import { setDataFromPath } from "transact-open-ux/core";
const formState = {
Applicant: {
FirstName: "David"
}
};
// formState.Applicant.FirstName === "Joe"
setDataFromPath("Applicant.FirstName", formState, "Joe");
Parameters
All parameters are optional unless otherwise indicated.
| Parameter | Description |
|---|---|
path | string Required. The path to set the data. |
data | object Required. The object to find and set the data path in. |
value | any Required. The value to set the data to. |
Returns
The modified object.