Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Hide If
special@authenticated
Note
titleTo access this API specification you wil need to be logged in

To login with your TM Forum account please click on the Login button below

Button Hyperlink
titleLogin
typeprimary
urlhttps://projects.tmforum.org/wiki/login.action?os_destination=%2Fdisplay%2FAPI%2FOpen%2BAPI%2BTable

Don't have an account? You can register by clicking here:

Button Hyperlink
titleRegister
typeprimary
urlhttps://www.tmforum.org/user-registration/
targettrue

Show If
special@authenticated

Managed Entity and Task Resource Models

Status attribute:
The status attribute is used by a state machine through the different lifecycle stages for the usage records. Valid status values are:|

Status code

Description

 

received

Newly injected into the target system

 

rejected

Rejected for validation error or similar reasons

 

recycled

Resubmitted after error correction

 

guided

Identified with customer and product references

 

rated

Rated

From this status on, the ratedProductUsage collection will have a value

rerate

Marked for re-rating

 

billed

Billed for customer invoice

 


Image Modified
Figure 1: State machine diagram for status attribute on usage

Usage Resource

Usage: 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. It is comprised of characteristics, which represent attributes of usage.
Below is a representation of the Usage resource in JSON format (cloud usage).

{
            "id": "15",
            "href": " http://serverlocation:port/usageManagement/usage/15",
            "date": "2013-04-19T16:42:23-04:00",
            "type": "CloudCpuUsage",
            "description": "Description for individual usage content",
            "status": "rated",
            "usageSpecification": {
                        "id": "234",
                        "href": "http://serverlocation:port/usageManagement/usageSpecification/234",
                        "name": "Cloud CPU usage specification"
            },
            "usageCharacteristic": [
                        {
                                    "name": "poolNumber",
                                    "value": "1"
                        }, {
                                    "name": "characteristicType",
                                    "value": "Reserved"
                        }, {
                                    "name": "value",
                                    "value": "2"
                        }, {
                                    "name": "unit",
                                    "value": "GHZ"
                        }
            ],
            "relatedParty": [{
                        "role": "customer",
                        "id": "1",
                        "href": "http://serverlocation:port/partyManagement/organization/1"
            }],
            "ratedProductUsage": [
                        {
                                    "ratingDate": "2013-04-19T16:42:23-04:00",
                                    "usageRatingTag": "Usage",
                                    "isBilled": "False",
                                    "ratingAmountType": "Total",
                                    "taxIncludedRatingAmount": "12.00",
                                    "taxExcludedRatingAmount": "10.00",
                                    "taxRate": "20",
                                    "isTaxExempt": "false",
                                    "offerTariffType": "Normal",
                                    "bucketValueConvertedInAmount": "",
                                    "currencyCode": "EUR",
                                    "productRef": "http://serverlocation:port/catalogManagement/productSpecification/345"
                        }
            ]
}


Below is a representation of the Usage resource in JSON format (voice usage).

{
            "id": "1234",
            "href": " http://serverlocation:port/usageManagement/usage/1234",
            "date": "2013-04-19T16:42:23-04:00",
            "type": "VOICE",
            "description": "Description for individual usage content",
            "status": "rated",
            "usageSpecification": {
                        "id": "22",
                        "href": "http://serverlocation:port/usageManagement/usageSpecification/22",
                        "name": "Voice usage specification"
            },
            "usageCharacteristic": [
                        {
                                    "name": "originatingCountryCode",
                                    "value": "43"
                        }, {
                                    "name": "originatingNumber",
                                    "value": "676123456789"
                        }, {
                                    "name": "destinationCountryCode",
                                    "value": "49"
                        }, {
                                    "name": "destinationNumber",
                                    "value": "170123456789"
                        }, {
                                    "name": "duration",
                                    "value": "20"
                        }, {
                                    "name": "unit",
                                    "value": "SEC"
                        }, {
                                    "name": "startDateTime",
                                    "value": "2013-04-19T16:42:23-04:00"
                        }, {
                                    "name": "endDateTime",
                                    "value": "2013-04-19T16:42:23-04:00"
                        }
            ],
            "relatedParty": [
                        {
                                    "role": "serviceProvider",
                                    "id": "1",
                                    "href": "http://serverlocation:port/partyManagement/organization/1"
                        }, {
                                    "role": "customer",
                                    "id": "45",
                                    "ref": "http://serverlocation:port/partyManagement/individual/45"
                        }
            ],
            "ratedProductUsage ": [
                        {
                                    "ratingDate": "2013-04-19T16:42:23-04:00",
                                    "usageRatingTag": "Usage",
                                    "ratingAmountType": "Total",
                                    "taxIncludedRatingAmount": "12.00",
                                    "taxExcludedRatingAmount": "10.00",
                                    "taxRate": "20",
                                    "isTaxExempt": "false",
                                    "offerTariffType": "Normal",
                                    "bucketValueConvertedInAmount": "",
                                    "currencyCode": "EUR"
                        }
            ]
}

