OfflineWorklistClient Extensions

Introduction

The OfflineWorklistClient extension stores process instance and workitem related information in a relational database. It can be used to build a unified worklist solution for multiple Appway installations/instances or to embed worklist information in other applications.

This document aims at describing the extension pre-requisites, its configuration, and the scripts it makes available to the Appway Platform.

Scope

This document covers the following:

  • A brief description of the extension and how the OfflineWorklistClient extension works
  • Prerequisites
  • Extension configuration options
  • Available script functions

How the OfflineWorklistClient Extension Works

Consider this scenario:

Figure1.png

Figure 1: A multi-Appway instance setup

In the figure above, we can see three separate Appway setups, the first and second a cluster, and the third a single node installation. For the sake of this document, let us call a cluster or a single node setup an environment. These environments have their own storage, and are running independently of each other. Each environment can also display their own worklists – via the WorkitemFinder extension – that serves as a single entry point for open process instances.

Note: The WorkitemFinder extension replaces the Inbox extension, deprecated in Appway 9.

Now, let’s assume a user creates a process instance in environment 1, but needs to check the status of a process instance that has been created in environment 2 to determine whether to proceed. In this scenario, the client can open a new browser, log into environment 2 and open its worklist page to determine whether to create a new process instance in environment 1.

The OfflineWorklistClient extension provides a unified view of process instances among separate Appway environments. Think of this as a single worklist page where the process instances of all environments can be seen.

At its core, the OfflineWorklistClient extension makes use of a database to store the state of process instances of different environments. It then aggregates all the stored data to serve as a single point of reference on the process instances of multiple environments. The diagram below illustrates how users interact with a unified worklist when the extension is installed and configured.

Figure2.png

Figure 2: User interaction with a unified worklist

With the extension installed and configured for the three environments, the state of all process instances is persisted to a database. The unified worklist can serve as the central point for viewing all process instance data for all the environments. This worklist can be hosted on any Appway environment with the extension installed and configured to point to the same database. Data is fetched via function calls provided by the extension itself.

Once the extension is configured, changes to process instances – whether they are newly created, updated, or completed/terminated – are tracked by the extension process listeners, then stored in the database. This ensures the database is in sync with the state of the multiple environments.

Note: When installing the extension for an environment with existing process instances, a rescan can be done to sync the OfflineWorklistClient database with the in-flight instances. See the `worklist.rescan.` configurations in the Extension Configuration Options section.

Prerequisites

The extension works with the following minimum requirements:

  • A data source configured in Appway. This data source name is then specified in the extension via the configuration property worklist.datasource.
  • For multiple Appway instances that require their data to be consolidated, they should all point to the same database.
  • The default values – with the exception of worklist.datasource configuration property – should be enough to run the extension normally. The description of the configurations below can be used to further optimize performance.

Note on System Status and System Info

The systeminfos table is used to store information about all connected Appway installations/instances and is populated by the system administrator. Its most important attributes are:

  • Public URL (as seen by business users): it allows the worklist to render links to the workitems hosted on other installations.
  • Cluster URL (as seen "behind the firewall"): is used by some functions to do "remote calls" to functions on other installations.

To enable this feature, the extension configuration property worklist.systemstatus.enabled (see the Extension Configuration Options below) must be set to true. The OfflineWorklistClient extension needs to be restarted. After the restart, the extension adds an entry into the systemstatus table for itself (or update that entry if it already exists). Moreover, it registers a background job that periodically updates this entry in the database, including the current timestamp. This timestamp, in turn, supports a further feature: the detection of an online/offline installation. If an installation is pulling information about workitems from the database, it can also check whether the installation that is hosting a workitem is currently online (the entry in systemstatus table has been updated recently) or offline. If the workitem is on a system that is not online, it can decide to hide these workitems in the worklist, render them inactive, or apply some other strategy the client wants. Furthermore, the above configuration property also makes the extension register two additional Studio tools (JSP pages) to list the systems found in the systeminfos table and to edit some of their properties (such as the public and cluster URL).

Extension Configuration Options

Following is a list of the main configuration properties for the OfflineWorklistClient extension.

worklist.datasource

The name of the data source where the extension data is stored. This data source should be configured in Appway. The default name is Worklist.

worklist.log.level

The log level of the extension, for troubleshooting purposes. The default value is set to INFO.

worklist.listener.priority

The priority of the listeners for changes in in-flight process instances. The listeners ensure changes in the in-flight process instances in Appway are in sync with the extension data in the database. The default value is 90.

worklist.rescan.onstartup

A flag to specify whether to rescan process instances on startup. This syncs the in-flight process instances in Appway with the extension database. The default value is true.

