Overview

serviceOrder API designed for ONAP Beijing Release. This API is build from TMF open API18.0 (applying TMF Guideline 3.0); Only operations GET (by id and list) and POST are available.

Version information

Version : 1.0.0_inProgress

URI scheme

Host : serverRoot
BasePath : /nbi/api/v1
Schemes : HTTPS

Tags

  • ServiceOrder : A Service Order is a type of order which can be used to describe a group of operations on service – one service order item per service. An action at the level of the service order item describe the operation to be done on a service (add, terminate for example). The service order is triggered from the BSS system in charge of the product order management to ONAP that will manage the service fulfillment.

Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Resources

ServiceOrder

A Service Order is a type of order which can be used to describe a group of operations on service – one service order item per service. An action at the level of the service order item describe the operation to be done on a service (add, terminate for example). The service order is triggered from the BSS system in charge of the product order management to ONAP that will manage the service fulfillment.

Create a service order

POST /serviceOrder
Description

This operation creates a service order entity. The TMF Open API specification document provides the list of mandatory and non mandatory attributes when creating a ServiceOrder, including any possible rule conditions and applicable default values. POST should be used without specifying the id and the href, the Service Order Management system is in charge of generating the id + href for the ServiceOrder.

Specific business errors for current operation will be encapsulated in

HTTP Response 422 Unprocessable entity

  • 100: OrderItem with 'add' action but serviceSpecification id missing

  • 101: OrderItem with 'change'/'noChange'/'remove' but service id missing

  • 102: OrderItem with 'add' action - serviceSpecification id provided but not existing

  • 103: OrderItem with 'add' action but service id already existing in the inventory

  • 104: A customer for existing service(s) is provided but he did not exist

  • 105: OrderItem with 'change'/'noChange'/'remove' - Service id provided but it is not existing in the inventory

  • 106: [Not managed for current Relese] Issue with lcpCloudRegionId and tenantId provided

Parameters
Type Name Schema

Body

serviceOrder
required

CreateServiceOrder
Responses
HTTP Code Description Schema

201

Success

CreateServiceOrder

400

Bad Request

List of supported error codes: - 20: Invalid URL parameter value - 21: Missing body - 22: Invalid body - 23: Missing body field - 24: Invalid body field - 25: Missing header - 26: Invalid header value - 27: Missing query-string parameter - 28: Invalid query-string parameter value

ErrorRepresentation

401

Unauthorized

List of supported error codes: - 40: Missing credentials - 41: Invalid credentials - 42: Expired credentials

ErrorRepresentation

403

Forbidden

List of supported error codes: - 50: Access denied - 51: Forbidden requester - 52: Forbidden user - 53: Too many requests

ErrorRepresentation

404

Not Found

List of supported error codes: - 60: Resource not found

ErrorRepresentation

422

Unprocessable entity

Functional error

Specific encapsulated business errors for current operation

* 100: OrderItem with 'add' action but serviceSpecification id missing

* 101: OrderItem with 'change'/'noChange'/'remove' but service id missing

* 102: OrderItem with 'add' action - serviceSpecification id provided but not existing

* 103: OrderItem with 'add' action but service id already existing in the inventory

* 104: A customer for existing service(s) is provided but he did not exist

* 105: OrderItem with 'change'/'noChange'/'remove' - Service id provided but it is not existing in the inventory

* 106: [Not managed for current Relese] Issue with lcpCloudRegionId and tenantId provided

ErrorRepresentation

500

Internal Server Error

List of supported error codes: - 1: Internal error

ErrorRepresentation

503

Service Unavailable

List of supported error codes: - 5: The service is temporarily unavailable - 6: Orange API is over capacity, retry later !

ErrorRepresentation

List service orders

GET /serviceOrder
Description

Retrieve and list service order entities according to given criteria. Only a predefined set of attribute is proposed. Attribute selection could be described in the fields attribute.

Specific business errors for current operation will be encapsulated in

HTTP Response 422 Unprocessable entity

Parameters
Type Name Description Schema

Query

description
optional

string

Query

externalId
optional

string

Query

fields
optional

this attribute could be used to filter retrieved attribute(s) and/or sort SO.

string

Query

limit
optional

The maximum number of elements to retrieve (it can be greater than the actual available number of items).

integer (int32)

Query

offset
optional

The index of the first element to retrieve. Zero is the first element of the collection.

integer (int32)

Query

orderDate.gt
optional

order date greather than

string

Query

orderDate.lt
optional

order date lower than

string

Query

state
optional

state of the order(s) to be retrieved

string
Responses
HTTP Code Description Schema

200

Success
Headers :
X-Total-Count (integer (int32))
X-Result-Count (integer (int32))

< ServiceOrder > array

400

Bad Request

List of supported error codes: - 20: Invalid URL parameter value - 21: Missing body - 22: Invalid body - 23: Missing body field - 24: Invalid body field - 25: Missing header - 26: Invalid header value - 27: Missing query-string parameter - 28: Invalid query-string parameter value

ErrorRepresentation

401

Unauthorized

List of supported error codes: - 40: Missing credentials - 41: Invalid credentials - 42: Expired credentials

