Handling data changes in client-side human services

In instance details and task UIs, data can be changed both locally by the user or remotely by another user or service. The remote changes must be propagated to the user's browser to keep the data in the UI current. However, the user might have unsaved changes that need to be reconciled with incoming server updates. Use a data change event handler to react to and handle remote data changes.

About this task

A data change event handler checks for remote changes to the input variables of the client-side human service in the following ways. For instance UIs, the changes can be to any of the input variables. For task UIs, the changes are limited to changes to variables that are shared business objects.
  • At regular intervals that are based on the settings for the system timer. For more information, see Changing custom properties for Process Portal.
  • Explicitly by a user if the data change event handler is bound to a coach view, for example, a Refresh Button coach view.
When changes are detected, the data change event handler is started, and its subflow is triggered. While the event handler is running, you can use the tw.system.coachUtils and tw.system.dataChangeUtils JS APIs to access the local and remote changes. If you want to use data changes after the data change event handler finishes, for example, to resolve conflicts between local and remote changes, copy the data that you need to local variables.
Tip: To reduce memory consumption in the browser and to provide a better experience for users, minimize the amount of information that is held by the client. Therefore, copy only the information that your use case requires.

When the execution of the data event handler finishes, control is returned to the coach that was running when the event handler was started.

Human services for case type UIs automatically include a default data change handler. For BPDs, if you generated the client-side human service for the instance UI from the Instance Details UI Service template, the service contains a data change handler with a reference implementation. You can customize the reference implementation that is provided by the template, for example, so that the instance UI refreshes when the user clicks a Refresh button. For more information about the template, see Instance Details UI Service template.

BPDs and case types from IBM® BPM V8.5.5 and earlier do not contain data change event handlers. You can upgrade the human services for these BPDs and case types to handle data changes by adding and implementing a data change event handler.

Procedure

The following procedure describes how to add a data change event handler to a human service. If one of the following situations apply, follow all the steps in the procedure:

If you are customizing the reference implementation, go to step 5.

  1. Open the Process Designer desktop editor.
  2. Open the client-side human service that you want to work with.
  3. In the Diagram view, drag an event handler Event handler tool onto the canvas. By default, the event handler is an Error event handler.
  4. Change the default Error event handler to a data change event handler by renaming the Error node to Data Change, and on the Implementation tab, under Event Trigger, select Data change event.
    Tip: The data change event handler is available only for client-side human services that run in the context of a BPD or case type. A client-side human service can have only one data change event handler. Human services for case types automatically contain an implemented data change event handler.
  5. Implement the data change event handler.
    1. Optional: Specify boundary events that can trigger the data change event handler. By default, the event handler checks the server at regular intervals for updated data. To specify boundary events, on the Implementation tab, under Behavior, specify the coach boundary events that trigger the event handler.

      For example, you can add a Refresh Button control to the UI so that users can manually refresh the data. In the data change event handler properties, add the boundary events for the Refresh Button control to trigger the refresh.

    2. Add the logic for reacting to data changes by double-clicking the Data change node. Several tw.system.coachUtils and tw.system.dataChangeUtils JavaScript APIs are available for detecting data changes on the server and applying them to the client. For more information, see JavaScript API for client-side human service development.
  6. Click Save all to save the configuration of the client-side human service.
Parent topic: Modeling client-side human services