worklist.rescan.job.enabled

A flag to specify whether the rescan should continue running even when the application has already started up (as opposed to the worklist.rescan.onstartup configuration above). The default value is false.

worklist.rescan.job.schedule

The schedule – in cron pattern – on how frequently the rescan job should run. This configuration is only required if worklist.rescan.job.enabled is set to true. The default value is at 2AM daily (0 0 2 * * ?).

worklist.rescan.job.paused

A flag to specify whether the rescan should be paused. This configuration is only required if worklist.rescan.job.enabled is set to true. The default value is false.

worklist.rescan.distributed

A flag to specify whether the rescan job should be distributed across all nodes or to run only on one node. The default value is true.

worklist.rescan.threads

The number of threads to be allocated per rescan job. The default value is 1.

worklist.rescan.retries

The number of retries allowed per rescan job. The default value is 3.

worklist.systemstatus.enabled

A flag to specify whether the status should be accessible from Studio. This can be found under Data & Integration > Status and Data &Integration > Systems. The default value is false.

worklist.systemstatus.schedule

The schedule – in cron pattern – on how frequently the system status updates should run. This configuration is only required if worklist.systemstatus.enabled is set to true. The default value is every 30 seconds starting at the :00 second after the minute (0/30 * * * * ?).

worklist.systemstatus.timeout

The timeout, in seconds, to be used when querying system status. The default value is 60.

worklist.systemstatus.cache.timeout

The timeout, in seconds, to be used when querying the system status from cache. Any value greater than zero enables the cache. The default value is 5.

worklist.systeminfo.cache.timeout

The timeout, in seconds, to be used when querying for system information. The default value is 30.

worklist.userattributes.cache.timeout

The timeout, in seconds, to be used when querying for user attributes in cache. A value greater than zero enables the cache (consider that zero also disables the cache). The default value is -1 (cache disabled).

worklist.groupattributes.cache.timeout

The timeout, in seconds, to be used when querying for group attributes in cache. A value greater than zero enables the cache (consider that zero also disables the cache). The default value is -1 (cache disabled).

worklist.remotefunctioncalls.enabled

A flag to specify whether to enable remote procedure calls between the Appway instances. The following functions are made available if this is enabled:

  • OfflineWorklistAssignWorkitemToUser
  • OfflineWorklistWorkflowInstanceGetAttribute
  • OfflineWorklistWorkflowInstanceSetAttribute
  • OfflineWorklistWorkflowInstanceRemoveAttribute
  • OfflineWorklistWorkflowTokenGetAttribute
  • OfflineWorklistWorkflowTokenSetAttribute
  • OfflineWorklistWorkflowTokenRemoveAttribute
  • OfflineWorklistWorkitem
  • OfflineWorklistTimestamp

The default value is true. This change requires the extension to be restarted.

worklist.remotefunctioncalls.password

The password to use for remote function calls. The same password should be used across all instances sharing the data held by the extension. The default is blank (no password).

worklist.remotefunctioncalls.timeout

The timeout, in seconds, for remote function calls. This configuration property is ignored if worklist.remotefunctioncalls.enabled is set to false. The default value is 5.

worklist.attributes

A comma-separated list of attribute names that are to be tracked/persisted by the extension in its internal database tables. The default value is * (asterisk) which means all attribute names are supported.

worklist.attributes.value.maxLength

Specifies the maximum length of an attribute value. The attribute value is truncated to the maximum length if it exceeds the specified value. The default value is -1 (no maximum length).

worklist.intermediate.events.enabled

A flag to specify whether process tokens for intermediate events should be tracked/saved. If set to true, tokens in timer, receive message and receive signal events are saved. The default value is true.

worklist.batchqueries.enabled

A flag to specify whether batch updates should be enabled. The default value is true (since extension version 4.0).

worklist.useThreadLocalConnections

A flag to specify whether a connection should be reused in a single thread. This is achieved by binding the context to the current request via a servlet filter. The default value is false.

worklist.jmx.enabled

A flag to specify whether the status of the extension can be read via JMX. The default value is false.

portalworklist.compatibility

A flag to specify whether the process ID should also be persisted in the extension’s database. The default value is false.

portalworklist.store.translated.labels

A flag to specify whether labels are to be translated to the target language. This option refers to values stored in the table WorkflowTokens (elementName, elementTaskListName, phaseName, phaseTaskListName, swimlaneName, swimlaneTaskListName). The target language is specified in portalworklist.default.language. The default value is false.

portalworklist.default.language

The language to use when translating labels. This configuration is only evaluated if portalworklist.store.translated.labels is set to true. The default value is English (en).

portalworklist.parent.tlname

