Frameworx Specification

Resource Ordering
Management
API REST Specification

TMF652
Release 16.5.1
April 2017

Latest Update: Frameworx Release 16.5 TM Forum Approved

Version 1.0.1 IPR Mode: RAND

TM Forum 2017. All Rights Reserved.

Resource Ordering Management API REST Specification

NOTICE

Copyright © TM Forum 2017. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that
comment on or otherwise explain it or assist in its implementation may be prepared, copied, published,
and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice
and this section are included on all such copies and derivative works. However, this document itself may
not be modified in any way, including by removing the copyright notice or references to TM FORUM,
except as needed for the purpose of developing any document or deliverable produced by a TM FORUM
Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM
FORUM IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its
successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.

TM FORUM invites any TM FORUM Member or any other party that believes it has patent claims that
would necessarily be infringed by implementations of this TM Forum Standards Final Deliverable, to notify
the TM FORUM Team Administrator and provide an indication of its willingness to grant patent licenses to
such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project
Team that produced this deliverable.

The TM FORUM invites any party to contact the TM FORUM Team Administrator if it is aware of a claim
of ownership of any patent claims that would necessarily be infringed by implementations of this TM
FORUM Standards Final Deliverable by a patent holder that is not willing to provide a license to such
patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team
that produced this TM FORUM Standards Final Deliverable. TM FORUM may include such claims on its
website, but disclaims any obligation to do so.

TM FORUM takes no position regarding the validity or scope of any intellectual property or other rights
that might be claimed to pertain to the implementation or use of the technology described in this TM
FORUM Standards Final Deliverable or the extent to which any license under such rights might or might
not be available; neither does it represent that it has made any effort to identify any such rights.
Information on TM FORUM's procedures with respect to rights in any document or deliverable produced
by a TM FORUM Collaboration Project Team can be found on the TM FORUM website. Copies of claims
of rights made available for publication and any assurances of licenses to be made available, or the result
of an attempt made to obtain a general license or permission for the use of such proprietary rights by
implementers or users of this TM FORUM Standards Final Deliverable, can be obtained from the TM
FORUM Team Administrator. TM FORUM makes no representation that any information or list of
intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential
Claims.

Direct inquiries to the TM Forum office:

© TM Forum 20167 All Rights Reserved. Page 2

Resource Ordering Management API REST Specification

240 Headquarters Plaza,

East Tower – 10th Floor,
Morristown, NJ 07960 USA
Tel No. +1 973 944 5100
Fax No. +1 973 944 5110
TM Forum Web Page: www.tmforum.org

© TM Forum 20167 All Rights Reserved. Page 3

Resource Ordering Management API REST Specification

TABLE OF CONTENTS
NOTICE ........................................................................................................................................ 2

Table of Contents.......................................................................................................................... 4

List of Tables ................................................................................................................................ 5

Introduction ................................................................................................................................... 6

SAMPLE USE CASES .................................................................................................................. 7

RESOURCE MODEL .................................................................................................................... 8

Managed Entity and Task Resource Models .......................................................................................... 8

Resource Order resource .................................................................................................................... 8

Notification Resource Models ............................................................................................................... 16

Resource Order Creation Notification ................................................................................................ 17

Resource Order Attribute Value Change Notification ......................................................................... 17

Resource Order State Change Notification ........................................................................................ 18

Resource Order Remove Notification ................................................................................................ 18

Resource Order Information Required Notification............................................................................. 19

API OPERATIONS...................................................................................................................... 20

Operations on Resource Order ............................................................................................................. 20

List resource orders ........................................................................................................................... 21

Retrieve resource order ..................................................................................................................... 21

Create resource order ....................................................................................................................... 24

Patch resource order ......................................................................................................................... 27

Delete resource order ........................................................................................................................ 29

API NOTIFICATIONS.................................................................................................................. 31

Register listener ................................................................................................................................... 31

Unregister listener ................................................................................................................................ 31

Publish Event to listener ....................................................................................................................... 32

Acknowledgements ..................................................................................................................... 34

Release History .................................................................................................................................... 34

© TM Forum 20167 All Rights Reserved. Page 4

Resource Ordering Management API REST Specification

LIST OF TABLES

N/A

© TM Forum 20167 All Rights Reserved. Page 5

Resource Ordering Management API REST Specification

INTRODUCTION

The following document is the specification of the REST API for Resource Order Management. It includes
the model definition as well as all available operations. Possible actions are creating, updating and
retrieving Resource Orders (including filtering).

