Skip to main content

tSM Inventory Management

The tSM Inventory Management module is a central component for managing and tracking the active usage (instances) of products, services, resources, or other entities in time. While the Catalog Module defines what can be offered (with specifications and relationships), the Inventory Module focuses on how these offers become active and evolve throughout their lifecycle. The key objects in the Inventory Module are:

  1. EntityInstance – a container for an actual product, service, or resource being used by a customer or within the organization.
  2. EntityInstanceConfiguration – a time-based record that describes how a particular EntityInstance is configured.
  3. EntityInstanceConfigurationRelationship – references or links among multiple EntityInstanceConfigurations defined in the Catalog specification. These are secondary relationships additional to parent-child which is inherent part of EntityInstanceConfiguration using parentId attribute.

service_inventory.png

1. EntityInstance​

An EntityInstance represents a unique “thing” in the system—a product subscription, a service instance, a resource installation, or any other item the business needs to track. Key points:

  • Business Key: Each EntityInstance has a readable identifier (for example, “SUB-12345”) that may appear on bills, in CRM, or on operational dashboards.
  • Type: Typically something like PRODUCT, SERVICE, or RESOURCE.
  • Lifecycle: The EntityInstance itself persists as long as the “thing” remains relevant. When the instance is canceled or retired, that EntityInstance is flagged as inactive or historical.

Example: Broadband Subscription​

A single broadband subscription, such as “SUB-1001,” is created when a customer orders an internet plan.

{
  "id": "e341f37b-34d3-4ba2-8e8c-cbd975dcfa14",
  "type": "PRODUCT",
  "key": "SUB-1001",
  "dataTags": ["VIP-CLIENT", "FIBER-CONNECTION"]
}

2. EntityInstanceConfiguration​

Each EntityInstance can have multiple configurations over its lifetime, representing how the instance is set up at any given time. A configuration is inextricably tied to a Catalog Specification (the definition of the product or service). Consequently:

  • Must Reference a Catalog Specification: An EntityInstanceConfiguration cannot exist on its own; it always references a specific “EntityCatalogSpecification.”
  • Time-Based: Configurations carry valid-from/valid-to dates and a status that indicates when and how long they are in effect.
  • Lifecycle Status: A configuration may be “current” (fully active), “pending” (awaiting provisioning), or “history” (past state).
  • Characteristics (chars): Instead of a rigid data model, flexible JSON-like fields are used to store attributes such as speed, hardware addresses, discount codes, etc.

Non-Overlapping Configurations​

Only one “current” configuration can apply at a time for a single EntityInstance. If a new configuration is scheduled (e.g., an upgrade or parameter change), you create a second record in “pending” status. When the pending state becomes active to a particular date, previous "current" configuration must be transitioned to "historical" state.

Business Example: Upgrading Broadband Speed​

A customer with the “SUB-1001” broadband subscription starts at 20 Mbit/s and later upgrades to 40 Mbit/s:

  • Configuration #1 (Current from 2025-01-01 to 2025-03-14):

    {
      "entityInstanceId": "e341f37b-34d3-4ba2-8e8c-cbd975dcfa14",
      "entityCatalogSpecificationId": "0bdab8c5-b2b2-45f3-bfe3-1fb7e6a33759",
      "name": "20 Mbit/s Plan",
      "status": "ACTIVE",
      "active": "CURRENT",
      "validFor": {
        "startDateTime": "2025-01-01",
        "endDateTime": "2025-03-14"
      },
      "chars": {
        "speed": 20,
        "bandwidthUnit": "Mbit/s"
      }
    }

  • Configuration #2 (Pending upgrade to begin on 2025-03-15):

    {
      "entityInstanceId": "e341f37b-34d3-4ba2-8e8c-cbd975dcfa14",
      "entityCatalogSpecificationId": "0bdab8c5-b2b2-45f3-bfe3-1fb7e6a33759",
      "name": "40 Mbit/s Plan",
      "status": "PENDING",
      "active": "PENDING",
      "validFor": {
        "startDateTime": "2025-03-15"
      },
      "chars": {
        "speed": 40,
        "bandwidthUnit": "Mbit/s",
        "discount": "SPRING23"
      }
    }

Once provisioning is finished for Configuration #2 (around March 15), the system sets #2 to “CURRENT” and updates #1 to “HISTORY.”

3. EntityInstanceConfigurationRelationship​

In many scenarios, multiple configurations need to link together. This linkage can be:

  • Parent-Child: A hierarchical relationship, often for decomposing a main service into sub-services or physical resources. For example, a “Broadband Service” configuration might have a child that represents “Wi-Fi Access”. This type is represented only by parentId in EntityInstanceConfiguration and does not need special relationship entity.
  • Secondary: Parallel or complementary links, such as promotional add-ons or supplementary items. These relationships generally correspond to rules or relationships defined at the Catalog level.