ErrorRepresentation

403

Forbidden

List of supported error codes: - 50: Access denied - 51: Forbidden requester - 52: Forbidden user - 53: Too many requests

ErrorRepresentation

404

Not Found

List of supported error codes: - 60: Resource not found

ErrorRepresentation

422

Unprocessable entity

Functional error

ErrorRepresentation

500

Internal Server Error

List of supported error codes: - 1: Internal error

ErrorRepresentation

503

Service Unavailable

List of supported error codes: - 5: The service is temporarily unavailable - 6: Orange API is over capacity, retry later !

ErrorRepresentation

Retrieve a service order

GET /serviceOrder/{id}
Description

This operation retrieves a service order entity. Attribute selection is enabled for all first level attributes.

Specific business errors for current operation will be encapsulated in

HTTP Response 422 Unprocessable entity

Parameters
Type Name Description Schema

Path

id
required

string

Query

fields
optional

Attribute selection

string
Responses
HTTP Code Description Schema

200

Success

ServiceOrder

400

Bad Request

List of supported error codes: - 20: Invalid URL parameter value - 21: Missing body - 22: Invalid body - 23: Missing body field - 24: Invalid body field - 25: Missing header - 26: Invalid header value - 27: Missing query-string parameter - 28: Invalid query-string parameter value

ErrorRepresentation

401

Unauthorized

List of supported error codes: - 40: Missing credentials - 41: Invalid credentials - 42: Expired credentials

ErrorRepresentation

403

Forbidden

List of supported error codes: - 50: Access denied - 51: Forbidden requester - 52: Forbidden user - 53: Too many requests

ErrorRepresentation

404

Not Found

List of supported error codes: - 60: Resource not found

ErrorRepresentation

422

Unprocessable entity

Functional error

ErrorRepresentation

500

Internal Server Error

List of supported error codes: - 1: Internal error

ErrorRepresentation

503

Service Unavailable

List of supported error codes: - 5: The service is temporarily unavailable - 6: Orange API is over capacity, retry later !

ErrorRepresentation

Definitions

ActionType

Action type to be describer on the order item. modify is not managed in Beijing release

Type : enum (add, modify, delete, noChange)

CreateServiceOrder

This structure is used in the operation POST for a serviceOrder request. Attribute description is not accurate and should be find in the serviceOrder class.

Name Description Schema

@baseType
optional

string

@schemaLocation
optional

string

@type
optional

string

category
optional

Used to categorize the order that can be useful for the OM system (e.g. “broadband”, “TVOption”, …)

string

description
optional

A free-text description of the service order

string

externalId
optional

ID given by the consumer and only understandable by him (to facilitate his searches)

string

orderItem
optional

< CreateServiceOrderItem > array

orderRelationship
optional

< OrderRelationship > array

priority
optional

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

string

relatedParty
optional

< RelatedParty > array

requestedCompletionDate
optional

Requested delivery date from the requestor perspective

string (date-time)

requestedStartDate
optional

Order start date wished by the requestor

string (date-time)

CreateServiceOrderItem

This structure is used in the operation POST for a serviceOrder request to describe an item. Attribute description is not accurate and should be find in the serviceOrderItem class.

Name Description Schema

@baseType
optional

Indicates the base type of the resource.

string

@schemaLocation
optional

A link to the schema describing this REST resource

string

@type
optional

Indicates the type of resource.

string

action
optional

ActionType

id
required

Identifier of the line item (generally it is a sequence number 01, 02, 03, …)

string

orderItemRelationship
optional

< OrderItemRelationship > array

service
required

Service

ErrorRepresentation

Representation of an error.

Name Description Schema

@schemaLocation
optional

it provides a link to the schema describing a REST resource

string

@type
optional

The class type of a REST resource

string

code
required

Application related code (as defined in the API or from a common list)

integer (int32)

message
optional

Text that provide more details and corrective actions related to the error. This can be shown to a client user

string

reason
required

Text that explains the reason for error. This can be shown to a client user.

string

referenceError
optional

url pointing to documentation describing the error

string

status
optional

http error code extension like 400-2

string

Hub

An HUB resource is used by client side to subscribe to notification. Not managed in the Beijing release.

Name Schema

callback
required

string

id
optional

string

query
optional

string

OrderItemRelationship

Linked order item to the one containing this attribute. nbi component used this relationship to sort request to ONAP.

Name Description Schema

id
required

Unique identifier of an order item

string

type
required

RelationshipType

OrderRelationship

Linked order to the one containing this attribute. This relationship is not used to sort ONAP request.

Name Description Schema

@referredType
optional

Type of the referred order.

string

href
optional

A hyperlink to the related order

string

id
required

The id of the related order

string

type
optional

The type of related order, can be : “dependency” if the order needs to be “not started” until another order item is complete (a service order in this case) or “cross-ref” to keep track of the source order (a productOrder)

string

RelatedParty