A Resource Order API provides a standard mechanism for placing a Resource Order with all necessary
order parameters. A Resource Order is created based on a resource candidate that is defined in the
resource catalog. The Resource candidate is an entity that makes a Resource Specification available to a
resource catalog.

Resources are physical or non-physical components (or some combination of these) within an enterprise's
infrastructure or inventory. They are typically consumed or used by Services (for example a physical port
assigned to a service) or contribute to the realization of a Product (for example, a SIM card). They can be
drawn from the Application, Computing and Network domains, and include, for example, Network
Elements, software, IT systems, content and information, and technology components.

A Resource Specification is an abstract base class for representing a generic means for implementing a
particular type of Resource. In essence, a Resource Specification defines the common attributes and
relationships of a set of related Resources, while Resource defines a specific instance that is based on a
particular Resource Specification.

Resource Order API manages resource order resource:

- A Resource Order is a type of order which can be used to place an order between a service
provider and a partner and vice versa
- Main order items attributes are the orders resource candidates and resource characteristics with
the related action to be performed (e.g: add or delete resources), state.

Resource Order API performs the following operations on the Resource Order:

- Retrieval of a Resource Order or a collection of Resource Orders depending on filter criteria

- Partial update of a ResourceOrder
- Creation of a Resource order
- Deletion of a resource order (for admin purposes)
- Notifications of events on resource order
o Order creation
o Order removal
o Order state change
o Order value change
o Order information required

The following Assumptions were considered in the development of this document :

- The Order Management system has access to the catalog system

© TM Forum 20167 All Rights Reserved. Page 6

Resource Ordering Management API REST Specification

SAMPLE USE CASES

Reader will find examples of use cases in “Open Digital Business Scenarios and Use Cases” document.

© TM Forum 20167 All Rights Reserved. Page 7

Resource Ordering Management API REST Specification

RESOURCE MODEL

Managed Entity and Task Resource Models

RESOURCE ORDER RESOURCE

A Resource Order is a request to provision a set of Resources (logical and physical) triggered by the
request to provision a Service through a Service Order.

Resource model

class ResourceOrder resource

AppointmentRef
ResourceSpecificationRef
id: String
id: String href: String
resourceSpecification
href: String
name: String 1
appointment 0..1

Note
note ResourceOrder 0..1 0..1
date: DateTime
author: String
0..* 0..1 id: String ResourceOrderItem
text: String
href: String
externalId: String orderItem id: String
state: String action: String
0..1 0..*
name: String state: String
description: String quantity: int 0..1
priority: int
OrderRelationship type: String 0..1
orderRelationship category: String
type: String orderDate: DateTime orderItemRelationship 0..*
id: String 0..* 0..1 requestedCompletionDate: Date
href: String requestedStartDate: Date ResourceOrderItemRelationship
resource
completionDate: DateTime 1 relationshipType: String
startDate: Date id: String
A
expectedCompletionDate: Date Resource

0..1 id: String

0..1 href: String
relatedParty 0..* relatedParty name: String
description: String
RelatedPartyRef 0..*
type: String
0..1
0..1 state: String
id: String
href: String 0..1
role: String
name: String place 0..*
characteristic 0..*
Place resourceRelationship 0..*

ResourceCharacteristic
href: String ResourceRelationship
role: String name: String
type: String
value: String
0..1

resource 1

ResourceRef

id: String
href: String

Lifecycle

The order item states are the same as the order ones. Note that the order and order item states are tightly
linked and need to be consistent, for example :

© TM Forum 20167 All Rights Reserved. Page 8

Resource Ordering Management API REST Specification

Order, state : InProgress

Order item 1, state : InProgress (Valid)
Order item 2, state : Pending (Valid)
Order item 3, state : Held (Valid)
Order item 4, state : Completed (Valid until there is another order item which is NOT completed)
Order item 5, state : Cancelled (Not valid : if an order item is cancelled, maybe the whole order should
be cancelled too) The state machine specifying the typical state change transitions is provided below.

stm ResourceOrder Lifecycle

Initial

Rej ected
Acknow ledged

yes no
Final

accept
resource
order Pending
start order treatment

extra information received

ordering process needs extra information to continue

extra information cannot be supplied
In progress

Cancelled
issue is resolved

Held Final

ordering processes is blocked due to an issue issue cannot be solved

order completly failed
order completly treated order partially completed/failed

Failed Partial
Completed

Final

Acknowledged The Acknowledged state is where an order has been received and has passed
message and basic business validations.

In Progress The In Progress state is when resource delivery has started.

