User Select Script¶
The user select script runs in the user's browser after the user selects an action and confirms it, and before the form is submitted. Use it for interaction that must happen at the moment of the decision and whose result must be submitted together with the action.
Open the script from the action's User Select Script setting in the process designer.
When to Use It¶
Typical uses:
- Ask the user to sign attached files or a text with an electronic signature.
- Call a REST service or a script module function to check or enrich the data.
- Write values into the form data, such as a decision date or the signer's name.
- Cancel the selection when a condition is not met and inform the user.
Use the postwork script instead for effects that must happen on the server, such as database updates, document generation, or mandatory checks.
When It Runs¶
- The user selects the action. Actions whose validation group fails stay disabled.
- The confirmation message and the comment input are shown.
- The user select script runs. It can cancel the selection or change the form data.
- The form data, including the changes made by the script, is submitted.
- The server continues with the postwork script and the routes.
Browser scripts are not enforcement
The user select script runs only when a user selects the action from the task form. It does not run when the action is selected through bulk selection, an email reply, a deadline, an auto-select rule, a prework script, or an API call. Do not rely on it for a mandatory business rule. Enforce mandatory conditions on the server, for example with a postwork check, and disable Allow Bulk Selection for actions that depend on the script.
Available Objects¶
The script runs in the same context as form scripts:
| Object | Purpose |
|---|---|
$Xml | Form data of the task. Relative paths start at the form data root. Changes are submitted with the action. |
$Rest, $Services | Calls to REST and web services configured for the process. |
$Calendar, $Calendar2 | Working calendar calculations. |
| Script module functions | Server functions of script modules, called with the Async suffix and await. |
| Form variables | Variables supplied to the form, such as $ActiveUser, prefixed with $. |
AltiKare.Signature | Electronic signature functions; see Electronic Signatures. |
Server-only objects such as $WorkItem, $Instance and $Database are not available. Use the postwork script for operations that need them.
Continuing or Cancelling the Action¶
The result of the script decides whether the action is submitted:
- Returning nothing (
undefined) or a truthy value submits the action. - Returning another falsy value, such as
false, cancels the selection. The user stays on the form and can select an action again.
Synchronous Script¶
A synchronous script returns its result directly:
1 2 3 4 | |
Asynchronous Script¶
Use await for asynchronous work such as service calls, module functions, or signatures. The action waits until the script finishes and uses its return value in the same way. Catch errors and return false so that the user gets a clear message and the selection is cancelled:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
In this example Finance.checkBudgetAsync is a placeholder for a function of your own script module.
Signing Files When the Action Is Selected¶
The following script asks the user to sign the attached files and submits the action only after the signature is completed:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | |
For prerequisites, formats, signature files, and server-side verification, see Electronic Signatures. For a complete example process, see Sign Attachments on Approval.