A flag to specify if the parent task name of tokens is to be stored. The default value is false.

Script Functions

Following is a silt of the main functions exposed by the OfflineWorklistClient extension grouped in sections.

Process instances Functions

These are functions that operate on process instances.

OfflineWorklistDeleteWorkflowInstance

Deletes a process instance from the offline worklist database.

Parameters: workflowInstanceId – The ID of the process instance to delete.

Returns: None

OfflineWorklistRescanWorkflowInstance

Deletes and rescans a process instance. The process instance is deleted from the database and the latest state is fetched from the cluster, then reinserted in the offline worklist database.

Note – This function call will work only when the provided Process Instance ID is hosted in the cluster in which the function is run.

Parameters: workflowInstanceId – The ID of the process instance to delete and rescan.

Returns: None  

System Information Functions

These are functions for obtaining systems information.

OfflineWorklistSystemFitness

Returns the System Info fitness

Parameters: systemId – The ID of the system for which to get the fitness

Returns: The status of the System Info fitness

OfflineWorklistSystemId

Returns the system ID of the server/cluster where the function is run.

OfflineWorklistSystemStatus

Returns the status of the specified system ID.

Parameters:

  • systemId – The system ID to get the status for
  • timeout – The timeout, in seconds. The default value for the timeout is the value of worklist.systemstatus.timeout.

Returns: The status of the system ID provided.

OfflineWorklistSystemURL

Returns the public system URL of the system ID provided.

Parameters: systemId – The system ID to get the URL for

Returns: The public system URL of the system ID provided.

OfflineWorklistClusterURL

Returns the cluster URL of the system ID provided.

Parameters: systemId – The system ID to get the cluster URL for

Returns: The cluster URL of the system ID provided.

 

OfflineWorklistSystems

Returns the systems with the specified status

Parameters: statusFilter – The status to be used as filter. Valid values are: ONLINE, MAINTENANCE, OFFLINE, TIMEOUT, UNKNOWN, LOCKED. If no filter is provided, the function returns all systems registered.

Returns: The system IDs

OfflineWorklistFindSystemIdForWorkflowInstance

Returns the system ID for a given process instance ID

Parameters: workflowInstanceId – The ID of the process instance belonging to the system to search.

Returns: The system ID hosting the supplied process instance ID.

User Functions

These are functions that operate on users.

OfflineWorklistGetUserAttribute

Reads a user attribute from the offline worklist database.

Parameters:

  • userId – The ID of the user owning the attribute.
  • attributeName – The attribute name to retrieve.
  • useCache – A flag to enable reading from the cache. Set it to true to enable reading, false otherwise. Default value is true.

Returns: The user attribute value

OfflineWorklistGetUserAttributes

Reads all user attributes from the offline worklist database.

Parameters: userId – The ID of the user owning the attributes.

Returns: The user attribute values.

OfflineWorklistSetUserAttribute

Saves a user attribute in the offline worklist database.

Parameters:

  • userId – The ID of the user owning the attributes.
  • attributeName – The name of the attribute.
  • attributeValue – The value of the attribute.

Returns: None

OfflineWorklistDeleteUserAttribute

Deletes a user attribute from the offline worklist database.

Parameters:

  • userId – The ID of the user owning the attributes.
  • attributeName – The name of the attribute to delete.

Returns: None

OfflineWorklistDeleteUserAttributes

Deletes all user attributes from the offline worklist database.

Parameters: userId – The ID of the user owning the attributes.

Returns: None

 

Group Functions

These are functions that operate on groups.

OfflineWorklistGetGroupIds

Reads all group IDs from the offline worklist database.

Parameters: None

Returns: An indexed collection of stored group IDs

OfflineWorklistGetGroupAttribute

Reads a group attribute from the offline worklist database.

Parameters:

  • groupId – The ID of the group owning the attribute.
  • attributeName – The attribute name to retrieve.
  • useCache – A flag to enable reading from the cache. Set it to true to enable reading, false otherwise. Default value is true.

Returns: The attribute value

OfflineWorklistGetGroupAttributes

Reads all group attributes from the offline worklist database.

Parameters: groupId – The ID of the group.

Returns: The attribute names and their corresponding values.

OfflineWorklistSetGroupAttribute

Saves a group attribute in the offline worklist database.

Parameters:

  • groupId – The ID of the group.
  • attributeName – The name of the attribute
  • attributeValue – The value of the attribute

Returns: None

 

OfflineWorklistDeleteGroupAttribute

Deletes all group attributes in the offline worklist database.

Parameters:

  • groupId – The ID of the group.
  • attributeName – The name of the attribute to delete.

Returns: None

OfflineWorklistDeleteGroupAttributes

