Declaring variables for client-side human services

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 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 value, null, is used. If no variable values are specified (no mapping), the default values take effect at run time.
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 the process 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 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 want to use the 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.

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 programmatically change the values, 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.

Procedure

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

Open your client-side human service in Process Designer.
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 BOs, 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.

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.