Script

A Script is a server-side executable unit in tSM — a piece of logic identified by a stable code, stored centrally, and invocable from processes, forms, APIs, connectors, and admin tools.

What it's for

• Automation — run business logic inside BPMN processes, event bindings, or direct API calls.
• Extensibility — add custom behavior without building and deploying a new microservice.
• Reuse — reference the same script from multiple processes, forms, or integrations by its code.

Scripts are first-class configuration entities — they have validity, localization, audit trail, ownership (microservice/listing), and can be organized with dataTags and configType.

The vast majority of scripts in tSM are written in SpEL (Spring Expression Language). For a full language reference, see the tSM SpEL chapter. For a hands-on guide to developing and debugging SpEL scripts, see the SpEL Scripts page.

---

Script types

scriptType	Language / Runtime	Description
SPEL	Spring Expression Language	The primary script type. General-purpose business logic, data manipulation, service calls.
TQL	tSM Query Language	Data queries, mostly used for admin scripts. Can also be executed via API with parameter binding.
REPORTING	TQL (reporting context)	Reporting-specific queries for dashboards, pivot tables, and charts. See the Reporting section.
ANSIBLE	Ansible playbook	Infrastructure automation, defined and used by the tSM Service Activation layer.
NETMICO	Python (Netmiko)	Network device management (SSH), defined and used by the tSM Service Activation layer.

---

How scripts are used

Method	Description	More info
BPMN processes	Service Task or listener references the script by code and passes parameters as JSON.	Script Binding, Task Templates
Event bindings	Scripts react to platform events (entity created, ticket closed, timer fired).	Event Bindings
Script-to-script	One script calls another via @script.… syntax.	Script-to-Script Bindings
REST endpoints	Scripts exposed as HTTP endpoints for external consumers.	REST Bindings
MCP tools	Scripts published as AI-callable tools via Model Context Protocol.	MCP Bindings
API	Scripts executed through the tSM Script API, passing parameters in the request body.	—
Forms / UI	Form logic invokes SpEL scripts for validation, data fetching, or side effects via frontend JEXL expressions.	—

---

Parameter and result forms

Scripts support two optional tSM Forms (JSON Schema-based) that define the data contract:

Field	Purpose
paramsFormCode	Defines the input parameters the script expects. The form is displayed before execution (in the SpEL Console, in the UI, or when invoked from a process). It provides validation, autocomplete, and quick documentation for callers — including Script Binding in BPMN processes and frontend JEXL invocations.
resultFormCode	Defines the response structure returned by the script.

This is the same concept used by Task Templates for their configuration forms: a tSM Form that acts as both a UI and a data-model definition.

Because a tSM Form is simultaneously a JSON Schema (data model) and a UI definition, a single artefact covers three concerns at once:

1. Validation — parameters are checked against the schema before execution; type mismatches surface immediately.
2. Documentation — field labels, descriptions, and constraints serve as living API docs for anyone calling the script.
3. UI — the SpEL Console, BPMN modeler, REST bindings, and MCP tool catalog all leverage the schema to render forms, validate payloads, and generate documentation automatically.

The role of paramsFormCode and resultFormCode across binding types is described in each binding's dedicated page:

• Script-to-Script → Using forms
• REST → Using forms
• MCP → Role of forms

---

TQL scripts

TQL (tSM Query Language) scripts are mostly used for admin and data-exploration purposes. They can also be executed via the Script API with parameter binding driven by paramsFormCode.

resultFormCode is rarely used for TQL scripts, but it can describe the expected response format for documentation purposes (no system-level enforcement yet).

---

Reporting scripts

Reporting scripts (REPORTING type) are TQL-based queries used for dashboards, pivot tables, and chart reports. They store additional visualization configuration in the generic config field:

Key in config	Description
pivotConfiguration	Pivot-table layout and field mappings.
chartConfiguration	Chart type, axes, and visual settings.

For details on creating and configuring reports, see the Reporting section.

---

Ansible and Netmiko scripts

Scripts of type ANSIBLE (Ansible playbooks) and NETMICO (Python/Netmiko for SSH-based network device management) are defined and used by the tSM Service Activation layer for infrastructure automation and network provisioning.

---

Execution context

Field	Description
runAsProcessUser	When true, the script runs under the system (process) user instead of the current user. Useful for background tasks or elevated operations.
execPrivilege	Optional privilege code required to execute the script. If set, only users (or roles) with this privilege can trigger it.

---

Transactions

Every SpEL script runs inside a database transaction. Understanding how transactions interact with external calls, async execution, and error handling is critical for correct behavior.

• Synchronous bindings execute inside the caller's transaction — changes are committed or rolled back together.
• Async bindings (async=true) execute after the transaction commits — the script sees a read-only snapshot.
• External calls (REST, SOAP, Kafka) are not part of the database transaction and cannot be rolled back automatically.

For a full discussion of transaction strategies, the {async: true} flag, and #businessException, see:

• SpEL and Transactions — async flag, business exceptions, and compensation patterns.
• Transactions overview — general concepts and the two strategies (delay-until-after-commit vs. send-immediately).
• Process Engine Transactions — transaction boundaries in BPMN processes, external tasks, and the SAGA pattern.

---

Reference

Script (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Identifier (not for end-user display).
code	String	Yes	–	Unique ASCII code (no spaces). Used to reference the script from processes, APIs, and forms.
name	String	Yes	–	Human-readable name shown in admin UI.
description	String	–	–	Optional tooltip / longer description.
validityFrom/To	Date	–	–	Optional window during which the script is considered active.
scriptType	Enum	–	–	Script language/runtime: SPEL, ADMIN, GROOVY, TQL, REPORTING, ANSIBLE, NETMICO.
scriptLanguage	String	–	–	Additional language qualifier (if needed beyond scriptType).
content	String	–	–	The script source code / body.
runAsProcessUser	Bool	–	–	Execute under the system (process) user instead of the calling user. Default false.
execPrivilege	String	–	–	Privilege code required to execute the script.
microservice	String	–	–	Code of the microservice this script belongs to (FK Microservice.code).
listing	String	–	–	Code of the listing this script belongs to (FK Listing.code).
paramsFormCode	String	–	–	Code of a tSM Form defining input parameters (validation, autocomplete, documentation).
resultFormCode	String	–	–	Code of a tSM Form defining response structure (informational; no system enforcement yet).
config	Map	–	–	Metadata for extension
dataTags	List	–	–	Labels for grouping and filtering (e.g., core, integration, reporting).
localizationData	Object	–	–	Translations for name / description.
auditInfo	Object	–	Yes	Standard audit metadata.

---

Good Practices

• Stable code — treat script codes as API contracts. Processes and integrations reference them by code; renaming breaks callers.
• Define paramsFormCode — a parameter form provides validation, autocomplete, and documentation for every caller (UI, process, API, MCP).
• Define resultFormCode — especially for scripts exposed via REST or MCP bindings, so external consumers and AI agents know the response structure.
• Use execPrivilege — protect sensitive scripts (data migrations, bulk operations) with a dedicated privilege.
• Prefer runAsProcessUser sparingly — only enable it when the script genuinely needs system-level access (e.g., cross-tenant operations).
• Organize with microservice — assign ownership so scripts appear in the right admin context.
• Tag consistently — use dataTags to distinguish script purposes (automation, reporting, integration, admin).
• Keep scripts focused — one script, one responsibility. Compose complex flows in BPMN rather than in a single monolithic script.
• Test in the SpEL Console — use the console's debugger and development tools to develop and validate scripts interactively before binding them to processes.
• Understand transactions — read the SpEL and Transactions guide before writing scripts that call external systems.