Skip to main content

tSM Entities & Characteristics

The tSM platform has a core infrastructure designed to support and extend business entities. tSM follows the TM Forum standard, allowing modules to create core business entities such as Customer or Ticket using standard data modeling (stored in relational tables, ElasticSearch, Kafka). These entities are built with attributes that conform to the TM Forum model.

When there is a need to extend the standard model, you can create custom types of entities (e.g., Retail Customer) and add new attributes using the Characteristics pattern. This enables the system to flexibly handle more specific or project-based requirements while maintaining a strong core structure.

Each entity in tSM is uniquely identified by a combination of ID and Type, ensuring consistent and precise referencing across the system. Entities are organized into different types, which allow for further modularity and configuration.

Entity Overview​

Each entity in tSM is uniquely identified by a pair of ID and Type:

  • ID: Must be unique within the same Type, typically using UUIDs for native tSM entities.
  • Type: A unique string, often a short class name on the backend (e.g., Customer, Ticket, EntityCatalogSpecification).

Entities of the same type share core attributes but may differ in their dynamic characteristics (configured through Config & Forms). More granular classification, such as distinguishing between Retail and Wholesale customers, is handled through EntityTypes (CustomerType in this case) and associated Configuration Profiles.

The same system handles both internal and external entities, such as resources from other systems (e.g., NIResource, BankAccount, Invoice, UsageRecord). Each entity's ID and Type combination guarantees unique identification across the system.

Configuration Profile & Characteristics​

For finer classification into subtypes (e.g., Customer: Retail, B2B, Wholesale), Configuration Profiles are used. A Configuration Profile contains:

  • Characteristics: Dynamic attributes (beyond the core) the entity type will include. These attributes are linked with a form defining their display.
  • FormSpecification: Configured forms applicable to this specification.
  • CommentTypes: Allowed types of comments for this entity specification.
  • AttachmentTypes: Allowed attachments for this entity specification.
warning

According to the TM Forum, a Configuration Profile is named EntitySpecification. To conform to this standard, tSM uses the term EntitySpecification in its API and backend systems, while the UI refers to it as a Configuration Profile.

Characteristics define dynamic attributes using JSON Schema. The Form Designer tool in tSM allows easy creation of forms for displaying these attributes. A characteristic in tSM is defined as:

  • Form: The JSON Schema defining the structure and display.
  • attributeName: The name used when storing the characteristic in EntitySpecification.
  • Privileges: Read/write permissions.
  • ElasticSearch behavior: Indexing behavior (untyped, typed, etc.).
  • Form display order: Position of the characteristic on forms (e.g., customer-detail).

Characteristics can be shared across multiple Configuration Profiles. However, within the same EntityType, characteristics with the same attributeName must be identical to ensure consistent interpretation across specifications.

entity_specification_pattern.png

TM Forum Characteristics Pattern​

The Configuration Profile conforms to the TM Forum Characteristics Pattern, a widely adopted standard for defining dynamic attributes for various entity types. These characteristics serve as reusable components that can be shared across multiple entity specifications, ensuring a standardized approach to defining and managing entity attributes. Each characteristic can represent a simple field (e.g., speed) or a complex object (e.g., a billing address), supporting both basic and advanced entity configurations.

By following the TM Forum pattern, tSM ensures compatibility with global telecom standards, making it easier for organizations to integrate the platform into existing OSS/BSS ecosystems.

Please note, that internal tSM Data Structure is not following strictly TM Forum SID model, but the API is designed to be compatible with it.

Motivation​

The TM Forum standard provides a structured and standardized method to define entities and their attributes (Characteristics). By following this pattern, organizations can extend their data model without modifying core structures, thus maintaining backward compatibility and ensuring a smooth path for future expansions.

For example, consider an EntitySpecification that represents a specific product type: a "Linksys USB Ethernet Cable Modem DOCSIS." Each section of this product’s definition—such as Features, Description, Additional Info, and Shipping Info—can be represented as a CharacteristicSpecification or a composite of multiple specifications. Using CharacteristicSpecRelationship, multiple characteristic definitions can be combined into a complex structure that reflects hierarchical or nested attributes.

Key Elements​

  • EntitySpecification:
    The base entity to which characteristics are applied. This can represent, for example, a catalog entry, a customer type, or a specific product.

  • CharacteristicSpecification:
    Defines the details of a single characteristic (attribute). A critical parameter is valueType, which indicates whether the characteristic is a simple data type (e.g., string, number) or a complex structure defined via a JSON schema.

  • EntitySpecCharUse:
    Associates a particular CharacteristicSpecification with a given EntitySpecification, effectively assigning that attribute to the entity type.

  • CharacteristicSpecValue:
    Defines allowed values for a characteristic, particularly useful for enumerations. This ensures that only predefined, controlled values are used.

