5.412 min read

Inventory & Resource APIs

Inventory & Resource Management APIs

Inventory APIs track what actually exists in a telco's environment. While catalog APIs define what is possible (design-time blueprints) and order APIs capture what is being requested (runtime transactions), inventory APIs are the authoritative record of current state -- the products a customer has, the services running on the network, and the resources allocated across the infrastructure.

The inventory triad -- TMF637 (Product Inventory), TMF638 (Service Inventory), and TMF639 (Resource Inventory) -- mirrors the catalog triad exactly. Each inventory API manages instances of the specifications defined in its corresponding catalog API. Additionally, TMF685 (Resource Pool Management) provides specialised management for pools of allocatable resources.

The Specification / Instance Pattern

TM Forum architecture distinguishes between specifications (what something looks like) and instances (a specific occurrence of that type). Catalog APIs manage specifications; inventory APIs manage instances. A ProductSpecification "Fixed Broadband 100Mbps" in TMF620 may have thousands of Product instances in TMF637, one per customer subscription.

TMF637: Product Inventory Management

TMF637 -- Product Inventory Management

TMF637 manages the product inventory -- the record of all product instances that have been provisioned to customers. It answers the question: "What does this customer currently have?" Each product instance links back to its ProductSpecification (from TMF620) and contains the specific characteristic values for that customer.

Product inventory is the BSS source of truth for subscription management. Billing reads it to know what to charge. CRM displays it for customer service agents. Digital channels query it for self-service account views. Order management checks it before processing modify or cease orders.

TMF637 Key Resources

TMF637 Core Resources

Resource	Purpose	Key Attributes
Product	An instantiated product for a specific customer	name, status, startDate, terminationDate, productSpecification, productCharacteristic, productRelationship, relatedParty, productPrice, place

Product Instance States

Product Instance Lifecycle States

State	Meaning	Billing Impact
Created	Product instance created but not yet active	No billing
PendingActive	Fulfilment in progress	No billing (or pre-billing in some models)
Active	Product is live and in use	Full billing applies
Suspended	Temporarily disabled (e.g., non-payment)	Billing may continue or be paused
PendingTerminate	Cease order in progress	Billing until termination completes
Terminated	Product permanently removed	Final bill generated

Querying Product Inventory

To display a customer's active products: GET /product?relatedParty.id=CUST-12345&status=Active. This returns all active product instances for customer CUST-12345, including characteristics like speed, contract term, and pricing. Each product instance includes a productSpecification reference that links back to the catalog definition.

TMF638: Service Inventory Management

TMF638 -- Service Inventory Management

TMF638 manages the service inventory -- the record of all CFS and RFS instances that are currently instantiated on the network. It answers the question: "What services are running, and what are their parameters?" Service inventory is the OSS source of truth for service state.

Service inventory sits between product inventory and resource inventory. Each service instance (CFS or RFS) links upward to a product instance (via TMF637) and downward to resource instances (via TMF639). This three-layer linkage provides full traceability from customer subscription to network element.

TMF638 Key Resources

TMF638 Core Resources

Resource	Purpose	Key Attributes
Service	An instantiated service (CFS or RFS)	name, state, serviceType, serviceSpecification, serviceCharacteristic, supportingService, supportingResource, serviceRelationship, relatedParty, place

The supportingService attribute is particularly important -- it links a CFS instance to its supporting RFS instances, maintaining the decomposition chain at the instance level.

Service Instance States

Feasibility Checked -- Service feasibility has been verified
Designed -- Service has been designed but not yet provisioned
Reserved -- Resources reserved for this service
Active -- Service is live and operational
Inactive -- Service is provisioned but not active
Suspended -- Service temporarily suspended
Terminated -- Service permanently removed

Service Inventory for Impact Analysis

Service inventory is critical for assurance and change management. When a network element fails, the question "which customers are affected?" is answered by querying TMF638: find all service instances with supportingResource references to the failed element, then trace upward through product inventory to identify affected customers. This is the foundation of service impact analysis.

TMF639: Resource Inventory Management

TMF639 -- Resource Inventory Management

TMF639 manages the resource inventory -- the record of all physical and logical resources in the network. It tracks what equipment is deployed, what logical elements are configured, and their current state and relationships. Resource inventory is the network-level source of truth.

Resource inventory is the most granular inventory layer. It tracks individual ports, VLAN assignments, IP addresses, routing entries, and physical equipment. Every resource instance links to a ResourceSpecification from TMF634 and may be referenced by service instances in TMF638.