Cancelled The Cancelled state is where an In-Flight Order has been successfully cancelled.

© TM Forum 20167 All Rights Reserved. Page 9

Resource Ordering Management API REST Specification

Completed The Completed state is where an order has complete provision and the resource is
now active.

Rejected The Rejected state is where:

- Invalid information is provided through the order request

- The order request fails to meet business rules for ordering.

Pending The Pending state is used when an order is currently in a waiting stage for an
action/activity to be completed before the order can progress further, pending order
amend or cancel assessment. In situations where Access Seeker action is required,
an “information required” notification will be issued on transition into this state.

A pending stage can lead into auto cancellation of an order, if no action is taken within
the defined timeframes to be described under the Agreement.

Held The Held state is used when an order cannot be progressed due to an issue. SP has
temporarily delayed completing an order to resolve an infrastructure shortfall to
facilitate supply of order. Upon resolution of the issue, the order will continue to
progress.

Failed All Order items have failed which results in the entire Order has Failed.

Partial Some Order items have failed and some have succeeded so the entire Order is in a
Partial state. This provides support for partial Failure of an Order

Consistency between Resource Order state and Resource Order Item state table:

If resource order state has state… the resource order items state should be…
Rejected All ‘Rejected’
Acknowledged All ‘Acknowledged’
note: once delivery begins for at least an item the RO
state shifts to ‘In Progress’
in Progress At least one RO item has ‘In Progress’ state
All items should be ‘Acknowledged’
Pending All ‘Pending state
Held All ‘Held’ state
Cancelled All ‘Cancelled’
Partial All Order item are either ‘Failed’ or ‘Completed’
At least one item has ‘Failed’ state
At least one item has ‘Completed’ state
Failed All ‘Failed’
Completed All ‘Completed’

Field descriptions

ResourceOrder fields

© TM Forum 20167 All Rights Reserved. Page 10

Resource Ordering Management API REST Specification

category A string. Used to categorize the order from a business perspective that can
be useful for the Resource Order Management system.

completionDate A date time (DateTime). Date when the order was completed.

externalId A string. ID given by the consumer and only understandable by him (to
facilitate his searches afterwards).

description A string. free-text description of the Resource Order.

href A string. Hyperlink to access the order.

id A string. Identifier of an instance of the Resource Order. Required to be

unique within the resource type. Used in URIs as the identifier for specific
instances of a type.

name A string. A string used to give a name to the Resource Order.

orderDate A date time (DateTime). Date when the order was created.

priority An int (int). A way that can be used by consumers to prioritize orders in
Resource Order Management system (from 0 to 4 : 0 is the highest priority,
and 4 the lowest).

requestedCompletionDate A date (Date). Requested delivery date from the requestor perspective.

requestedStartDate A date (Date). Order start date wished by the requestor.

expectedCompletionDate A date (Date). Expected delivery date amended by the provider

startDate A date (Date). Order start date wished by the requestor

state A string. The life cycle state of the resource order.

type A string. Name of the Resource Order type.

orderRelationship A list of resource order relationships (OrderRelationship [*]).

relatedParty A list of related party references (RelatedPartyRef [*]). A related party

defines party or party role linked to a specific entity.

note A list of notes (Note [*]). Extra information about the Resource Order

Note sub-resource

Extra information about the resource order.

author A string. Author of the note.

date A date time (DateTime). Date of the note.

text A string. Text of the note.

OrderRelationship sub-resource

© TM Forum 20167 All Rights Reserved. Page 11

Resource Ordering Management API REST Specification

Linked order to the one containing this attribute.

href A string. A hyperlink to the related order.

id A string. The id of the related order.

type A string. The type of related order, can be:

 “dependency” if the order needs to be “not started” until another order
item is complete (a resource order in this case)
 “cross-ref” to keep track of the source order (a serviceOrder)

ResourceOrderItem

An identified part of the order. A resource order is decomposed into one or more order items.

id A string. Identifier of the line item (generally it is a sequence number

01, 02, 03, ...).

action A string. The action to be carried out on the Resource. Can be:
 add
 modify
 delete
 noChange

state A string. State of the order item : described in the state machine
diagram.

appointment An appointment references (AppointmentRef). Used to precise that an

appointment was set up with a related party for this order item.

resourceSpecification A service specification (ResourceSpecificationRef). The resource

specification (default values, etc. are fetched from the catalogue).

resourceOrderItemRelationship A list of order items relationships (ResourceOrderItemRelationship[*]).

Linked order items to the one containing this attribute.

