Declaring variables for client-side human services

Draft comment:
This topic is shared by BAW, CP4BA, CP4BASaaS. Last updated on 2025-03-13 12:15

For each client-side human service that you create, declare variables to capture the data that steps or activities in that human service use.

About this task

You can add the following variables to your client-side human service.

Table 1. Variables available for addition to client-side human services
Variable	Description
Input	Variables that represent input data that is passed to the current client-side human service
Output	Variables that represent output data that the current client-side human service returns to its caller
Private	Local variables that are used only within the client-side human service
Exposed Process Values	Exposed process values (EPVs) can be linked to and used from a client-side human service
Environment Variables	Environment variables can be linked to and used from a client-side human service

Default variable values

For input and private variables that you define for either root or nested client-side human services, you can specify default values that take effect at run time. For the default values, you can specify both simple and complex values, as well as arrays for lists. Depending on how the client-side human service is used, the default values take effect as follows:

When the client-side human service is implemented as a task, and the process instance specifies variable values for the task through input mapping, the specified values take effect at run time. If a mapped variable from the process is not initialized, its mapped null value is used. If no variable values are specified (no mapping), the default values take effect at run time. See also Creating versus starting a client-side human service task in a process.
When a client-side human service is implemented as a startable service or a URL, for example, if there are input variable values that are specified as URL parameters, the specified values take effect at run time. Otherwise, the default values take effect.
When a nested client-side human service is called from a parent client-side human service and the parent specifies variable values through input mapping, the specified values take effect at run time. If there is no mapping, the nested service uses the default values. If there is a mapping, the nested input uses the parent variable value, even if it is uninitialized.
When variables are declared inside an event handler of either error or data change type, the default values take effect the first time the event handler runs in the current instance of the nested service that contains the event handler. If you exit the client-side human service that contains the event handler and enter it again, all the variables, including the event handler variables, are reset.

Tip: In client-side human services that are implemented as instance details user interfaces, only private variables can have default values.

Exposed process variables (EPVs) and environment variables

You can link to existing exposed process values (EPVs) and environment variables in the Variables view of a client-side human service, so that you can access the variables through scripts that you defined for your client-side human service. You can reference the name of the variables as follows:

tw.epv.[epv_name].[epv_variable_name]
tw.env.[env_variable_name]

Depending on whether your client-side human service runs in the context of a parent process application or as part of a dependent toolkit, its variables can be accessed differently:

If a variable with the same name exists in the parent process application, the value from theprocess application is used, regardless of its structure or properties.
If a variable with the same name exists in the dependent toolkit but does not exist in the process applicationprocess application, the toolkit value is used.

When an EPV or environment variable with the same name exists in both the parent process application and in the dependent toolkit, the format that you specify in your scripts determines which variable value is used.

If you want to use the process application value, use the variable's short name in your scripts, for example, tw.epv.[epv_name] or tw.env.
If you want to use the toolkit value, regardless of overlapping names, use the tw.epv.toolkit or tw.env.toolkit format in your scripts.

Note: The variable declaration must be a direct dependency of the context that the client-side human service is running in. Declarations in nested toolkits will not be resolved at run time. As such, when the variable is declared in a toolkit, the process application must depend on that toolkit.

The variable values are available when you run the client-side human service, and are retrieved only when the client-side human service is started. To change the values programmatically, use a called service that implements a server-side JavaScript API function call. For example, tw.epv.[epv_name].[epv_variable_name].update(<value>, <date>).

The new value will not be automatically retrieved by the client-side human service. Newly launched client-side human services will see the new value after the scheduled time.

For more information about EPVs and environment variables, see Creating exposed process values (EPVs) and Setting environment variables.

Creating versus starting a client-side human service task in a process

The following expected behavior occurs when you use a client-side human service task in a process or call a Business Automation Workflow REST process or task API. Depending on which task instance is used for the data retrieval, Process Inspector might show out of sync data for the task, as follows:

When the task is created, data is retrieved from the process instance at creation time.
Later, when a user starts the task, data is retrieved from the runtime process instance, which might be different from the data when the task was created.

Therefore, Process Inspector and the Business Automation Workflow process or task REST API might show that out of sync task data until the task is started by the user.

The described behavior is not observed when you use heritage human services, which do not automatically retrieve data from the runtime process instance when a user starts the task.

Exposing business data at user task level for use in search APIs

You can now expose business data at task activity level in addition to simple-type and nonlist variables at process level. It means that the data is available for searching when user task instances are running or have completed, allowing for effective retrieval of relevant information. Also, you can define aliases for the exposed variables and use them along with task and process metadata in task search APIs.

For UI developers, business data searches provide control over searchable task data, exposing only relevant information. For business users, it helps in building and refining task searches in Workplace by using specific data values during and after task completion.

Tip: Business data searches work for both advanced and basic searches. However, for the basic searches you need to have the federated data repository indexing configured. For more information, see Enabling the Federated Data Repository process indexing. For more information on how to use the exposed business data in your searches, see Searches in Workplace.

You can expose the following variable types:

Table 2. Variable types that can be exposed
Variable type	Available in task search
Simple-type (for example, Boolean, string, integer)	Yes
Nonlist (single-value)	Yes
List (multi-value)	No
Composite-type	No
Simple-type properties of business objects	Yes

To expose business data and define an alias for it:

In your client-side human service, go to the Variables tab and select the variable that you want to expose.
Select Expose in work environments to make the business data available in the user task activity.
In the Alias field, type a unique name that you want to assign to the exposed variable.

Note: The name needs to be unique within the client-side human service, unless it is shared with an input or output variable with the same name, type, and cardinality.

Procedure

To add an input, output, private, or EPV variable to the client-side human service:

Open your client-side human service.
Switch to Variables, then click the plus sign next to Input to add a new input variable.
In the Details section:
1. Specify the variable name.
  Variable names are case-sensitive and must start with a lowercase letter, with subsequent words capitalized, for example: myVar. Do not use underscores or spaces in variable names.
2. Click Select next to Variable Type to select the type of the variable from the Select Library Item list.
  Custom business objects that you created are also listed. To create a new business object, click New and complete the wizard steps.
  Client-side human services do not support business object instances that reference themselves. For example, the following JavaScript generates an error when used inside a client-side human service:
```
tw.local.myVariable= {};
tw.local.myVariable.pointer= tw.local.myVariable;
```
  Tip: For more information on how to use the standard JavaScript syntax to instantiate objects in the client-side script, see Re-creating heritage human services as client-side human services.
3. Optional: Specify a variable description under Documentation.
4. Optional: If you want your variable to be an array, select Is List.
To specify a default value for the input or private variable that you are adding, select Has default under Default Value, and then type in the default value.
Note: For complex business objects, the default value script must declare a variable and return it by specifying the last line as the variable name. For example:
```
var autoObject = <new_instance>; 
...
autoObject
```
Save the configuration.
Iterate through steps 2 to 4 to add an output, private, EPV, or environment variable to the client-side human service.
Click Save or Finish Editing.
For details about declaring variables for the client-side human services, see Declaring variables

What to do next

You can now map the input and output variables that you want to pass to steps and activities in your client-side human service. See Data mapping for nested client-side human services.