TMF639 Key Resources

TMF639 Core Resources

Resource	Purpose	Key Attributes
Resource	An instantiated physical or logical resource	name, resourceStatus, resourceSpecification, resourceCharacteristic, resourceRelationship, relatedParty, place, note

Physical resource instances represent deployed equipment with specific identifiers and locations:

OLT-EAST-07: Huawei MA5800-X17, Rack 3, Slot 2, Site: East Exchange
ONT-CUST-12345: Nokia G-240W-F, Serial: ALCL-A1B2C3, Installed: 42 Oak Street
Router-CORE-01: Cisco ASR 9006, Interfaces: 48x10GE + 12x100GE, Site: Core POP
Antenna-SITE-15-S1: Ericsson AIR 6449, Band: n78 (3.5GHz), Sector: 1

TMF685: Resource Pool Management

TMF685 -- Resource Pool Management

TMF685 manages pools of allocatable resources -- collections of resources that can be drawn from during fulfilment. Examples include IP address pools, VLAN ID ranges, MSISDN number blocks, and equipment inventory pools. It provides reserve, allocate, and release operations for pool members.

Resource pools are essential for automated allocation during fulfilment. When a resource order (TMF652) requests a VLAN, the fulfilment system queries TMF685 to find an available VLAN from the appropriate pool, reserves it, and then allocates it. Without pool management, resource allocation would require manual intervention.

TMF685 Key Operations

GET /resourcePool -- List available resource pools
GET /resourcePool/{id} -- Retrieve pool details (capacity, utilisation)
POST /resourcePool/{id}/reserve -- Reserve a resource from the pool (temporary hold)
POST /resourcePool/{id}/allocate -- Allocate a resource (permanent assignment)
POST /resourcePool/{id}/release -- Release a resource back to the pool
GET /resourcePool/{id}/availability -- Check pool capacity and availability

IP Address Pool Allocation

During broadband provisioning: (1) SOM/ROM queries TMF685 GET /resourcePool?type=IPv4&region=East to find the appropriate IP pool. (2) POST /resourcePool/{poolId}/reserve to temporarily hold an IP address (e.g., 10.42.1.15). (3) After successful activation via TMF640, POST /resourcePool/{poolId}/allocate to permanently assign the IP. (4) On service termination, POST /resourcePool/{poolId}/release to return the IP to the pool. The reservation step prevents race conditions when multiple orders are being processed simultaneously.

Intermediate

Reserve vs Allocate Pattern

TMF685 separates reservation (temporary hold) from allocation (permanent assignment). This two-phase pattern prevents resource conflicts during parallel order processing.

Reservations have a configurable TTL (time-to-live). If the order fails or times out, the reservation expires automatically and the resource returns to the available pool. This eliminates "zombie allocations" where resources are held by failed orders. The pattern is especially important for scarce resources like public IPv4 addresses or premium MSISDNs.

Inventory Query Patterns

Inventory APIs support rich query capabilities that are essential for customer service, assurance, and planning use cases. The standard TMF filtering, pagination, and field selection patterns apply across all three inventory APIs.

Common Query Scenarios

Inventory Query Scenarios

Scenario	API	Example Query
Customer product portfolio	TMF637	GET /product?relatedParty.id=CUST-12345&status=Active
All services at a location	TMF638	GET /service?place.id=LOC-42-OAK&state=Active
Resources on a specific device	TMF639	GET /resource?resourceRelationship.resource.id=OLT-EAST-07
Services using a specific resource	TMF638	GET /service?supportingResource.id=VLAN-1042
Products by specification type	TMF637	GET /product?productSpecification.id=SPEC-BROADBAND&status=Active
Resource utilisation by type	TMF639	GET /resource?resourceSpecification.id=SPEC-VLAN&resourceStatus=Available

Cross-Inventory Traversal

One of the most powerful capabilities is cross-inventory traversal -- following the chain from product to service to resource (or vice versa) to answer complex questions.

Impact Analysis: Resource Failure to Customer Notification

Identify Failed Resource

TMF639 -- Resource Inventory

Resource monitoring detects OLT-EAST-07 port GE0/0/1 is down. Query TMF639 to get resource details.

Find Affected Services

TMF638 -- Service Inventory

Query TMF638: GET /service?supportingResource.id=OLT-EAST-07-PORT-1&state=Active to find all CFS/RFS instances using that port.

Identify Affected Products

TMF637 -- Product Inventory