resource A resource references (ResourceRef). The resource to be acted on by

the order item.
ResourceOrderItemRelationship

Linked order item to the one containing this attribute.

relationshipType A string. The type of related order item, can be:

o “dependency” if the order item needs to be “not started” until
another order item is complete

© TM Forum 20167 All Rights Reserved. Page 12

Resource Ordering Management API REST Specification

id A string, the id of the resource order item.

Appointment

Used to precise that an appointment was set-up with a related party for this order item.

id A string. The id of the appointment.

href A string. An hyperlink to the appointment

Place

Used to define a place useful for the resource (for example a delivery geographical place).

href A string. Reference of a place (for instance in google map).

role A string. The role of the place (e.g. delivery address, install site etc).

Resource

Resource attributes description (these are as per the Resource ODE model as used in the
Resource Inventory specification).

id A string. Identifier of a resource instance. Required to be unique. Used in

URIs as the identifier of the resource (for modify or delete use cases).

href A string. Reference to the owned resource (useful for delete or modify
command).

description A string. A description of the resource (what it provides).

name A string. Name of the resource.

state A string. The lifecycle state of the resource.

place A list of places (Place [*]). Used to define places useful for the resource (for
example a delivery geographical place).

resourceCharacteristic A list of resource characteristics (ResourceCharacteristic[*]).A name/value pair

list used to store instance specific values of attributes. The behavior is
equivalent to a MAP data structure where only one entry for any given value of
"name" can exist.

resourceRelationship A list or resource relationships (ResourceRelationship[*]). Linked Resource to

the one instantiate, it can be :
 “reliesOn” if the resource needs another already owned resource to
rely on (e.g. an option on an already owned mobile access Resource)
 “targets” or “isTargeted” (depending on the way of expressing the link)
for any other kind of links that may be useful

© TM Forum 20167 All Rights Reserved. Page 13

Resource Ordering Management API REST Specification

relatedParty A list of related party references (RelatedPartyRef[*]). Parties linked at the

resource level (it may be a User for example).

RelatedPartyRef relationship

RelatedParty reference. A related party defines party or party role linked to a specific entity.

href A string. Reference of the related party, could be a party reference or a party
role reference.

id A string. Unique identifier of a related party.

name A string. Name of the related party.

role A string. Role of the related party.

Json representation sample

We provide below the json representation of an example of a 'ResourceOrder' resource object

{
"id": "42",
"href": "http://serverlocation:port/resourceOrderingManagement/resourceOrder/42",
"externalId": "MyResourceOrder_42",
"priority": "1",
"description": "A wonderful 42 order for brand new Resources",
"category": "Uncategorized",
"state": "InProgress",
"orderDate": "2013-04-12T16:42:23-04:00",
"requestedStartDate": "2013-04-12T16:42:23-04:00",
"requestedCompletionDate": "2013-04-19T16:42:23-04:00",
"completionDate": "2013-04-19T16:42:23-04:00",
"orderRelationship": [{
"type": "dependency",
"href": "https://host:port/ resourceOrderingManagement /resourceOrder/3304",
"id": "3304"
}, {
"type": "cross-ref",
"href": "https://host:port/ serviceOrderingManagement /serviceOrder/3304",
"id": "3304"
}

],

"note": [{
"text": "A free text detailing the note",
"date": "2013-04-12T16:42:23-04:00",
"author": "name"
}],
"relatedParty": [{
"role": "owner",

© TM Forum 20167 All Rights Reserved. Page 14

Resource Ordering Management API REST Specification

"id": "345221",
"name": "John Doe"
}],
"resourceOrderItem": [{
"id": "1",
"action": "add",
"state": "Acknowledged",
"appointment": {

"href": "http://serverlocation:port/appointment/100"

},
"resourceSpecification": {
"id": "42",
"href": "http: //serverlocation: port/resourceCatalogManagement/resourceSpecification/42"
},

"resource": {
"place": {
"href": "http://map.google.com/.../1234112GDE",
"role": "DeliveryPlace"
},

"resourceCharacteristic": [{
"name": "Colour",
"value": "White"
}, {
"name": "Memory",
"value": "16"
}]
}
}, {
"id": "2",
"action": "modify",
"state": "InProgress",
"resourceSpecification": {
"id": "43",
"href": "http: //serverlocation: port/resourceCatalogManagement/resourceSpecification/43"
},
"resource": {
"id": "456",
"href": "http: //serverlocation: port/resourceInventoryManagement/logicalResource/456",
"resourceCharacteristic": [{
"name": "anotherCharacteristic",
"value": "itsValue"
}],
"relatedParty": [{
"role": "owner",
"id": "5667443",
"name": "Jimmy Doe"
}]
}
}, {
"id": "3",
"action": "add",
"state": "InProgress",

© TM Forum 20167 All Rights Reserved. Page 15

Resource Ordering Management API REST Specification

"resourceSpecification": {
"id": "43",
"href": "http: //serverlocation: port/resourceCatalogManagement/resourceSpecification/51"
},
"resource": {
"resourceRelationship": {
"type": "reliesOn",
"resource": {
"href": "411",
"id": "http: //serverlocation:
port/resourceInventoryManagement/resource/411"
}

}
}
}]
}