Catalog-Defined Relationships​

Because the Catalog Module defines which items can be bundled or must accompany another, an EntityInstanceConfigurationRelationship references the specific “entityCatalogSpecificationRelationshipId” to maintain consistency between design-time (Catalog) and run-time (Inventory).

Relationship Example: Router Rental​

A broadband plan can require a rental router. In the Catalog, we might have a “Broadband” specification and a “Router” specification, linked by a “mandatory hardware” relationship. In Inventory, you would create:

  1. EntityInstance – “SUB-1001” (the subscription).
  2. EntityInstanceConfiguration – “40 Mbit/s Plan,” referencing the broadband specification.
  3. EntityInstanceConfiguration – “Router Model X,” referencing the router specification (it might be a separate EntityInstance or part of the same entity, depending on your business model).
  4. EntityInstanceConfigurationRelationship: 
    {
      "entityInstanceConfigurationId": "c74fbec2-01ab-4d82-8e22-5b216c3f8e55", 
      "entityInstanceToId": "62f59d63-8e45-4c2e-b8c9-3a1139c322bd",
      "entityCatalogSpecificationRelationshipId": "b73c376b-543f-4247-bb6f-15ee378faa2a",
      "chars": {
        "relationshipType": "MANDATORY_HARDWARE",
        "rentalFee": 5
      }
    }
    • entityInstanceConfigurationId references the broadband plan’s configuration.
    • entityInstanceToId references the router entity instance.
    • entityCatalogSpecificationRelationshipId ensures this link matches the underlying Catalog definition of a mandatory hardware relationship.

This approach guarantees alignment between the service design (Catalog) and the service deployment (Inventory).

4. Parent-Child Configuration Trees​

Many service or product offerings have a natural tree structure. For instance:

  • Parent Configuration: “Enterprise Fiber Connection – 1 Gbit/s.”
  • Child Configurations:
    • “Static IP Block”
    • “Managed Router Service”
    • “Voice Over IP Extension”

Each child is tracked as its own EntityInstanceConfiguration but is connected via a parent-child relationship. This allows partial changes (e.g., upgrade the router or swap the IP block) without affecting the top-level service or other siblings.

5. Extended Business Scenarios​

A. Enterprise Service with Multiple Sites
A corporate account might have a “Global WAN Service” as the parent. Children configurations represent each site (e.g., “Branch Office in Prague,” “Branch Office in London”). Each child is an EntityInstanceConfiguration with its own link to an underlying Catalog specification for site-level connectivity. Additional sub-children might handle local IP phones or Wi-Fi hotspots.

B. Product Bundles with Promotions
If a mobile operator bundles “Mobile Plan” + “Streaming App,” these relationships exist in the Catalog as an optional add-on. When a customer picks the bundle, two configurations appear in Inventory: one for the main plan, one for the add-on. A relationship object references the “PROMO-BUNDLING” definition from the Catalog. This ensures correct billing and provisioning flows.

C. Resource Instances in a Warehouse
An equipment inventory might track each router or set-top box as an EntityInstance. If a device is installed at a customer site, its configuration references the location data and possibly a parent service configuration. When the device is returned (e.g., after contract cancellation), that instance updates to show it is back in the warehouse with a new status or new configuration record.

6. Summary of Key Points​

  1. EntityInstance is the root identifier for a product, service, or resource in use. It remains the same as multiple configurations come and go.
  2. EntityInstanceConfiguration always references an Entity Catalog Specification (from the Catalog Module). It cannot be created without specifying which catalog definition it aligns to.
  3. Relationships among configurations are recorded as EntityInstanceConfigurationRelationship objects, referencing the relevant specification relationship in the Catalog.
  4. Lifecycle & Validity: Configurations use statuses (ACTIVE, PENDING, HISTORY) and date ranges. Only one configuration can be “current” at a time per instance, with no overlapping validities.
  5. Parent-Child Trees: Provide hierarchical decomposition for complex services or multi-component products, reflecting real-world usage.
  6. Secondary Links: Cover mandatory or optional add-ons, promotions, or other custom relationships guided by the Catalog.

By adhering to these principles and referencing the underlying Catalog definitions, the tSM Inventory Module ensures a consistent “design-to-run” workflow. It captures not only what the customer has but how it is configured, when changes occur, and why certain relationships exist—all in a time-aware, audit-friendly manner that integrates seamlessly with provisioning, billing, and trouble-ticketing processes.