Usage SPECIFICATION Resource

UsageSpecification: A detailed description of a usage event that are of interest to the business and can have charges applied to it. It is comprised of characteristics, which define all attributes known for a particular type of usage.
Below is a representation of the UsageSpecification resource in JSON format for cloud (CPU rated).

{
            "id": "234",
            "href": "http://serverlocation:port/usageManagement/usageSpecification/234",
            "name": "cloudCpuSpec",
            "description": "Spec for cloud CPU usage",
            "validFor": {
                        "startDateTime": "2013-04-19T16:42:23-04:00",
                        "endDateTime": "2099-06-19T00:00:00-04:00"
            },
            "usageSpecCharacteristic": [
                        {
                                    "name": "poolNumber",
                                    "description": "the number of the pool",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "number",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "0",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "characteristicType",
                                    "description": "sub-type of the characteristic",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "Reserved",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }, {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "Reserved Gold",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }, {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "Reserved Silver",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }, {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "Reserved Bronze",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }, {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "Burst",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "value",
                                    "description": "value of the usage specified by the unit",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "number",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "0",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "unit",
                                    "description": "unit of measure",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "GHz",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }, {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "Number of vCPU",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }
            ]
}



JSON representation of the usage specification for voice:

{
            "id": "22",
            "href": "http://serverlocation:port/usageManagement/usageSpecification/22",
            "name": "VoiceSpec",
            "description": "Spec for voice calls usage",
            "validFor": {
                        "startDateTime": "2013-04-19T16:42:23-04:00",
                        "endDateTime": "2099-06-19T00:00:00-04:00"
            },
            "usageSpecCharacteristic": [
                        {
                                    "name": "originatingCountryCode",
                                    "description": "country code of the caller",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "number",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "originatingNumber",
                                    "description": "phone number of the caller",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "destinationCountryCode",
                                    "description": "country code of the called party",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "number",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "destinationNumber",
                                    "description": "phone number of the called party",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "string",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "duration",
                                    "description": "duration of the call",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "number",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "0",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "unit",
                                    "description": "unit of the duration",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "number",
                                                            "default": "false",
                                                            "value": "SEC",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "startDateTime",
                                    "description": "startdate and starttime of the call",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "dateTime",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }, {
                                    "name": "endDateTime",
                                    "description": "enddate and endtime of the call",
                                    "configurable": "true",
                                    "usageSpecCharacteristicValue": [
                                                {
                                                            "valueType": "dateTime",
                                                            "default": "false",
                                                            "value": "",
                                                            "valueFrom": "",
                                                            "valueTo": ""
                                                }
                                    ]
                        }
            ]
}


Field Descriptions :
RatedProductUsage: An occurrence of employing a product for its intended purpose with all rating details.

Field

Description

bucketValueConvertedInAmount

Monetary value of bucket

currencyCode

A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro)

isBilled

Boolean indicating if usage have been billed or not

isTaxExempt

Indicates if the rated amount is exempt of tax

offerTariffType

Type of tariff applied

productRef

Reference of product specification

ratingAmountType

Type of amount

ratingDate

Date of usage rating

taxExcludedRatingAmount

All taxes excluded rated amount

taxIncludedRatingAmount

All taxes included rated amount

taxRate

Tax rate

usageRatingTag

Tag value : 'usage' : the usage is always rated outside a usage bundle
'included usage' : the usage is rated inside a usage bundle
'non included usage' : the usage bundle is exhausted. The usage is rated outside the usage bundle


RelatedParty: Defines party or partyRole linked to a specific entity.

Field

Description

href

Reference of the relatedParty, could be a party reference or a partyRole reference

Id

Unique identifier of the related party

name

Name of the related party

role

Role of the related party

validFor

The period for which the related party is linked to the entity


Usage: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. It is comprised of characteristics, which represent attributes of usage.

Field

Description

date

Date of usage

description

Description of usage

href

Reference of usage

id

Usage unique identifier

status

Status of usage

type

Type of usage


UsageCharacteristic: Provides the value of a given characteristic.

Field

Description

name

The name of the usage characteristic.

value

A discrete value that the characteristic can take on.


UsageSpecification: A detailed description of a usage event that are of interest to the business and can have charges applied to it. It is comprised of characteristics, which define all attributes known for a particular type of usage.

Field

Description

description

A narrative that explains in detail what the usage specification is

href

Reference of usage specification

id

Usage specification unique identifier

name

The name of the usage specification.

validFor

The period for which the usage specification is valid