Notification Resource Models

5 notifications are defined for this API

Notifications related to ResourceOrder:

- ResourceOrderCreationNotification

- ResourceOrderAttributeValueChangeNotification

- ResourceOrderStateChangeNotification

- ResourceOrderRemoveNotification

- ResourceInformationRequiredNotification

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification resource (depicted by "SpecificNotification" placeholder) is a sub class of a generic
Notification structure containing an id of the event occurence (eventId), an event timestamp (eventTime),
and the name of the notification resource (eventType).
This notification structure owns an event structure ("SpecificEvent" placeholder) linked to the resource
concerned by the notification using the resource name as access field ("resourceName" placeholder).

© TM Forum 20167 All Rights Reserved. Page 16

Resource Ordering Management API REST Specification

RESOURCE ORDER CREATION NOTIFICATION

Notification sent when a new ResourceOrder resource is created.

Json representation sample

We provide below the json representation of an example of a 'ResourceOrderCreationNotification'

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ResourceOrderCreationNotification",
"event": {
"resourceOrder" :
{-- SEE ResourceOrder RESOURCE SAMPLE --}
}
}

RESOURCE ORDER ATTRIBUTE VALUE CHANGE NOTIFICATION

Notification sent when changing an attribute of a ResourceOrder resource.

Json representation sample

© TM Forum 20167 All Rights Reserved. Page 17

Resource Ordering Management API REST Specification

We provide below the json representation of an example of a

'ResourceOrderAttributeValueChangeNotification' notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ResourceOrderAttributeValueChangeNotification",
"event": {
"resourceOrder" :
{-- SEE ResourceOrder RESOURCE SAMPLE --}
}
}

RESOURCE ORDER STATE CHANGE NOTIFICATION

Notification sent when changing the state of a ResourceOrder resource.

Json representation sample

We provide below the json representation of an example of a 'ResourceOrderStateChangeNotification'

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ResourceOrderStateChangeNotification",
"event": {
"resourceOrder" :
{-- SEE ResourceOrder RESOURCE SAMPLE --}
}
}

RESOURCE ORDER REMOVE NOTIFICATION

Notification sent when removing a ResourceOrder resource.

Json representation sample

We provide below the json representation of an example of a 'ResourceOrderRemoveNotification'

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ResourceOrderRemoveNotification",
"event": {
"resourceOrder" :
{-- SEE ResourceOrder RESOURCE SAMPLE --}
}
}

© TM Forum 20167 All Rights Reserved. Page 18

Resource Ordering Management API REST Specification

RESOURCE ORDER INFORMATION REQUIRED NOTIFICATION

Used to notify that some data in the order needs to be filled / is missing.

- “resourcePath” allows to precise if it is a data at order level or at orderItem level (and which one of
them) that is missing
- “fieldPath” details which field is missing. Its structure is quite similar to GET filter criteria :
o “missing=” points at the missing field
o “&<criteria>” can be used to identify a specific element in lists

Simple example: requestedStardDate contact is missing

{
"eventId":"00005",
"eventTime":"2013-04-19T16:42:25-30:00",
"eventType":"orderInformationRequiredNotification",
"resourcePath":"/order/42 ",
"fieldPath":"missing=requestedStartDate",
"resourceOrder":{
"id":" 42",
"href":"http://serverlocation:port/resourceOrderingManagement/resourceOrder/42",
}
}

© TM Forum 20167 All Rights Reserved. Page 19

Resource Ordering Management API REST Specification

API OPERATIONS

Remember the following Uniform Contract:

Operation on Entities Uniform API Operation Description

Query Entities GET Resource GET must be used to

retrieve a representation of
a resource.

Create Entity POST Resource POST must be used to

create a new resource

Partial Update of an Entity PATCH Resource PATCH must be used to

partially update a resource