JSON Schema-Based Approach​

By leveraging JSON Schema, it’s possible to define characteristics as complex data types, including validation rules, required attributes, and enumerations. For example, a "Virtual Storage" product specification might be defined as:

{
 "$schema": "http://json-schema.org/draft-07/schema#",
 "$id": "VirtualStorage.schema.json",
 "title": "VirtualStorage",
 "definitions": {
   "VirtualStorage": {
     "$id": "#VirtualStorage",
     "description": "This product specification defines the virtual storage medium.",
     "type": "object",
     "properties": {
       "Maximum Allowed Storage": {
         "type": "number",
         "description": "The storage limit in the virtual storage medium",
         "enum": [
           1024000,
           2048000
         ]
       }
     },
     "required": [
       "Maximum Allowed Storage"
     ],
     "allOf": [
       {
         "$ref": "Product.schema.json#Product"
       }
     ]
   }
 }
}

Entity Types​

Entities in tSM are categorized into groups that share common properties, such as how they are identified and how they relate to other entities. Each entity has a primary key represented as a UUID (globally unique) and a business identifier, which is unique within its business context.

  • For core entities like Customer or Ticket, the business identifier is the key that must be unique across the entire database.
  • For reference entities, such as code tables, the business identifier is the code, which must be unique within its specific register or context.
  • For child entities, the primary key (UUID) serves as the unique identifier, while the business ID is only unique within the parent entity (e.g., within a catalog or register).

These categories ensure that tSM maintains consistent identification and business logic across various entity types:

  • Core Entity Types: Main business objects like Account, BillingDocument, and Ticket. These entities have a unique business identifier, which must be globally unique across the system.

  • Code Table Entities: These entities, like BillingCycleType or LeadSource, are used for configuration and reference purposes. The business identifier is typically the code, and it must be unique within the scope of the code table (e.g., a register or category).

  • Data Entities: Key transactional or process-related entities, such as Attachment, TicketRelationship, and Notification. They ensure that operational and event data is tied back to core entities.

  • Reference Entities: These define relationships between different entities, such as AttachmentRelatedEntity and NotificationRelatedEntity. The business identifier for these entities typically involves a reference key (refId/refType) to establish the linkage between entities.

  • Owned Entities: These entities are owned by a parent object, such as Calendar or Worklog. They inherit context from their parent entity, with the UUID serving as the unique identifier within the ownership relationship.

  • Child Entities: Examples include catalog items like EntityCatalogCategory or EntityCatalogSpecification. These entities have a business ID that is unique within the context of a parent entity, like a catalog (e.g., B2B Product Catalog), ensuring that items within a specific category or register are uniquely identified.

This structure ensures that entity identification in tSM remains consistent, scalable, and compliant with both global standards and business-specific requirements.

Module, ConfigType & Tags​

To group entities and related configurations (forms, processes, code tables, etc.), tSM uses a Module system. For example, the Ticketing module may be divided into Service Assurance, Change Management, and Issue Tracking. A module contains:

  • moduleType: A value that ties the module to core use cases (e.g., BasicTsmModuleType for Ticketing/Change Management).
  • formSpecification: Defines extensions to standard forms, adding dynamic parts at the module level (e.g., extra attributes for code tables).
  • config: Additional data for configuration.

ConfigType allows the configurator to link all elements related to one business functionality. Additionally, tags can be used for even finer grouping of items related to one release.

Entity relationships in tSM use the uniqueness of ID and Type to link one entity to another across microservices. Depending on the relationship's purpose, terms like ownerId/ownerType or refId/refType are used.

For more complex relationships, tSM uses the Related entity system (e.g., RelatedEntity and RelatedParty in ticketing). Each relationship type is defined, specifying:

  • entityType: The type of entity that can be the target of the relationship.
  • entitySpecification: Subtype constraints for the target entity.
  • form: The form defining the relationship's data.

In RelatedEntity/RelatedParty, tSM maintains:

  • Controlling entity (e.g., ticket).
  • Target entity (refId/refType pair).
  • RefData: JSON structure to store entity data when external data isn't readily available.
  • Data: The relationship data managed by a form.

Conclusion​

The entity management system in tSM, with its modular and configurable design, provides a robust framework for handling a wide variety of entity types and their dynamic attributes. By leveraging EntityType, Configuration Profiles (EntitySpecification), and Characteristics, tSM allows both internal and external entities to be managed effectively within a telecommunications environment.