Listing-Type

Chapter II., Listing-Type Concept, Configuration, and Usage

A Listing-Type in tSM is a reusable configuration object that determines what data is displayed, how it is structured, which operations are available, and which system components consume it. While it serves as the core schema for UI listings, it is equally central for reporting, export/import (backup/restore), notification cards, and widget data sources across the platform.

1. Key Features of Listing-Type Configuration

Entity Assignment
Ensures that each Listing-Type is bound to a specific entity (such as Ticket, Customer, or Order), supporting correct data binding, backup/restore operations, and integration with other modules (e.g., notification cards).
Listing Title
Allows you to set a human-readable title (label) for the listing, which appears in the listing header instead of the default or auto-generated name.
Data Source – ElasticSearch
In addition to the standard database source, you can configure the listing to pull data from an ElasticSearch index.
Default Sorting
Enables you to set a default sort field and order (ascending/descending), ensuring records are displayed as expected when the listing loads.
Column Definitions
Each Listing-Type contains a definition for individual columns, where you configure backend field mappings, UI aliases, visibility, data types, filters, sorting, converters, export options, edit widgets, and permission rules.
Profile Management
Allows configuration of listing profiles specific to users or groups (including visible columns, filters, and sorting). Users can create, share, and assign profiles as needed.
Default Filters
Supports the application of global (system-level) filters that are invisible to end users, for example, to only display active or B2B records.
Inline and Mass Editing
Supports configuration for in-place (inline) editing of individual fields and bulk editing of multiple records at once, including the ability to link to custom scripts or specialized forms.
Nested Data Handling
Allows flattening and displaying of nested entities (such as tasks within a ticket) as individual rows in the listing, while maintaining parent-child relationships.
New Record Form Configuration
For entity creation forms opened from a listing, you can define allowed entity types, the default type, the required privilege to create a specific type, and the label of the form itself.

2. Working with Entity Metadata

Understanding the underlying data structure is essential for configuring Listing-Type columns, filters, and display options effectively. Discovering available fields and relationships helps you:

Correctly map columns to backend fields.
Set up filters, sorting, and converters according to real data types.
Ensure compatibility with integrations, exports, and UI expectations.

2.1 How to Discover Entity Structure

2.1.1 For ElasticSearch

You can discover the available data structure by entering the command select searchHit() from <<indexName>> in the TQL Console. This will display all available fields and information within the selected index.

Example:

select searchHit() from ordering

This command displays the available fields for the “ordering” (orders) index.

The list of indexes can be found in chapter 3.1. Basic Settings (Basic Information Tab).

2.1.2. For SQL

In the main menu (main menu sidebar in the tSM), locate the item tSM Public API.

Select the microservice corresponding to the entity you are interested in.
Choose the version “v2.”
In the list of API operations, find the GET method for the specific entity.

In the example “200” response, you will find the available fields and structure for that entity as provided by the REST API.

3. Configuration of Listing-Type

