Listing User Guide - Introduction

Preface

This guide is dedicated to the configuration, use, and best practices of the listing component—the universal data grid for displaying and managing tabular data—in tSM. Its content is derived from the tSM Academy training, prepared and delivered by Jan Novák, to whom special thanks are due.

The guide is intended for system administrators, power users, analysts, and anyone involved in defining or maintaining listings within tSM. It provides a comprehensive, practical reference for configuring and customizing listings.

1. Key Concepts and Functionality

2. Introduction

Listings are the primary UI components in tSM for presenting collections of data—whether these are records from entities (such as customers, orders, or tickets), or arbitrary datasets from internal or external sources.

Every listing is configured using three main building blocks:

Component	Description
Listing Type	Configuration object defining which data is shown, how it is structured, and what operations and views are available.
Listing Column	Definition of individual data fields/attributes (mapping to backend or Elastic), including all display, export, edit, and permission settings.
Listing Profile	User- or role-specific configuration that determines which columns, filters, order, and display settings are active for a given user.

2. Distinction: Listing vs. Listing Type

While a Listing is a runtime, visual component, a Listing Type serves as a reusable schema that can be referenced by various modules: not only UI listings, but also form dropdowns, notification cards, reporting, backup/restore logic, and more.

Concept	Definition	Typical Usage
Listing	UI component that displays a data collection (in tabular, hierarchical, card, or board form)	Frontend – UI tables/lists, interactive filtering, editing, exporting, in-place updates
Listing Type	Configuration object that defines structure, filtering, columns, and behavior of a Listing	Backend & frontend – reporting, backup/restore, widgets, data selection, configuration profiles

3. Core Features of Listing (UI Component)

• Multiple Display Modes: Table, tree, card, and Kanban board formats.
• Dynamic Filtering, Full-Text Search, Sorting, and Paging: Provides flexible data exploration and manipulation.
• Inline (In-Place) Editing and Bulk Operations: Enables efficient updates directly within the listing.
• Data Export: Supports export to Excel and other formats.
• Per-Column Access Control: Enforces granular permissions on individual columns.
• Scripting Support: Enables custom logic (e.g., Painless scripts for Elasticsearch integration).

4. Core Features of Listing-Type (Configuration)

A Listing Type defines the structure and behavior of a listing and serves as a reusable schema in multiple application contexts. Its role includes:

• Specifying the entity or dataset to display.
• Defining columns:
• Field mapping to backend attributes
• Filter types, default values
• Sortability, visibility, permissions
• Data converters and rendering rules
• Defining available view modes and supported actions (edit, export, etc.).
• Including metadata for linking to APIs, Elasticsearch indexes, or microservices.

Beyond visual listings, listing types are reused as key definition mechanisms in other components:

Component	How Listing Type is Used
Notification Cards	Determines which fields to show in summary or alert messages.
Forms	Used to populate dropdowns or lookup widgets with entity lists.
Backup/Restore	Defines which fields are included in export/import of data configurations.
Reporting	Supplies the structure for pivot tables, charts, and summary reports.
Access Rules	Used to define scope-based visibility or permissions via TQL filters.

Note: A single entity can have multiple listing types—for example, one for displaying basic info, another for reporting, and a third for use in a widget or modal.

5. Core Features of Listing Columns

• Field Mapping: Enables display of specific data by mapping each column to a unique backend or Elasticsearch field.
• Custom Display Name (Alias): Allows showing user-friendly labels in the UI, independent of backend field names.
• Visibility Control: Sets whether a column is visible or hidden in different display modes (table, card, tree, etc.).
• Data Type and Formatting: Supports various data types (string, number, date) and custom formatting for each column.
• Filtering and Sorting: Defines available filter types and operators per column, default filters, and sorting options.
• Editing: Enables in-place editing directly within the listing using various widget types (input, select, number, date, lookup).
• Converters: Automatically transforms technical or coded values into readable labels, using frontend or backend converters.
• Export Settings: Specifies whether and how a column is included in exports (e.g., to Excel) and the format for export.
• Permission Control: Provides granular control over visibility and editing rights per column, configurable per user, role, or context.

6. Core Features of Listing Profiles

• Personalized Views: Users can customize visible columns, column order, active filters, sort order, and row count to suit their needs.
• Profile Sharing: Users can share saved profiles with others, with read-only or editable (owner) permissions.
• Default Profiles: Administrators can define default profiles for roles or modules, enforcing pre-configured views and filters.
• Automated Export and Reporting: Profiles can be linked to scheduled or on-demand exports and reports, ensuring consistent outputs.
• Multi-Mode Display Settings: Each profile stores separate configuration for table, card, or tree view modes.
• Persistent Context: Profiles save the user’s last-used configuration—including column widths, order, filter states, and view settings—persisting preferences across sessions.

7. Key Terminology

Term	Description
Listing	UI component that displays a collection of entity records (rows + columns).
Listing Type	Definition of structure and behavior for a listing; reused platform-wide.
Column	Attribute defined in listing type, including display logic and filters.
Profile	User-specific configuration of a listing (selected columns, filters, order).
Widget	UI element used for editing/filtering data in listings (input, select, etc.).
Converter/Pipe	Transformation function (ID → name) for displaying human-readable values.
Permissions	Access control for listings and individual columns/actions.

8. Summary

Listings provide the main user interface for interacting with multiple records in tSM, supporting advanced filtering, editing, sorting, exporting, and multiple display modes.

Listing Types serve as reusable configuration objects that define the structure, columns, operations, permissions, filters, and integration points for listings and related system components.

Listing Columns control how individual data fields are displayed, formatted, filtered, edited, exported, and secured within each listing.

Listing Profiles allow users and administrators to personalize and persist their preferred combinations of visible columns, filters, sorting, and view modes for different use cases.

Clear distinction and correct configuration of Listings, Listing Types, Columns, and Profiles are essential for:

• Ensuring consistent and reliable data presentation
• Supporting flexible business requirements and workflows
• Enabling secure and granular access control
• Facilitating efficient reporting, exporting, and system integration Well-designed Listing Types and Profiles are critical for maximizing usability, maintainability, and data governance throughout the tSM platform.