Complete Update of an PUT Resource PUT must be used to

Entity completely update a
resource identified by its
resource URI

Remove an Entity DELETE Resource DELETE must be used to

remove a resource

Execute an Action on an POST on TASK Resource POST must be used to

Entity execute Task Resources

Other Request Methods POST on TASK Resource GET and POST must not
be used to tunnel other
request methods.

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

Notifications are also described in a subsequent section.

OPERATIONS ON RESOURCE ORDER

© TM Forum 20167 All Rights Reserved. Page 20

Resource Ordering Management API REST Specification

LIST RESOURCE ORDERS

GET /resourceOrder?fields=...&{filtering}
Description

This operation list resource order entities.

Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's an example of a request for retrieving ResourceOrder resources.

Searching resource orders started on January 1st 2015. The result items are shrunk to show only the ids
(fields=id)

Request

GET /resourceOrderingManagement/resourceOrder?fields=id&orderDate="2015-01-01"
Accept: application/json

Response

200

[
{
"id": "986781"
},
{
"id": "986782"
},
{
"id": "986783"
}
]

RETRIEVE RESOURCE ORDER

GET /resourceOrder/{id}?fields=...&{filtering}
Description

This operation retrieves a resource order entity.

Attribute selection is enabled for all first level attributes.

© TM Forum 20167 All Rights Reserved. Page 21

Resource Ordering Management API REST Specification

Filtering on sub-resources may be available depending on the compliance level supported by an

implementation.

Usage Samples

Here's an example of a request for retrieving a ResourceOrder resource.

Request

GET /resourceOrderingManagement/resourceOrder/42
Accept: application/json

Response

200

{
"id": "42",
"href": "http://serverlocation:port/resourceOrderingManagement/resourceOrder/42",
"externalId": "MyResourceOrder_42",
"priority": "1",
"description": "A wonderful 42 order for brand new Resources",
"category": "Uncategorized",
"state": "InProgress",
"orderDate": "2013-04-12T16:42:23-04:00",
"requestedStartDate": "2013-04-12T16:42:23-04:00",
"requestedCompletionDate": "2013-04-19T16:42:23-04:00",
"completionDate": "2013-04-19T16:42:23-04:00",
"orderRelationship": [{
"type": "dependency",
"href": "https://host:port/ resourceOrderingManagement /resourceOrder/3304",
"id": "3304"
}, {
"type": "cross-ref",
"href": "https://host:port/ serviceOrderingManagement /serviceOrder/3304",
"id": "3304"
}

],

"note": [{
"text": "A free text detailing the note",
"date": "2013-04-12T16:42:23-04:00",
"author": "name"
}],
"relatedParty": [{
"role": "owner",
"id": "345221",
"name": "John Doe"
}],

© TM Forum 20167 All Rights Reserved. Page 22

Resource Ordering Management API REST Specification

"resourceOrderItem": [{
"id": "1",
"action": "add",
"state": "Acknowledged",
"appointment": {

"href": "http://serverlocation:port/appointment/100"

},
"resourceSpecification": {
"id": "42",
"href": "http: //serverlocation: port/resourceCatalogManagement/resourceSpecification/42"
},

"resource": {
"place": {
"href": "http://map.google.com/.../1234112GDE",
"role": "DeliveryPlace"
},

"resourceCharacteristic": [{
"name": "Colour",
"value": "White"
}, {
"name": "Memory",
"value": "16"
}]
}
}, {
"id": "2",
"action": "modify",
"state": "InProgress",
"resourceSpecification": {
"id": "43",
"href": "http: //serverlocation: port/resourceCatalogManagement/resourceSpecification/43"
},
"resource": {
"id": "456",
"href": "http: //serverlocation: port/resourceInventoryManagement/logicalResource/456",
"resourceCharacteristic": [{
"name": "anotherCharacteristic",
"value": "itsValue"
}],
"relatedParty": [{
"role": "owner",
"id": "5667443",
"name": "Jimmy Doe"
}]
}
}, {
"id": "3",
"action": "add",
"state": "InProgress",
"resourceSpecification": {
"id": "43",
"href": "http: //serverlocation: port/resourceCatalogManagement/resourceSpecification/51"

© TM Forum 20167 All Rights Reserved. Page 23

Resource Ordering Management API REST Specification

},
"resource": {
"resourceRelationship": {
"type": "reliesOn",
"resource": {
"href": "411",
"id": "http: //serverlocation:
port/resourceInventoryManagement/logicalResource/411"
}

}
}
}]
}

CREATE RESOURCE ORDER

