Skip to main content
Version: 2.4

SpEL Scripts

This page is a hands-on guide for developing and debugging SpEL scripts inside the tSM platform. For the entity definition, all script types (TQL, Reporting, Ansible, …), and the attribute reference, see Script.

Opening the SpEL Console​

The SpEL Console is the built-in development environment for SpEL scripts. You can open it in two ways:

ModeHow to openUse-case
Without contextIn the main left menu, search for spel and select SpEL Console.Quick experiments, standalone utilities.
With contextOpen an entity (order, ticket, …), click the ⋯ menu and choose SpEL Console.When you need context variables such as #order or #ticket.

When opened with context, the console automatically injects the entity as a variable (e.g. #order, #ticket) so you can reference it immediately in your script.

Console layout​

The SpEL Console is split into two panels:

AreaPurpose
Left panel — Script editorThe code editor with syntax highlighting, autocomplete, and line numbers. This is where you write and edit the SpEL expression.
Right panel — Script detail & toolsTabs for metadata, execution results, debugging output, and more (see sections below).

The microservice selector in the top-right corner lets you choose which backend service context to execute against (e.g. Ordering, Ticketing, Catalog).

Script selection and metadata​

When you open the SpEL Console, you can select an existing script or create a new one. The right panel shows the script's metadata:

  • Name and code — the human-readable name (e.g. Order / Get / Products) and the stable code (e.g. Order.Get.Products) used to reference the script from processes, bindings, and APIs.
  • Description — a brief explanation of what the script does and when it is used. Always fill this in; it appears in the SpEL Console, in binding configurations, and as tool descriptions for MCP bindings.
  • Owner entity type — optional badge (e.g. ORDER) indicating which entity type this script is designed for.
  • Tags and config type — use dataTags to categorize scripts (automation, integration, reporting, …) and configType for grouping in admin views.
  • Audit info — automatic metadata showing who last updated the script and when.

Input and output attributes​

Defining parameters with paramsFormCode​

The Input Attributes section of the script detail lets you attach a tSM Form that defines the script's input parameters. This form — identified by paramsFormCode — is designed using the standard tSM Form Designer.

Because a tSM Form is both a JSON Schema (data model) and a UI definition, one artefact serves multiple purposes at once:

PurposeHow it works
ValidationParameters are validated against the JSON Schema before the script executes — in the SpEL Console, via API, in BPMN Script Binding, or through REST / MCP bindings.
DocumentationField names, types, descriptions, and constraints act as living API docs for anyone calling the script. AI agents (via MCP) use the schema as the tool's inputSchema.
UIThe SpEL Console renders the form so you can fill in parameter values interactively before running the script. The BPMN modeler and Task Templates render it too.

Defining results with resultFormCode​

The Output Attributes section works the same way: attach a tSM Form (resultFormCode) that describes the result structure the script returns. This is used for:

  • Documentation — callers know the shape of the response.
  • MCP — the form's JSON Schema becomes the tool's output schema so AI agents can parse the result.
  • UI — when a result form is selected, the console can display the output in a structured form view rather than raw JSON.

When no output form is selected the console shows "No form selected" and you can toggle between a rendered form and a raw JSON view.

tip

Always define paramsFormCode on scripts that are called from multiple places. It makes the script self-documenting and prevents callers from passing invalid data. See the Script reference for the full explanation.

Execution and debugging​

Running a script​

Click the Run button (or the keyboard shortcut) to execute the script against the selected microservice context. If the script defines a paramsFormCode, fill in the parameter form first — the console validates inputs before submission.

The result appears in the Result tab on the right panel.

Debugger​

The SpEL Console includes a step-through debugger similar to Chrome DevTools:

ToolWhat it does
Step OverExecute the current expression and move to the next one.
ContinueResume execution until the next breakpoint or the end of the script.
VariablesInspect all current context variables (#ticket, #order, custom variables, …) and their values at the current step.
WatchAdd expressions to evaluate live at each step (e.g. #offers.size(), #total > 100).

The debugger lets you inspect intermediate values at every step, making it easy to trace data flow through complex scripts.

Comments​

The Comments tab on the right panel provides a collaborative space to leave notes on a script — execution history, known issues, or review comments. Comments support filtering and can be used as a lightweight review mechanism.

Stacktrace​

When a script throws an exception, the Stacktrace tab displays the full backend stack trace. This includes:

  • The exception type and message — e.g. ApiValidationException: Customer segment is blocked.
  • The full Java stack trace from the backend — useful for identifying which service method or SpEL expression caused the failure.
  • The SpEL expression line where the error occurred — the console highlights the relevant line in the editor.

This is the same information you would see in backend logs, but surfaced directly in the console for faster debugging. For complex issues, you can copy the traceId from the stacktrace and search for it in Kibana to see the full distributed trace.

Kibana integration​

The Result tab provides a direct link to open the script execution in Kibana. This lets you see everything that happened during the script evaluation:

  • All log entries generated by the script (via @logger.info(…) or @log.log.create(…)).
  • HTTP calls made to external systems via @tsmRestClient or @tsmSoapClient.
  • Database queries triggered by service method calls.
  • Timing information — how long each operation took.

The link is pre-filtered by the execution's traceId, so you see exactly the log entries for that specific run. For more context on how external calls interact with transactions, see SpEL and Transactions.

Spreadsheet​

The Spreadsheet tab provides a tabular interface for working with data:

Use-caseHow
Load input dataImport data from a spreadsheet (CSV, Excel) to use as script input — useful for bulk operations or data migrations.
View outputWhen a script returns a list or table-like structure, render the result as a spreadsheet for easy inspection, sorting, and filtering.
ExportExport the script's output to a spreadsheet file for downstream use (reporting, sharing with stakeholders).

This is powered by the tSM Spreadsheet component. It is particularly useful for scripts that process collections — you can visually verify each row of the result without reading raw JSON.

Attachments​

The Attachments tab lets you attach files to the script — reference documents, sample data files, configuration exports, or screenshots that help other team members understand the script's purpose and usage.

See also​