Script Contexts¶

A script's available objects and XML scope depend on its execution surface and caller. Check both before reusing code from another script. An editor completion entry lists an API that may be useful; it does not establish that the object exists in every invocation. An available server proxy still enforces its tenant and user authorization rules.

Task Scripts and Expressions¶

Task prework, postwork, automation and evaluation operation scripts run on the server with $WorkItem, $Instance and $Xml. Relative XML paths start at the work item's data root (DataRoot). Inspect the selected pool and data root before choosing paths.

Role identity expressions, action auto-selection rules and route rules use work item context. Their return values differ: a role expression returns identities; action and route conditions return boolean true when applicable. Lifecycle and automation scripts perform their operations through the context; returning a boolean is not an action selection. Other JavaScript expressions depend on their owner and must be checked at that invocation site.

Pool Lifecycle Scripts¶

Pool opening, closing and termination scripts receive instance context, including $Instance, $Initiator, $Templates and $Xml.

The XML node comes from the work item initiating, completing or terminating the instance. Relative paths start at that work item's data root. Do not assume $Xml points to the XML document root merely because the script belongs to a pool. The $Case is present only when the instance has an associated case.

Screen Initialization¶

A screen's initialization script runs on the server before its data is sent to the browser. It receives screen data at the configured RootElement, $ActiveUser, $Culture and process services. It does not receive $Instance or $WorkItem. Its XML changes prepare the initial screen data; they are not changes to a form already open in a browser.

Form Scripts and Action Selection¶

Form and screen client scripts run in the browser with $Xml bound to the supplied form data node. Client helpers include $Calendar, $Calendar2, $Rest, $Services and asynchronous module functions. Their implementations and signatures can differ from server proxies. $Database and the server $WorkItem proxy are not provided by the client scripting runtime. Additional values, such as $ActiveUser, depend on the form's supplied variables.

An action selection script runs after action validation and before the action is selected. An undefined or truthy return value permits selection; another falsy value cancels it.

Use supported XML helper updates that preserve live element bindings. Replacing bound content with InnerXml(value), OuterXml(value) or raw DOM subtree operations can leave controls referencing detached elements. Correct serialized XML does not prove that the form displays or edits the current nodes.

Validation and Formatting Rules¶

$Xml represents the rule's bound widget node. For RowRules, it represents the current row. It is not necessarily the form root. A truthy validation result reports a violation; a truthy formatting result applies the configured properties. Keep these conditions observational rather than modifying form data from them.

Row Creation Scripts¶

Table Content and Repeating Content row scripts initialize a new row. $Xml represents the control's bound container; $NewChild represents the new row. Use paths relative to the new row with $NewChild, rather than assuming $Xml already points there.

Query row scripts also receive $Row, the source query record. $NewChild is the newly mapped XML row and $Xml is the query target node. These scripts initialize rows; their return value is not a validation result. Row creation scripts and validation/formatting RowRules have different XML scopes.

Event Scripts¶

Both Event and EventListener handle scripts run with server work item context, but their additional inputs differ:

$Input does not replace the listener's $Xml. Event payload and workflow data are separate XML contexts.

Module Functions and RPC¶

A script module inherits the context of a direct server caller. Calling that function from prework can provide $Xml and $WorkItem; calling it through Module.FunctionAsync(...) in a browser does not provide these objects.

Web module execution selects a process-version, instance or content-type context. Even with an instance ID, it does not receive the live form XML, $Xml, $WorkItem or unsaved form edits. Pass required values as arguments and return data for the client to apply through supported form APIs. An instance context can supply $Instance; a process-version-only context cannot. Content-type context also lacks process-definition-specific services.

Use the standalone server XML factory when parsing text independently of form data:

1
2
3
4

exports.ReadLabel = function (xmlText) {
    var data = Xml.parse(xmlText);
    return data.Evaluate('Label');
};

Xml.parse uses lowercase parse. It does not require $Xml and does not supply process schemas or defaults. Syntax validation does not establish that a global exists at runtime. Verify shared functions through each intended call path; a successful hook call alone does not verify RPC behavior.