POST /resourceOrder
Description

This operation creates a resource order entity.

Mandatory and Non Mandatory Attributes

The following tables provides the list of mandatory and non mandatory attributes when creating a
ResourceOrder, including any possible rule conditions and applicable default values.

Mandatory Attributes Rule

orderItem

Non Mandatory Attributes Default Value Rule

category Uncategorized
completionDate
externalId
description
name
orderDate
priority 4 (lowest)
requestedCompletionDate
requestedStartDate
startDate
expectedCompletionDate
state Acknowledged
type
orderRelationship
relatedParty
note
orderItem.state Acknowledged
orderItem.ResourceSpecification
orderItem.resource.place

© TM Forum 20167 All Rights Reserved. Page 24

Resource Ordering Management API REST Specification

orderItem.appointment

Additional Rules

The following table provides additional rules indicating mandatory fields in sub-resources or relationships
when creating a ResourceOrder resource.

Context Mandatory Sub-Attributes

note text
appointment id OR href
orderItem id, action, resource
relatedParty role, id OR href OR name
orderItem.resource.place role, id OR href
orderItem.resourceSpecification id OR href
orderItem.resource characteristic (if action==add), id OR href (if action==modify or
action==delete)

The following pre-conditions apply for this operation.

Pre-conditions
PATCH allowed if order not completed

Default Values Summary

When creating the resource, the following table summarizes the default values applicable to optional
attributes of the resource (or sub-resources).

Attributes Default Value

state Acknowledged
priority 4 (lowest)
category Uncategorized
orderItem.state Acknowledged

Usage Samples

Here's an example of a request for creating a ResourceOrder resource composed of 2 order items:

- Line 1: for ordering a new resource that needs a physical place and an appointment to be
delivered;
- Line 2: change of a characteristic value of an already owned Resource and change the user
associated with this Resource

Request

POST /resourceOrderingManagement/resourceOrder
Content-Type: application/json

"note": [{

© TM Forum 20167 All Rights Reserved. Page 25

Resource Ordering Management API REST Specification

"text": "A free text detailing a note for the resource order"
}],
"relatedParty": [{
"role": "owner",
"id": "345221",
"name": "John Doe"
}],
"resourceOderItem": [{
"id": "1",
"action": "add",

"appointment":{

"href":"http://serverlocation:port/appointment/100",

},
"resourceSpecification": {
"href": "http: //serverlocation: port/resourceCatalog/resourceSpecification/42"
},
"resource": {
"place":{
"href":"http://map.google.com/.../1234112GDE",
"role":"DeliveryPlace"
},
"resourceCharacteristic": [{
"name": "Colour",
"value": "White"
}, {
"name": "Memory",
"value": "16"
}]
}
}, {
"id": "2",
"action": "modify",
"resource": {
"href": "http: //serverlocation: port/resourceInventoryManagement/logicalResource/456",
"relatedParty": [{
"role": "owner",
"id": "5667443",
"name": "Jimmy Doe"
}]
}
}, ]
}

Response

201

{
"id": "42",
"href": "http://serverlocation:port/ resourceOrderingManagement /resourceOrder/42",
"priority": "1",

© TM Forum 20167 All Rights Reserved. Page 26

Resource Ordering Management API REST Specification

"state": "Acknowledged",
"orderDate": "2013-04-12T16:42:23-04:00",
"note": [{
"text": "A free text detailing a note for the resource order"
}],
"relatedParty": [{
"role": "owner",
"id": "345221",
"name": "John Doe"
}],
"resourceOderItem": [{
"id": "1",
"action": "add",
"state": "Aknowledged",

"appointment": {

"href": "http://serverlocation:port/appointment/100"

},
"resourceSpecification": {
"href": "http: //serverlocation: port/resourceCatalogManagement/resourceSpecification/42"
},
"resource": {
"place": {
"href": "http://map.google.com/.../1234112GDE",
"role": "DeliveryPlace"
},
"resourceCharacteristic": [{
"name": "Colour",
"value": "White"
}, {
"name": "Memory",
"value": "16"
}]
}
}, {
"id": "2",
"action": "modify",
"state": "Aknowledged",
"resource": {
"href": "http: //serverlocation: port/resourceInventoryManagement/logicalResource/456",
"relatedParty": [{
"role": "owner",
"id": "5667443",
"name": "Jimmy Doe"
}]
}
}]
}

PATCH RESOURCE ORDER

PATCH /resourceOrder/{id}

© TM Forum 20167 All Rights Reserved. Page 27

