Skip to main content

Chapter I – Introduction to tSM JEXL

This chapter provides basic introduction of tSM JEXL language.

This guide is divided into three parts:​

  • In the first chapter, we introduce JEXL, explain where and how it can be used within tSM, and provide basic examples for each usage area.
  • The second chapter covers the basics of tSM JEXL syntax.
  • The third chapter lists all the JEXL commands currently available in tSM.

What is JEXL and Its Role in tSM?​

JEXL (JavaScript Expression Language) is a scripting tool that manages data transformations, calculations, and conditional logic in tSM’s frontend. With JEXL, you can build dynamic forms and pages without deep programming knowledge. By integrating JEXL, you can design more flexible UI elements that respond to specific business needs.

In tSM, JEXL is commonly used for:

  • Dynamic Form Customization: Show or hide fields, cards, and other page elements; set default values; and perform live calculations.
  • Context Manipulation: Use the current context to display relevant data in widgets.
  • Form Data Manipulation: Work with and modify active form data in real time.
  • tSM Data Manipulation: Fetch data from tSM entities (e.g., customers, orders, tickets).
  • Data Transformation: Transform strings, sum values, or filter lists.
  • Advanced Custom Validations: Implement special validations not provided by built-in tools.

How to Use JEXL in tSM​

  1. Open Form Builder: Select the widget where you want to use JEXL and go to its settings on the right side of the screen.
  2. Check the Field:
    • If you see “JEXL” in the top-right corner of the field, that field is already configured for JEXL input.
    • If you see a special symbol on the right side of the field, it starts as a standard input. Clicking the symbol switches the field into JEXL mode, where you can write your expression.

JEXL Debug Console​

  • tSM includes a built-in JEXL debug console. If you have the right permissions, you can enable it in your user settings.
  • Once enabled, a debug console symbol appears on certain pages or forms. Clicking it opens a console with exact data and context for that specific form.
  • This console helps you test or troubleshoot JEXL expressions in real time.

** How to enable debug mode: **

**How to open debug console: **

** And this is how debug console look like, also showing how to get main context of currently opened form or page (with $context command): **

Usage Examples​

1. Dynamic Form Customization​

Scenario
You want to hide a field if the user selects “B2B” in the customerSegment field.

How to Do It

  1. Open the form in the Form Builder and locate the widget you want to hide.
  2. Find the Hidden attribute in the widget’s settings and switch it to JEXL mode.
  3. Insert script:
$context.form.customerSegment == 'B2B'

Explanation

  • This expression returns true when customerSegment is “B2B.”
  • Because true in the Hidden attribute means “hide this field,” the field will disappear whenever the user selects “B2B.”

2. Context Manipulation​

Scenario
On a Customer Detail page, you have a widget for showing contacts. You want this widget to automatically pull and display contacts related to the currently selected customer.

How to Do It

  1. Go to the Customer Detail page in the Form Builder.
  2. Select the contacts widget and switch the relevant data-source field to JEXL mode.
  3. Insert script:
$context.entity

Explanation

  • $context.entity refers to the main entity on the current page, which in this case is the selected customer.
  • By using $context.entity, the widget knows which customer it should display contacts for, making it automatically adapt to whichever customer is open.

3. Form Data Manipulation​

Scenario
You have two date fields in a form. You want to set the second date to be one day after the first date by default.

How to Do It

  1. In the Form Builder, find the second date field’s Default Value attribute.
  2. Switch it to JEXL mode.
  3. Insert this script:
addTime($context.form.chars.date, 1, 'days');

Explanation

  • addTime is a function that adds a specified number of units (days, months, etc.) to a given date.
  • Here, we’re taking $context.form.chars.date (the first date field) and adding 1 day to it. When the form loads, the second date will automatically be set to “first date + 1 day.”

4. tSM Data Manipulation​

Scenario
You want to retrieve data about a specific customer from the tSM database based on their ID and use it in your form or logic.

How to Do It

  1. Locate the widget where you need to display or use the customer data.
  2. Switch the data-related attribute to JEXL mode.
  3. Insert this script:
customer('1f6ea41a-6fba-473c-ace9-399c84166007')

Explanation

  • customer('...') is a built-in function that fetches a customer object from tSM using the provided ID.
  • Once you have this object, you can reference its fields or properties in other parts of the form.

5. Data Transformation​

Scenario: You have a form field called fruits that is an array (e.g., [“apple”, “orange”, “banana”]). You want to check if “apple” is one of the items in that array.

How to Do It

  1. In the Form Builder, go to the attribute where you need this check (for example, a visibility setting, a default value, or a custom calculation field).
  2. Switch to JEXL mode.
  3. Insert this script:
includes($context.form.chars.fruits, 'apple');
// Output: true or false

Explanation

  • The includes function checks if the second argument (in this case, “apple”) exists in the first argument (the fruits array).
  • It returns true if found, false otherwise.

6. Advanced Custom Validations​

Scenario
You have two fields in your form: clientStatus and discountRate. You want a validation rule that says:

  • If clientStatus is VIP, then discountRate must be between 10 and 50 (inclusive).
  • Otherwise, no special validation is needed.

How to Do It

  1. Go to the Validation settings of the discountRate field.
  2. Switch to Custom Validation (JEXL mode).
  3. Insert this script
($context.form.chars.clientStatus == 'VIP') &&
  ($context.form.chars.discountRate < 10 || $context.form.discountRate > 50)

Explanation

  • JEXL validations expect an expression that returns true if the input is invalid.
  • This expression says: “If clientStatus is VIP and the discountRate is outside 10–50, return true (invalid). Otherwise, return false (valid).”
  • For non-VIP users, it always returns false, so there’s no validation error.

Final Note​

These examples should give you a clear, step-by-step overview of how to use JEXL for different tasks in tSM, from hiding fields dynamically to validating data with complex rules. As you become more familiar with JEXL and tSM’s built-in functions, you’ll be able to create even more powerful and customized solutions.