TMF635 Usage Management API

The TMF635 usage management API supported by MATRIXX provides a standardized mechanism for creating, updating, retrieving, importing, and exporting a collection of usages.

A usage is an occurrence of employing a product, service, or resource for its intended purpose, which is of interest to the business and can have charges applied to it.

The TMF Gateway supports the following TMF usage management API REST operations:
  • POST Create Usage — Create a usage event.
  • GET Get Usage Event List from Subscription — Query usage events associated with a subscription. The result is an array of event objects.
  • GET Get Usage by ID — Query a usage event by ID. The result is one usage event.
  • GET Get Usage customfilter querySize — Filter usage events by size.
  • GET Get Usage customfilter eventTime — Filter usage events by time; for example, you can query for two usage events at the same start time.

The operations are performed on custom extensions to the MtxUserExtension MATRIXX Data Container (MDC).

Note: The TMF635 usage management API provides usage events for purchase events only.
Before you can deploy TMF635 with MATRIXX, you must extend the following:
  • MtxDiamRoMsg and MtxUsageEvent to include UsageSpecificationId and UsageRefId.
  • TMFUsageSpecificationUser to include all fields in TMF UsageSpecification.

For more information about extending TMFUsageSpecification User, see the discussion about TMF Usage Management Custom MDCs.

You must also configure a pricing configuration and use eventField mapping to map the fields in the extended MtxDiamRoMsg to the extended MtxUsageEvent.

For example, map the following:
<MtxEventFieldMap>
   <SourceFieldContainer>CustDiamRoMsg</SourceFieldContainer>
    <SourceFieldName>usageUid</SourceFieldName>
    <EventFieldContainer>CustUsageEvent</EventFieldContainer>
    <EventFieldName>usageUid</EventFieldName>
    <IsAggregationGroupField>false</IsAggregationGroupField>
</MtxEventFieldMap>
<MtxEventFieldMap>
    <SourceFieldContainer>CustomDiamRo</SourceFieldContainer>
    <SourceFieldName>usageUid</SourceFieldName>
    <EventFieldContainer>CustUsageEvent</EventFieldContainer>
    <EventFieldName>usageUid</EventFieldName>
    <IsAggregationGroupField>false</IsAggregationGroupField>
</MtxEventFieldMap>
<MtxEventFieldMap>
    <SourceFieldContainer>CustDiamRoMsg</SourceFieldContainer>
    <SourceFieldName>usageSpecificationId</SourceFieldName>
    <EventFieldContainer>CustUsageEvent</EventFieldContainer>
    <EventFieldName>usageSpecificationId</EventFieldName>
    <IsAggregationGroupField>false</IsAggregationGroupField>
</MtxEventFieldMap>
<MtxEventFieldMap>
    <SourceFieldContainer>CustomDiamRo</SourceFieldContainer>
    <SourceFieldName>usageSpecificationId</SourceFieldName>
    <EventFieldContainer>CustUsageEvent</EventFieldContainer>
    <EventFieldName>usageSpecificationId</EventFieldName>
    <IsAggregationGroupField>false</IsAggregationGroupField>
</MtxEventFieldMap>

For more information, see the discussion about event and failed event field mapping properties in My MATRIXX Help.

After you deploy TMF635 with MATRIXX:
  • To use the usage APIs, you must have a subscription with an associated device to generate usage against.
  • Your pricing configuration must have catalog items with offers that have assets (like voice, SMS, and data) granted, and the subscription you create must include some of those catalog items purchased so that the usage can be injected in the appropriate balances.
  • To generate usage using the POST API, there must be a UsageSpecificationId associated.

For a detailed specification of the TMF Usage Management API, see the TM Forum Specification, Party Management API REST Specification, TMF635 release 19.0.0.