Deletes all group attributes in the offline worklist database.

Parameters: groupId – The ID of the group.

Returns: None

 

Database Functions

These are functions for obtaining database information.

OfflineWorklistDataSourceName

Returns the name of the data source used by the Offline Worklist Client extension.

Parameters: None

Returns: The data source name

OfflineWorklistSchemaName

Returns the name of the database schema used by the OfflineWorklistClient extension. This value is read from the data source configuration and may be null if no schema has been defined.

Parameters: None

Returns: The schema name

OfflineWorklistReplaceSchema

Replaces all occurrences of the text ‘’ with the database schema name.

Parameters: sql – The SQL statement to format – e.g. ‘SELECT * FROM {SCHEMA}.WorkflowTokens’

Returns: The formatted SQL statement

 

Remote Function Calls Functions

These are functions that are only available when the configuration property worklist.remotefunctioncalls.enabled is set to true.

All functions in this section – with the exception of OfflineWorklistTimestamp – have their Appway function counterparts. Their usage is the same, except the extension functions can be called even for an entity (i.e. a workitem) that does not exist in the Appway instance where the script is called.

OfflineWorklistAssignWorkitemToUser

Assigns a workitem to a user. This is functionally the same as the AssignWorkitemToUser function in the Appway Platform.

Parameters:

  • workItemId – The ID of the workitem to be assigned.
  • userId – The ID of the user to whom the workitem will be assigned
  • variableAssignments – The variable assignments for the value store of the process instance being forwarded. This parameter is optional.
  • ignoreAssignmentErrors – If set to true, variable assignment errors are ignored. The default value is false.
  • forceCurrentProcessToken – If true, assigns to the current workitem instead to a parent lying inside a swimlane. The default value is false.

Returns: None

OfflineWorklistWorkflowInstanceGetAttribute

Retrieves the attribute value for a given process instance ID. This is functionally the same as the ProcessInstanceGetAttribute function in the Appway Platform.

Parameters:

  • processInstanceId – The ID of the process instance
  • attributeName – The name of the attribute whose value is to be fetched.

Returns: The attribute value.

OfflineWorklistWorkflowInstanceSetAttribute

Sets a process instance attribute. This is functionally the same as the ProcessInstanceSetAttribute function in the Appway Platform.

Parameters:

  • processInstanceId – The ID of the process instance.
  • attributeName – The name of the attribute to set.
  • attributeValue – The value of the attribute to set.

Returns: None

OfflineWorklistWorkflowInstanceRemoveAttribute

Removes a process instance attribute. This is functionally the same as the ProcessInstanceRemoveAttribute function in the Appway Platform.

Parameters:

  • processInstanceId – The ID of the process instance whose attribute is to be removed.
  • attributeName – The name of the attribute to remove.

Returns: None

OfflineWorklistWorkflowTokenGetAttribute

Retrieves a process token attribute. This is functionally the same as the ProcessTokenGetAttributeFunction in the Appway Platform.

Parameters:

  • processTokenID – The ID of the process token.
  • attributeName – The name of the attribute to retrieve.
  • inherit – Set it to true to fetch the attribute from the parent token if it does not exist in the current one, false otherwise. Default value is false.

Returns: The attribute value

OfflineWorklistWorkflowTokenSetAttribute

Sets a process token attribute. This is functionally the same as the ProcessTokenSetAttributeFunction in the Appway Platform

Parameters:

  • processTokenId – The ID of the process token
  • attributeName – The name of the attribute to set
  • attributeValue – The value for this attribute
  • inherit – true to set the attribute to the parent token if it does not exist in the current one, false otherwise. Default value is false.

Returns: None.

 

OfflineWorklistWorkflowTokenRemoveAttribute

Removes a process token attribute. This is functionally the same as the ProcessTokenRemoveAttribute function in the Appway Platform.

Parameters:

  • processTokenID – The ID of the process token.
  • attributeName – The attribute to remove.
  • inherit – true if the attribute will be removed from a parent if it does not exist in the current one, false otherwise. Default value is false.

Returns: None

OfflineWorklistWorkitem

Retrieves a workitem by its workitem ID and process instance ID. If no parameters are supplied, this function call returns the current workitem (only available in the context of a process). This is functionally the same as the WORKITEM function in the Appway Platform.

Parameters:

  • workitemId – The ID of the workitem.
  • processInstanceId – The ID of the process instance.

Returns: The workitem, or null if it does not exist.

OfflineWorklistTimestamp

Retrieves the timestamp of the given system ID

Parameters: systemId – The system ID to fetch the timestamp for

Returns: The timestamp for the supplied system ID, in milliseconds.