Configuration of a Listing-Type is performed at {{BaseUrl}}/config/listing-type where BaseUrl is your environment address (e.g., https://tsm-demo.datalite.cloud).

Listing-Type settings are divided into five main tabs:

Basic Information – Core properties and identification settings for the Listing-Type
Columns – Configuration of columns, including data mapping, display settings, formatting, and editing options
Profiles – Management of user and group profiles for customized views, filters, and layout preferences
Config – Advanced settings for view modes, nested data structures, and configuration for creating new records
Mass Editing Configuration – Settings that define and control bulk (mass) editing operations, including which fields and actions are available for batch updates

3.1. Basic Settings (Basic Information Tab)

The Basic Information tab lets you define all core properties of a Listing-Type. Here, you set its technical identifiers (name, code, entity type), data source (ElasticSearch or database), display title, and key integration points such as API URLs.

You can control default sorting, apply global filters, enable or restrict in-place and mass editing, and assign special categorization tags for advanced grouping and selection across the platform.

Every Listing-Type's access, behavior, and integration starts with these settings.

3.1.1. Configuration Options

Tip: Additionally, you will find an interactive guide (form) at the end of this chapter, which not only explains every field but also showcases practical use case examples.

Name and Code:
Each Listing-Type must have both a name and a code.
- The code must be unique among all Listing-Types in the system.
- The name is a human-readable label shown in configuration and in the UI.
  These identifiers are used throughout the platform for referencing Listing-Types in configuration, API calls, navigation, and profile assignment.
Entity Type:
Specifies the main entity (such as Ticket, Customer, or Order) to which this Listing-Type applies.
This field is mandatory and is used for data binding, contextual integration (for example, notification cards rely on correct assignment of entity type), and for backup/restore operations (where the system maps each entity to its corresponding Listing-Type).
ElasticSearch Index Name:
If the Listing-Type retrieves data from ElasticSearch, specify the name of the ElasticSearch index here. If there is no elastic index for selected entity do not fill this input.

Note: The available indices depend on your environment, but typical examples include: customer, account, lead, person, catalogtree, relationshiptree, inventorytree, ordering, ticket, relatedparty, ticket-template, task-main, log, kafkadlq, notification, registervalue, billing-document, billing-cycle, camundatask.

TQL Name:
Technical query name used in TSM Query Language (TQL). This enables integration with reporting, automation, and advanced custom queries. TQL Name must be unique among all Listing-Types in the system. If there is no elastic index for selected entity do not fill this input.
Listing Title:
The human-readable title shown in the listing header (instead of an auto-generated or technical name).
Default Listing-Type:
Indicates if this Listing-Type should be the default configuration for its associated entity. Entity can only have one default listing-type defined. This is important for backup/restore and integrations that use a default Listing-Type if none is explicitly referenced.
Sort Order:
Sets the default sorting state when the listing is loaded in the UI.
Options:
- Not Sorted: No default sorting is applied
- Ascending: Sorted ascending by the field specified in Sort Field
- Descending: Sorted descending by the field specified in Sort Field
Sort Field:
Specifies the field to use for default sorting, in combination with the Sort Order setting.
Frontend URL:
Defines the UI navigation route or target page for this listing. Commonly used for drill-downs from reports or as a target for links.
Backend URL:
Specifies the backend API endpoint for fetching or updating records related to this Listing-Type.
This is essential for data integrations, REST API calls, notification resolution, and export functionality.
Default Condition:
Predefined filter condition(s) that are always applied to this Listing-Type.
These filters are not visible to the end user and are used to restrict or preselect records (e.g., only active items, only B2B customers) and to optimize queries.

Note: Default Filters are only supported when the Listing-Type uses ElasticSearch as its data source. This feature is not available for SQL/database-based listings.

Tip: The examples can be found in an interactive guide (form) below.

Permission to Edit Input Widget:
Specifies the required privilege for using in-place editing in this listing.
By default, all users can use in-place editing; if a privilege is specified, only users with that privilege (or any automatically generated column-level privileges) can use the edit widget.
Enable Mass Editing:
Enables or disables mass (bulk) editing operations for this Listing-Type.
When enabled, checkboxes are shown next to rows, allowing users to select and edit multiple records at once with batch actions.
Config Type:
A general-purpose categorization field that allows you to group Listing-Types—even those associated with different entities—into a shared category or logical grouping.
Commonly used for filtering, selection, and cross-entity configuration in widgets, reporting, dashboards, or other modules where related entities must be handled together.

INTERACTIVE GUIDE - Basic Settings

This example explains the configuration of individual fields for a listing-type in the Basic Information tab.

Detail

Display all tooltips

Entity type:

TQL name:

Sort order:

Config type:

Frontend URL:

Sort field:

Enable mass editing:

Elasticsearch index name:

Listing title:

Permission to edit input widget:

Default listing type:

Backend URL:

Default condition:

Tip: For every Listing-Type, always ensure these primary settings are properly configured and aligned with your use case. They determine not only how data appears in the UI, but also how the listing is used in integrations, reporting, automation, and migration.

3.2. Listing Columns Configuration (Columns Tab)

Details on configuring columns, data mapping, formatting, filtering, editing, and permission rules are covered in Chapter IV., Listing Columns.

3.3. Listing Profiles Configuration (Profiles Tab)

Details on profile creation, sharing, assignment, and advanced usage are covered in Chapter III., Listing Profiles.

3.4. Advanced Listing Settings (Config Tab)

The Config Tab in the Listing-Type configuration provides access to advanced and custom settings that go beyond the basic properties, columns, and profiles. This area is intended for administrators and advanced users who need to:

Define how new records are created from the listing (including allowed types, privileges, and dialog titles)
Configure hierarchical or nested data display (such as flattening arrays/objects for tree views)
Adjust view mode-specific behaviors (like showing expand/collapse columns in tree view)
Integrate with custom automation, default filtering, or workflow logic (through additional, rarely changed configuration options)

These settings give you granular control over user experience, access rights, and data presentation in cases not covered by standard tabs.

3.4.1. Configuration Options

New Record Form Settings

Allowed Entity Types/Subtypes: Specify the codes of entity types that users can create from this listing (e.g., only certain ticket types).
Default Type: Set the code of the entity type that will be pre-selected in the "New Record" dialog.
Privilege for Creation: Define the required privilege code a user must have to create new records from this listing.

Note: The creation privilege applies globally to all allowed types in the dialog. It is not possible to set a different privilege for each type individually; all types configured here require the same privilege to create.

Dialog Title: Override the default label of the creation form for clarity or localization.

Note: New Record Form Settings are currently available for a limited number of entities, but can be extended further as needed. Currently supported entities include: Customer, Person, Campaign, Order, and Order-Line.

Nested Data and Data Flattening

Nested Data Expression: Configure which nested Elastic object (e.g., "tasks" within a ticket) should be flattened and displayed as separate rows in the listing.

View Mode Settings

Expand/Collapse Column (Tree View): Enable this option to add a dedicated column for expand/collapse controls in hierarchical tree view displays.

Advanced Logic & Integration

Custom Automation, Filters, or Workflow Settings: (If supported in your environment) define hooks, filters, or workflow logic for advanced integration or specialized requirements.

INTERACTIVE GUIDE - Advanced Listing Settings

This use case shows how to configure the creation dialog, allowed entity types, and advanced view/nested settings for listings that support creating new records.

Configuration

Display all tooltips

New Record Form Settings

New Form Title:

Allowed Types:

Default Type:

Privilege Code:

View Mode Settings

Expand/Collapse Column (Tree View):

Nested Data Configuration

Nested Data Expression:

3.4.2. Editing Modes: JSON Editor vs. Dynamic Form

Default Mode – JSON Editor
By default, the Config tab displays all advanced Listing-Type settings as a JSON object. You can edit this JSON directly to add, remove, or change any supported configuration property.

Dynamic Form Mode (Schema-Driven UI)
If your tSM environment contains a form with the code Listing.Type.Detail.Config and this form includes definitions for the relevant input fields (text fields, checkboxes, arrays, etc.), the system will automatically show an easy-to-use dynamic form instead of the JSON editor.

This allows safer, more intuitive editing of settings (no need to understand or edit raw JSON).
Whenever a new configuration option is added to Listing-Type, it should also be added to this form definition so users can set it via the UI.
All Listing-Type advanced settings are always saved in the underlying JSON, regardless of editing mode.

3.4.2.1. Example: JSON Editor Mode

Example JSON configuration:

{
  "filteredNested": "task",
  "newRecordConfig": {
    "label": "Create New Ticket",
    "types": [
      "Incident",
      "Request"
    ],
    "defaultType": "Incident",
    "createPrivilege": "Ticket.Create"
  },
  "addEmptyFirstColumnForTreeView": true
}

Field descriptions:

"filteredNested" – Field or expression for nested data to be displayed as rows.
"addEmptyFirstColumnForTreeView" – If true, adds expand/collapse column for tree view.
"newRecordConfig" – Object with all settings for the new record creation dialog:
- "label" – Dialog title.
- "types" – List of allowed entity type codes.
- "defaultType" – Default/pre-selected entity type code.
- "createPrivilege" – Privilege code required for creation.

3.4.2.2. Configuring the Listing.Type.Detail.Config Form

To enable Dynamic Form Mode, you must define a form with the code Listing.Type.Detail.Config and configure input fields for each advanced setting.

Form configuration reference:

Root Level Fields

View Mode Settings - Expand/Collapse Column
Key: addEmptyFirstColumnForTreeView
Widget: Checkbox
Title: Expand/Collapse Column (Tree View)
Tooltip: When enabled, adds a dedicated column with expand/collapse control for hierarchical/tree view display.
Nested Data and Data Flattening - Nested Data Expression
Key: filteredNested
Widget: Text Field
Title: Nested Data Expression
Tooltip: Specify the field or expression for nested data to be displayed as separate rows (e.g., tasks within tickets).

New Record Form Settings (Object: newRecordConfig)

New Record Configuration
Key: newRecordConfig
Widget: Object Layout
Nested widgets:
- Dialog Title
  Key: label
  Widget: Text Field
  Label: New Form Title
  Tooltip: The title that will be shown at the top of the dialog when creating a new record from the listing. If not set, a generic title will be used.
- Allowed Entity Types/Subtypes
  Key: types
  Widget: Array (Text Field for each value, with "+" enabled on array)
  Label: Allowed Types
  Tooltip: List of type codes that will be available for selection when creating a new record from the listing (e.g., order types, ticket types, etc.).
- Default Type
  Key: defaultType
  Widget: Text Field
  Label: Default Type
  Tooltip: The type code that will be preselected when opening the new record form from the listing.
- Privilege for Creation
  Key: createPrivilege
  Widget: Text Field
  Label: Privilege Code
  Tooltip: Privilege code required to create a new record from the listing (e.g., Crm.Customer.Add). Only users with this privilege will see the "Create New" button.

Tip: You can, of course add layout widget to separate configuration in in columns and titles to the each part of configuration.

3.4.3 Using and Maintaining the Config Tab

By default, you edit advanced Listing-Type settings as JSON.
If a correctly-defined Listing.Type.Detail.Config form exists, it replaces the JSON editor with structured fields for easier editing.
When you introduce new advanced configuration fields, add them both to the JSON structure and to the dynamic form schema for consistency and usability.
All properties defined in the Config Tab are essential for advanced display modes, new record dialog customization, hierarchical data handling, and future extensibility.

3.5 Mass Editing Configuration Tab

The Mass Editing Configuration tab allows you to control and define bulk editing (mass edit) capabilities for a listing-type.

3.5.1. Enabling Mass Editing

By enabling mass editing in Basic Settings (see section 3.1. Basic Settings (Basic Information Tab)), checkboxes are added next to each row in the listing, allowing users to select multiple records for batch actions.

3.5.2 Configuration Options

By clicking the “+” button in the Mass Editing Configuration Tab, you can add a new bulk action configuration. The following fields are available for each mass edit action:

Button Label: The text displayed on the mass edit button in the UI.
Button Severity: Visual style or severity indicator for the button (e.g., primary, secondary, danger/warning). This helps distinguish between regular and critical batch actions.
Form: Select the custom form that will be shown to the user when performing this batch action. This form defines which fields will be editable and how the bulk edit will work.
Button Icon: The icon displayed on the button (e.g., tsm-icon-bulk-edit, etc.).
Privilege: The required privilege needed to access and execute this mass editing action. If not specified, all users with basic listing access can perform the action; if set, only users with the specified privilege will see and use the button.
SpEL Script: Mandatory script, that should be executed as part of the mass edit process.

INTERACTIVE GUIDE - Mass Editing Configuration

This use case demonstrates how to configure a custom mass editing (bulk edit) action for records in a listing. These actions appear as special buttons above the listing and enable efficient batch changes.

Display all tooltips

Button Label:

Button Severity:

Form:

Button Icon:

Privilege:

SpEL Script:

Tip: You can define multiple mass editing actions per listing-type. For example, you might have one action for "Bulk Status Change" and another for "Bulk Assignment," each with its own form and permissions.

4. Summary

Listing-Type is the foundational configuration object that defines what data is shown, how it is structured, which operations are available, and how data can be filtered, edited, and integrated across the tSM platform.
Each Listing-Type determines the entity, data source (DB, ElasticSearch, API), columns, filters, sorting, display and editing modes, and integration endpoints for each listing view.
Proper configuration of Listing-Types ensures:
- Consistent and intuitive UI for end users,
- Secure and controlled access to data via role-based permissions and privileges,
- Efficient and safe operations such as inline/mass editing, custom creation forms, and nested data display,
- Seamless integrations with reporting, automation, notification cards, and data migrations,
- Easy extensibility and maintenance via schema-driven forms and support for custom logic or workflow hooks.

A well-designed Listing-Type is not just a technical artifact, but a central building block for business process automation, data governance, and user experience across all modules in tSM. Investing time in designing, documenting, and maintaining Listing-Type configurations will significantly improve the flexibility, reliability, and long-term success of your tSM solution.