UsageSpecCharacteristic: A detailed description of an attribute that defines a particular type of usage, described by its name, category, type, presence and a set of allowed values

Field

Description

configurable

Boolean indicating if usageSpecCharacteristic is configurable or not

description

A narrative that explains in detail what the usage specification characteristic is

name

The name of the usage specification characteristic


UsageSpecCharacteristicValue: A value that can be assigned to a UsageSpecCharacteristic.

Field

Description

default

Indicates if the value is the default value for a characteristic

value

A narrative that explains in detail what the usage specification characteristic is

valueType

A kind of value that the characteristic can take on, such as numeric, text, and so forth.

valueFrom

The low range value that a characteristic can take on

valueTo

The upper range value that a characteristic can take on.


UML model:
Image Modified
Figure 2 Usage resource model
Image Modified
Figure 3 UsageSpecification resource model

Export Job Resource

An ExportJob resource represents a TASK used to export resources to a File
The ExportJob resource supports the following properties:

Attribute name

Description

query

Used to scope the exported data (identical to GET filter construct using target ID as base)
"query": "type=usage &version=2.0"

path

URL of the root resource acting as the source for streaming content to the file specified by the ExportJob
../partyManagement/individual

content-type

The format of the exported data .By default "application/json"

status

notstarted, running, succeeded, failed

url

URL of the File containing the data to be exported
a file URL, which is of the form

file://host/path


where host is the fully qualified domain name of the system on which the path is accessible, and path is a hierarchical directory path of the form directory/directory/.../name

completionDate

Date at which the Job was completed.

creationDate

Date at which the Job was created.

errorLog

Reason for Failure


JSON representation of an ExportJob

{
        "id": "54",
        "href": "http:/api/usageManagement/exportJob/54",
        "status": "running",
        "path": "usageManagement/",
        "content-type": "application/json",
        "errorLog": "",
        "creationDate": "2013-04-19T16:42:23-04:00",
        "completionDate": "2013-04-21T16:42:23-04:00",
        "url": "ftp://ftp.myUsage.com/usage/54"
    }   


UML Model:
Image Modified

Import Job Resource

An ImportJob resource represent a TASK used to import resources from a File
The ImportJob resource supports the following properties:

Attribute name

Description

content-type

The format of the imported data. By default "application/json"

path

URL of the root resource where the content of the file specified by the ImportJob must be applied
../partyManagement/individual

status

notstarted, running, succeeded, failed

url

URL of the File containing the data to be imported
a file URL, which is of the form

file://host/path


where host is the fully qualified domain name of the system on which the path is accessible, and path is a hierarchical directory path of the form directory/directory/.../name

completionDate

Date at which the Job was completed.

creationDate

Date at which the Job was created.

errorLog

Reason for Failure if status is failed


JSON representation of an ImportJob

{
        "id": "54",
        "href": "http:/api/ usageManagement/importJob/54",
        "status": "completed",
        "path": "usageManagement/",
        "content-type": "application/json",
        "errorLog": "",
        "creationDate": "2013-04-19T16:42:23-04:00",
        "completionDate": "2013-04-21T16:42:23-04:00",
        "url": "ftp://ftp.myUsage.com/usage/54"
    }   


UML Model:
Image Modified

Notification Resource Models


2 notification event types are defined :

  1. ImportJobCompletionNotification
  2. ExportJobCompletionNotification


UML Model:
Image Modified
Event: ExportJobCompletionNotification

{
    "eventType": "ExportJobCompletionNotification",
    "eventTime": "2014-09-27T05:46:25.0Z",
    "eventId": "1154278",
    "event": {"exportJob": {
        "id": "54",
        "href": "http:/api/usageManagement/exportJob/54",
        "status": "succeeded",
        "path": "usageManagement/",
        "content-type": "application/json",
        "errorLog": "",
        "creationDate": "2013-04-19T16:42:23-04:00",
        "completionDate": "2013-04-21T16:42:23-04:00",
        "url": "ftp://ftp.myUsage.com/usageManagement/54.json"
    }}
}




Event: ImportJobCompletionNotification

{
    "eventType": "ImportJobCompletionNotification",
    "eventTime": "2014-09-27T05:46:25.0Z",
    "eventId": "1154278",
    "event": {

 

"importJob": {
        "id": "54",
        "href": "http:/api/usageManagement/importJob/54",
        "status": "succeeded",
        "path": "usageManagement/",
        "content-type": "application/json",
        "errorLog": "",
        "creationDate": "2013-04-19T16:42:23-04:00",
        "completionDate": "2013-04-21T16:42:23-04:00",
        "url": "ftp://ftp.myUsage.com/usageManagement/54.json"
    }}
}

 


© TM Forum 2015. All Rights Reserved.