For each affected service, traverse the product link to find the customer product instances in TMF637.

Notify Affected Customers

CRM / Notification System

Use the relatedParty references on each product instance to identify and notify affected customers.

Inventory and Catalog: The Instance/Specification Link

Every inventory instance maintains a reference to its specification in the corresponding catalog. This link is fundamental: it allows systems to determine the type, constraints, and relationships of any instance by looking up its specification.

Inventory to Catalog Mapping

Inventory API	Instance Resource	Catalog API	Specification Reference
TMF637	Product	TMF620	product.productSpecification -> ProductSpecification
TMF638	Service	TMF633	service.serviceSpecification -> ServiceSpecification
TMF639	Resource	TMF634	resource.resourceSpecification -> ResourceSpecification

Think of it like a car and its blueprint. The blueprint (specification) defines the model: engine type, colour options, features. Your actual car (instance) is one occurrence of that blueprint with specific choices: red colour, V6 engine, sunroof. You can always look at the blueprint to understand what your car is capable of.

When a system needs to understand an inventory instance, it follows the specification reference back to the catalog. For example:

Billing reads a Product instance from TMF637, then looks up the ProductSpecification from TMF620 to determine applicable pricing rules
SOM reads a Service instance from TMF638, then looks up the ServiceSpecification from TMF633 to understand decomposition rules for a modify order
Assurance reads a Resource instance from TMF639, then looks up the ResourceSpecification from TMF634 to understand supported monitoring parameters

A critical challenge is catalog version management. When a specification is updated (e.g., new characteristics added), existing inventory instances still reference the old version. Strategies include:

Versioned specifications -- each spec has a version; instances reference a specific version
Backward-compatible changes -- new optional characteristics do not break existing instances
Migration orders -- when breaking changes are needed, generate modify orders to update existing instances to the new spec version
Grace periods -- old spec versions remain active for a defined period to allow migration

Inventory API Source of Record

Inventory Entities -- Source of Record

Entity	System of Record	System of Engagement	System of Reference	Notes
Product Instances	Product Inventory (TMF637)	CRM / Self-Service Portal	Product Catalog (TMF620)	Customer subscription records
Service Instances (CFS/RFS)	Service Inventory (TMF638)	NOC Dashboard / SOM	Service Catalog (TMF633)	Active service configurations
Resource Instances	Resource Inventory (TMF639)	NMS / Element Managers	Resource Catalog (TMF634)	Deployed equipment and allocations
Resource Pools	Resource Pool Manager (TMF685)	ROM / Provisioning	—	Allocatable resource collections

Inventory Data Quality Challenges

Inventory data quality is one of the most persistent challenges in telco operations. When inventory data diverges from reality, every system that depends on it is compromised.

Common Inventory Data Quality Issues

Typical problems include: (1) Ghost resources -- inventory shows resources that no longer exist on the network. (2) Unregistered resources -- real equipment or configurations not reflected in inventory. (3) State drift -- inventory shows "Active" but the actual service is down. (4) Characteristic drift -- inventory shows 100Mbps but the actual configured speed is 200Mbps. (5) Orphaned instances -- services or products with no valid customer reference.

Advanced

Inventory Reconciliation

Reconciliation is the process of comparing inventory data against the actual state of the network and resolving discrepancies. It is essential for maintaining trustworthy inventory.

Reconciliation approaches include: (1) Discovery-based -- periodically scan the network and compare discovered elements against TMF639. (2) Event-driven -- listen to network element events and update inventory in real-time. (3) Order-based -- use completed orders as the trigger to verify that inventory matches expected state. (4) Audit-based -- scheduled full audits comparing all inventory records against network state. The choice depends on network scale, change frequency, and acceptable drift tolerance.

Section 5.4 Key Takeaways

TMF637 (Product Inventory) tracks what customers have; TMF638 (Service Inventory) tracks what services are running; TMF639 (Resource Inventory) tracks what resources are allocated
Every inventory instance references its specification in the corresponding catalog API
TMF685 (Resource Pool Management) handles reserve/allocate/release for pooled resources
Cross-inventory traversal enables impact analysis: resource failure -> affected services -> affected customers
Inventory data quality is critical -- drift between inventory and reality undermines all dependent systems
The reserve-then-allocate pattern (TMF685) prevents resource conflicts during parallel order processing
Inventory APIs support rich query patterns for customer service, assurance, and capacity planning
Regular inventory reconciliation against the actual network state is essential for data trustworthiness