A related party defines party which are involved in this order and the role they are playing. for Beijing release: With the current version of APIs used from SO and AAI we need to manage a ‘customer’. This customer concept is confusing with Customer BSS concept. We took the following rules to manage the ‘customer’ information: o It could be provided through a serviceOrder in the service Order a relatedParty with role ‘ONAPcustomer’ should be provided in the serviceOrder header (we will not consider in this release the party at item level); External API component will check if this customer exists and create it in AAI if not. o If no relatedParty are provided the service will be affected to ‘generic’ customer (dummy customer) – we assume this ‘generic’ customer always exists.

Name Description Schema

@referredType
optional

string

href
optional

An hyperlink to the party - not used in Beijnig release

string

id
required

Unique identifier of a related party

string

name
optional

Name of the related party

string

role
required

The role of the related party (e.g. Owner, requester, fullfiller etc). ONLY 'ONAPcustomer' is considered

string

RelationshipType

Relationship type; Only reliesOn is managed in Beijing release.

Type : enum (reliesOn)

Service

Service (to be added, modified, deleted) description

Name Description Schema

@schemaLocation
optional

The URL to get the resource schema. Not managed in Beijing Release

string

@type
optional

To define the service type Not managed in Beijing Release

string

href
optional

Reference to the Service (useful for delete or modify command). Not managed in Beijing release.

string

id
required

Identifier of a service instance. It must be valued if orderItem action is 'delete' and corresponds to a AAI service.id

string

name
optional

Name of the service - When orderItem action is 'add' this name will be used in ONAP/SO request as InstaceName.

string

relatedParty
optional

< RelatedParty > array

serviceCharacteristic
optional

< ServiceCharacteristic > array

serviceRelationship
optional

< ServiceRelationship > array

serviceSpecification
optional

ServiceSpecificationRef

serviceState
optional

The lifecycle state of the service requested; Not managed in Beijing release.

string

ServiceCharacteristic

ServiceCharacteristic

Name Description Schema

name
required

Name of characteristic

string

value
optional

Value

valueType
optional

string

ServiceOrder

A Service Order is a type of order which can be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa

Name Description Schema

@baseType
optional

string

@schemaLocation
optional

string

@type
optional

string

category
optional

Used to categorize the order that can be useful for the OM system (e.g. “broadband”, “TVOption”, …)

string

completionDateTime
optional

Date when the order was completed

string (date-time)

description
optional

A free-text description of the service order

string

expectedCompletionDate
optional

string (date-time)

externalId
optional

ID given by the consumer and only understandable by him (to facilitate his searches)

string

href
optional

Hyperlink to access the order

string

id
required

ID created on repository side

string

orderDate
optional

string (date-time)

orderItem
optional

< ServiceOrderItem > array

orderRelationship
optional

< OrderRelationship > array

priority
optional

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

string

relatedParty
optional

< RelatedParty > array

requestedCompletionDate
optional

Requested delivery date from the requestor perspective

string (date-time)

requestedStartDate
optional

Order start date wished by the requestor

string (date-time)

startDate
optional

Date when the order was started for processing

string (date-time)

state
optional

StateType

ServiceOrderItem

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

Name Description Schema

@baseType
optional

not used in Beijing relase

string

@schemaLocation
optional

not used in Beijing relase

string

@type
optional

Used to extend the order item. not used in Beijing relase

string

action
optional

ActionType

id
required

Identifier of the line item (generally it is a sequence number 01, 02, 03, …)

string

orderItemRelationship
optional

< OrderItemRelationship > array

service
required

Service

state
optional

StateType

ServiceRef

Service references

Name Description Schema

href
optional

Reference of the service

string

id
required

Unique identifier of the service

string

ServiceRelationship

Linked Services to the one instantiate nbi component used this relationship to sort request to ONAP.

Name Schema

service
required

Service

type
required

RelationshipType

ServiceSpecificationRef

The service specification (these attributes are fetched from the catalogue).

Name Description Schema

@baseType
optional

Not used in Beijing release

string

@schemaLocation
optional

Not used in Beijing release

string

@type
optional

Not used in Beijing release

string

href
optional

Reference of the service specification Not used in Beijing release.

string

id
required

Unique identifier of the service specification This information will be used to retrieve SDC information + mapped to SO ModelNameVersionIdin the request.

string

name
optional

Name of the service specification Not used in Beijing release

string

targetServiceSchema
optional

TargetServiceSchema

version
optional

Version of the service Specification Not used in Beijing release

string

StateType

List of possible state for the order and the orderItem.

Type : enum (acknowledged, rejected, pending, held, inProgress, cancelled, completed, failed, partial)

TargetServiceSchema

Target to the schema describing the service spec resource

Name Description Schema

@schemaLocation
required

This field provided a link to the schema describing this REST resource.

string

@type
required

Indicates the (class) type of resource.

string

Value

Value is a descriptive structure for service characteristic; For Beijing we only manage 'basic' attribute - the serviceCharacteristicValue must be used.

Name Description Schema

@schemaLocation
optional

This field provided a link to the schema describing this REST resource. Not used in Beijing Release

string

@type
optional

Indicates the (class) type of resource. Not used in Beijing Release

string

serviceCharacteristicValue
optional

Value of the characteristic. This attribute must be used in Beijing Release to provide characteristic value.

string