Custom workflows and workflow instances

The core functionality of the architecture is to allow external integrators to implement custom workflows (custom UI and logic). Every time the user starts a new custom workflow, a new custom workflow instance (aka “CUWO instance”) is created. Each such instance has a unique identifier (the “CUWO instance ID”), runs inside a CUWO container component, and is sandboxed from the normal client environment. The device (e.g., Dasher) that the workflow instance is running on is called the “CUWO instance host”.

The “CUWO container” is implemented using a webview (e.g., Android WebView) and thus the user interface and logic running inside the container must be implemented using HTML, CSS, and JavaScript. The CUWO instance host will provide the workflow logic with the “CUWO callback” and the “CUWO message” APIs that will allow the workflow to communicate with the surrounding host (e.g. to close the container on completion or to trigger the printing of a document).

The workflow instance is invoked by a “start URL” that is preconfigured in the master data (for example the product in case of a “configure line item” CUWO). The workflow can load additional resources (e.g., CSS or image files) and perform page navigation.

Workflow lifecycle

Each client device has its own CUWO container and is not aware of any workflows running on other devices. The generation of the CUWO instance ID takes this into account and generates a unique identifier based on its client ID (the internal structure of the instance ID is an implementation detail though).

Setup and teardown

From a high-level view, the general setup of a workflow starts with the user triggering the start of a custom workflow. The enfore client will determine the start URL, initialize the container (which in turn checks the necessary client certificate and fetches it as necessary) and initiate the workflow by causing the container to load the start URL. Once the custom workflow is finished (either successfully or not), the workflow must notify the container via the CUWO Callback. The container will then notify the enfore client which will clean up the container and workflow and handle the workflow’s results.

Aborting workflows

To guard against workflow instances that are created and then do not complete, the UI window provided by the CUWO container will have some UI elements for aborting the flow.

When the user uses those elements to abort the flow, the workflow will be notified via an TerminationRequested message. The container will then display confirmation query to the user, the message of which the workflow can control if it replies to the TerminationRequested message within 200 ms with an TerminationConfirmationMessage message. If the user confirms that the workflow should be terminated, the container will notify the workflow with a TerminationNotification message and terminate the workflow after another 200ms.

The following diagram shows the possible sequence of events:

If the workflow needs to be terminated due to technical reasons (e.g. Android memory warning), the workflow will be notified by a KillNotification message. The system will try to give the workflow some time to persist its state, but due to technical constraints, that is not guaranteed. In exceptional cases, the workflow may also be killed directly without the use of a KillNotifiation message. This happens, for example, if the power connection of the device is cut.

Page navigation and loading additional resources

The workflow running inside the container is essentially a web page and thus can invoke page navigation using the usual HTML or JavaScript constructs. Note though that the CUWO container does not provide any UI that would allow the user to navigate the browse history. As such, the workflow should rather be implemented as a single-page application. On the technical level, the target of any navigation link must always be _self. Links to other targets are not supported.

The workflow may also load additional resources such as stylesheets or script files and perform XHR requests using the usual constructs.

Workflow UI

The user interface of the workflow is implemented using plain HTML, CSS, and JavaScript. Enfore provides a collection of React/Redux-based UI components implemented in N4JS, that should be/are to be used to implement a user interface in the same style as the enfore OnlinePresence (OPR).

Workflow interaction with hardware devices

The custom workflow may need to interact with hardware devices such as printers, barcode scanners, or a signature part. As the client-side logic is running inside WebView, it does not have direct access to those devices. Instead, the workflow can trigger device interaction via the “CUWO Messages API”.

Workflow extension points and workflow types

A custom workflow replaces or enriches a processing step in the regular enfore platform behavior. Therefore, the regular platform behavior must define "extension points" where custom workflows can be attached. Each extension point defines what the specific workflow's purpose is, what parameters is receives and what result data is expected of it.