Resource Ordering Management API REST Specification

Description

This operation allows partial updates of a resource order entity. Support of json/merge
(https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is
optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules
concerning mandatory sub-resource attributes and default value settings in the POST operation applies to
the PATCH operation. Hence these tables are not repeated here.

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on
their usage.

Patchable Attributes Rule

category
description
name
priority
requestedCompletionDate Only when order is in “Acknowledged” state – delivery process
not started
requestedStartDate Only when order is in “Acknowledged” state – delivery process
not started
state To manage the order delivery process : Acknowledged,
InProgress (start process), Held / Pending (suspend process),
Cancelled
Influence the orderItem states
type
orderRelationship
relatedParty Only when order is in “Acknowledged” state – delivery process
not started
note
orderItem.resourceSpecification Only when order is in “Acknowledged” state – delivery process
not started or suspended
orderItem.resource.place Only when order is in “Acknowledged” state – delivery process
not started or suspended
orderItem.resource Only when order is in “Acknowledged” state – delivery process
not started or suspended
orderItem.appointment Only when order is in “Acknowledged” state – delivery process
not started or suspended

Non Patchable Attributes Rule

id
href
externalId
orderDate
completionDate
orderItem.id
orderItem.action

© TM Forum 20167 All Rights Reserved. Page 28

Resource Ordering Management API REST Specification

Additional Rules

The following pre-conditions apply for this operation.

Pre-conditions
PATCH allowed if order not completed

Usage Samples

Here's an example of a request for patching a ResourceOrder resource.

Changing the priority of the order (using json-merge)

Request

PATCH /resourceOrderingManagement/resourceOrder/42
Content-Type: application/merge-patch+json

{
"priority": 1
}

Response

201

{ Similar JSON as in GET response with priority changed }

DELETE RESOURCE ORDER

DELETE /resourceOrder/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a resource order entity.

Usage Samples

Here's an example of a request for deleting a ResourceOrder resource.

Request

© TM Forum 20167 All Rights Reserved. Page 29

Resource Ordering Management API REST Specification

DELETE /resourceOrderingManagement/resourceOrder/42

Response

204

© TM Forum 20167 All Rights Reserved. Page 30

Resource Ordering Management API REST Specification

API NOTIFICATIONS

For every single of operation on the entities use the following templates and provide sample
REST notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the
REST Guidelines reproduced below.

REGISTER LISTENER

POST /hub
Description

Sets the communication endpoint address the service instance must use to deliver information about its
health state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if
it does not support multiple listeners. In this case DELETE /api/hub/{id} must be called before an endpoint
can be created again.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

Usage Samples

Here's an example of a request for registering a listener.

Request

POST /api/hub
Accept: application/json

{"callback": "http://in.listener.com"}

Response

201
Content-Type: application/json
Location: /api/hub/42

{"id":"42","callback":"http://in.listener.com","query":null}

UNREGISTER LISTENER

© TM Forum 20167 All Rights Reserved. Page 31

Resource Ordering Management API REST Specification

DELETE /hub/{id}
Description

Clears the communication endpoint address that was set by creating the Hub.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

Usage Samples

Here's an example of a request for un-registering a listener.

Request

DELETE /api/hub/42
Accept: application/json

Response

204

PUBLISH EVENT TO LISTENER

POST /client/listener
Description

Clears the communication endpoint address that was set by creating the Hub.

Provides to a registered listener the description of the event that was raised. The /client/listener
url is the callback url passed when registering the listener.

Behavior

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

Usage Samples

Here's an example of a notification received by the listener. In this example “EVENT TYPE” should be
replaced by one of the notification types supported by this API (see Notification resources Models section)
and EVENT BODY refers to the data structure of the given notification type.

Request

POST /client/listener

© TM Forum 20167 All Rights Reserved. Page 32

Resource Ordering Management API REST Specification

Accept: application/json

{
"event": {
EVENT BODY
},
"eventType": "EVENT_TYPE"
}

Response

201

For detailed examples on the general TM Forum notification mechanism, see the TMF REST
Design Guidelines.

© TM Forum 20167 All Rights Reserved. Page 33

Resource Ordering Management API REST Specification

ACKNOWLEDGEMENTS

RELEASE HISTORY
Release Date Release led by: Description
Number

Release 1.0 04/15/2016 Pierre Gauthier Generated using the API

TM Forum data model
[email protected]

Nicoleta Stoica
Vodafone

Mariano Belaunde
Orange Labs

© TM Forum 20167 All Rights Reserved. Page 34