From 7afe844fb9f4171697ff5b82b86b2161ffbf2a78 Mon Sep 17 00:00:00 2001 From: Rene Robert Date: Wed, 28 Mar 2018 09:55:53 +0000 Subject: add API documentations Issue-ID: EXTAPI-40 Change-Id: If700a2e2700f7c19e22c8f5d11ddf425eb0075a5 Signed-off-by: Rene Robert --- .../serviceOrder/apiServiceOrder.plantuml | 168 ++ docs/offeredapis/serviceOrder/asciiDoc.adoc | 752 ++++++++ docs/offeredapis/serviceOrder/documentation.html | 2030 ++++++++++++++++++++ docs/offeredapis/serviceOrder/markDown.md | 463 +++++ 4 files changed, 3413 insertions(+) create mode 100644 docs/offeredapis/serviceOrder/apiServiceOrder.plantuml create mode 100644 docs/offeredapis/serviceOrder/asciiDoc.adoc create mode 100644 docs/offeredapis/serviceOrder/documentation.html create mode 100644 docs/offeredapis/serviceOrder/markDown.md (limited to 'docs/offeredapis/serviceOrder') diff --git a/docs/offeredapis/serviceOrder/apiServiceOrder.plantuml b/docs/offeredapis/serviceOrder/apiServiceOrder.plantuml new file mode 100644 index 0000000..3199855 --- /dev/null +++ b/docs/offeredapis/serviceOrder/apiServiceOrder.plantuml @@ -0,0 +1,168 @@ +@startuml + +enum ActionType { + add + modify + delete + noChange +} +enum StateType { + acknowledged + rejected + pending + held + inProgress + cancelled + completed + failed + partial +} +enum RelationshipType { + reliesOn +} + +class ErrorRepresentation { + code:int + reason:string + message:string + status:string + referenceError:string + @type:string + @schemaLocation:string +} + +class ServiceRelationship + ServiceRelationship --> "1-1" RelationshipType : type + ServiceRelationship --> "1-1" Service : service + +class ServiceRef { + id:string + href:string +} + +class ServiceCharacteristic { + name:string + valueType:string +} + ServiceCharacteristic --> "0-1" Value : value + +class RelatedParty { + id:string + href:string + role:string + name:string + @referredType:string +} + +class ServiceSpecificationRef { + id:string + href:string + name:string + version:string + @type:string + @schemaLocation:string + @baseType:string +} + ServiceSpecificationRef --> "0-1" TargetServiceSchema : targetServiceSchema + +class Service { + id:string + href:string + name:string + serviceState:string + @type:string + @schemaLocation:string +} + Service --> "0-*" ServiceCharacteristic : serviceCharacteristic + Service --> "0-*" ServiceRelationship : serviceRelationship + Service --> "0-*" RelatedParty : relatedParty + Service --> "0-1" ServiceSpecificationRef : serviceSpecification + +class OrderItemRelationship { + id:string +} + OrderItemRelationship --> "1-1" RelationshipType : type + +class ServiceOrderItem { + id:string + @type:string + @schemaLocation:string + @baseType:string +} + ServiceOrderItem --> "0-1" ActionType : action + ServiceOrderItem --> "0-1" StateType : state + ServiceOrderItem --> "0-*" OrderItemRelationship : orderItemRelationship + ServiceOrderItem --> "1-1" Service : service + +class ServiceOrder { + id:string + href:string + externalId:string + priority:string + description:string + category:string + orderDate:dateTime + completionDateTime:dateTime + requestedStartDate:dateTime + requestedCompletionDate:dateTime + expectedCompletionDate:dateTime + startDate:dateTime + @baseType:string + @type:string + @schemaLocation:string +} + ServiceOrder --> "0-1" StateType : state + ServiceOrder --> "0-*" RelatedParty : relatedParty + ServiceOrder --> "0-*" OrderRelationship : orderRelationship + ServiceOrder --> "0-*" ServiceOrderItem : orderItem + +class OrderRelationship { + type:string + id:string + href:string + @referredType:string +} + +class TargetServiceSchema { + @type:string + @schemaLocation:string +} + +class Value { + @type:string + @schemaLocation:string + serviceCharacteristicValue:string +} + +class CreateServiceOrderItem { + id:string + @type:string + @schemaLocation:string + @baseType:string +} + CreateServiceOrderItem --> "0-1" ActionType : action + CreateServiceOrderItem --> "0-*" OrderItemRelationship : orderItemRelationship + CreateServiceOrderItem --> "1-1" Service : service + +class CreateServiceOrder { + externalId:string + priority:string + description:string + category:string + requestedStartDate:dateTime + requestedCompletionDate:dateTime + @baseType:string + @type:string + @schemaLocation:string +} + CreateServiceOrder --> "0-*" RelatedParty : relatedParty + CreateServiceOrder --> "0-*" OrderRelationship : orderRelationship + CreateServiceOrder --> "0-*" CreateServiceOrderItem : orderItem + +class Hub { + id:string + query:string + callback:string +} + +@enduml \ No newline at end of file diff --git a/docs/offeredapis/serviceOrder/asciiDoc.adoc b/docs/offeredapis/serviceOrder/asciiDoc.adoc new file mode 100644 index 0000000..4a29548 --- /dev/null +++ b/docs/offeredapis/serviceOrder/asciiDoc.adoc @@ -0,0 +1,752 @@ += API ServiceOrder + + +[[_overview]] +== Overview + +=== Api URL + +https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/kl1kgvz1zR/swagger.json[Swagger UI] + + +https://plantuml.rd.francetelecom.fr/proxy?fmt=svg&src=https://api-designer.sso.infra.ftgroup/api/1.0/apis/kl1kgvz1zR/plantuml&noCache=934804.0[plant UML UI] + +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 +[%hardbreaks] +__Version__ : 1.0.0_inProgress + + +=== URI scheme +[%hardbreaks] +__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` + + +[[_paths]] +== Resources + +[[_serviceorder_resource]] +=== 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. + + +[[_serviceordercreate]] +==== 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 + +[options="header", cols=".^2,.^3,.^4"] +|=== +|Type|Name|Schema +|**Body**|**serviceOrder** + +__required__|<<_createserviceorder,CreateServiceOrder>> +|=== + + +===== Responses + +[options="header", cols=".^2,.^14,.^4"] +|=== +|HTTP Code|Description|Schema +|**201**|Success|<<_createserviceorder,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,ErrorRepresentation>> +|**401**|Unauthorized + +List of supported error codes: +- 40: Missing credentials +- 41: Invalid credentials +- 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>> +|**403**|Forbidden + +List of supported error codes: +- 50: Access denied +- 51: Forbidden requester +- 52: Forbidden user +- 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>> +|**404**|Not Found + +List of supported error codes: +- 60: Resource not found|<<_errorrepresentation,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,ErrorRepresentation>> +|**500**|Internal Server Error + +List of supported error codes: +- 1: Internal error|<<_errorrepresentation,ErrorRepresentation>> +|**503**|Service Unavailable + +List of supported error codes: +- 5: The service is temporarily unavailable +- 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>> +|=== + + +[[_serviceorderfind]] +==== 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 + +[options="header", cols=".^2,.^3,.^9,.^4"] +|=== +|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 + +[options="header", cols=".^2,.^14,.^4"] +|=== +|HTTP Code|Description|Schema +|**200**|Success + +**Headers** : + +`X-Total-Count` (integer (int32)) + +`X-Result-Count` (integer (int32))|< <<_serviceorder,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,ErrorRepresentation>> +|**401**|Unauthorized + +List of supported error codes: +- 40: Missing credentials +- 41: Invalid credentials +- 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>> +|**403**|Forbidden + +List of supported error codes: +- 50: Access denied +- 51: Forbidden requester +- 52: Forbidden user +- 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>> +|**404**|Not Found + +List of supported error codes: +- 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>> +|**422**|Unprocessable entity + +Functional error|<<_errorrepresentation,ErrorRepresentation>> +|**500**|Internal Server Error + +List of supported error codes: +- 1: Internal error|<<_errorrepresentation,ErrorRepresentation>> +|**503**|Service Unavailable + +List of supported error codes: +- 5: The service is temporarily unavailable +- 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>> +|=== + + +[[_serviceorderget]] +==== 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 + +[options="header", cols=".^2,.^3,.^9,.^4"] +|=== +|Type|Name|Description|Schema +|**Path**|**id** + +__required__||string +|**Query**|**fields** + +__optional__|Attribute selection|string +|=== + + +===== Responses + +[options="header", cols=".^2,.^14,.^4"] +|=== +|HTTP Code|Description|Schema +|**200**|Success|<<_serviceorder,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,ErrorRepresentation>> +|**401**|Unauthorized + +List of supported error codes: +- 40: Missing credentials +- 41: Invalid credentials +- 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>> +|**403**|Forbidden + +List of supported error codes: +- 50: Access denied +- 51: Forbidden requester +- 52: Forbidden user +- 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>> +|**404**|Not Found + +List of supported error codes: +- 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>> +|**422**|Unprocessable entity + +Functional error|<<_errorrepresentation,ErrorRepresentation>> +|**500**|Internal Server Error + +List of supported error codes: +- 1: Internal error|<<_errorrepresentation,ErrorRepresentation>> +|**503**|Service Unavailable + +List of supported error codes: +- 5: The service is temporarily unavailable +- 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>> +|=== + + +[[_definitions]] +== Definitions + +[[_actiontype]] +=== ActionType +Action type to be describer on the order item. +modify is not managed in Beijing release + +__Type__ : enum (add, modify, delete, noChange) + + +[[_createserviceorder]] +=== 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. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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,CreateServiceOrderItem>> > array +|**orderRelationship** + +__optional__||< <<_orderrelationship,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,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]] +=== 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. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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,ActionType>> +|**id** + +__required__|Identifier of the line item (generally it is a sequence number 01, 02, 03, …)|string +|**orderItemRelationship** + +__optional__||< <<_orderitemrelationship,OrderItemRelationship>> > array +|**service** + +__required__||<<_service,Service>> +|=== + + +[[_errorrepresentation]] +=== ErrorRepresentation +Representation of an error. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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]] +=== Hub +An HUB resource is used by client side to subscribe to notification. +Not managed in the Beijing release. + + +[options="header", cols=".^3,.^4"] +|=== +|Name|Schema +|**callback** + +__required__|string +|**id** + +__optional__|string +|**query** + +__optional__|string +|=== + + +[[_orderitemrelationship]] +=== OrderItemRelationship +Linked order item to the one containing this attribute. +nbi component used this relationship to sort request to ONAP. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|Name|Description|Schema +|**id** + +__required__|Unique identifier of an order item|string +|**type** + +__required__||<<_relationshiptype,RelationshipType>> +|=== + + +[[_orderrelationship]] +=== OrderRelationship +Linked order to the one containing this attribute. +This relationship is not used to sort ONAP request. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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]] +=== 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. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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]] +=== RelationshipType +Relationship type; +Only reliesOn is managed in Beijing release. + +__Type__ : enum (reliesOn) + + +[[_service]] +=== Service +Service (to be added, modified, deleted) description + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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,RelatedParty>> > array +|**serviceCharacteristic** + +__optional__||< <<_servicecharacteristic,ServiceCharacteristic>> > array +|**serviceRelationship** + +__optional__||< <<_servicerelationship,ServiceRelationship>> > array +|**serviceSpecification** + +__optional__||<<_servicespecificationref,ServiceSpecificationRef>> +|**serviceState** + +__optional__|The lifecycle state of the service requested; +Not managed in Beijing release.|string +|=== + + +[[_servicecharacteristic]] +=== ServiceCharacteristic +ServiceCharacteristic + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|Name|Description|Schema +|**name** + +__required__|Name of characteristic|string +|**value** + +__optional__||<<_value,Value>> +|**valueType** + +__optional__||string +|=== + + +[[_serviceorder]] +=== 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 + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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,ServiceOrderItem>> > array +|**orderRelationship** + +__optional__||< <<_orderrelationship,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,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,StateType>> +|=== + + +[[_serviceorderitem]] +=== ServiceOrderItem +An identified part of the order. A service order is decomposed into one or more order items. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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,ActionType>> +|**id** + +__required__|Identifier of the line item (generally it is a sequence number 01, 02, 03, …)|string +|**orderItemRelationship** + +__optional__||< <<_orderitemrelationship,OrderItemRelationship>> > array +|**service** + +__required__||<<_service,Service>> +|**state** + +__optional__||<<_statetype,StateType>> +|=== + + +[[_serviceref]] +=== ServiceRef +Service references + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|Name|Description|Schema +|**href** + +__optional__|Reference of the service|string +|**id** + +__required__|Unique identifier of the service|string +|=== + + +[[_servicerelationship]] +=== ServiceRelationship +Linked Services to the one instantiate +nbi component used this relationship to sort request to ONAP. + + +[options="header", cols=".^3,.^4"] +|=== +|Name|Schema +|**service** + +__required__|<<_service,Service>> +|**type** + +__required__|<<_relationshiptype,RelationshipType>> +|=== + + +[[_servicespecificationref]] +=== ServiceSpecificationRef +The service specification (these attributes are fetched from the catalogue). + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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,TargetServiceSchema>> +|**version** + +__optional__|Version of the service Specification +Not used in Beijing release|string +|=== + + +[[_statetype]] +=== StateType +List of possible state for the order and the orderItem. + +__Type__ : enum (acknowledged, rejected, pending, held, inProgress, cancelled, completed, failed, partial) + + +[[_targetserviceschema]] +=== TargetServiceSchema +Target to the schema describing the service spec resource + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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 +Value is a descriptive structure for service characteristic; +For Beijing we only manage 'basic' attribute - the serviceCharacteristicValue must be used. + + +[options="header", cols=".^3,.^11,.^4"] +|=== +|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 +|=== + diff --git a/docs/offeredapis/serviceOrder/documentation.html b/docs/offeredapis/serviceOrder/documentation.html new file mode 100644 index 0000000..0983ed9 --- /dev/null +++ b/docs/offeredapis/serviceOrder/documentation.html @@ -0,0 +1,2030 @@ + + + + + + + +API ServiceOrder + + + + + +
+
+

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
+ +++++ + + + + + + + + + + + + + + +
TypeNameSchema

Body

serviceOrder
+required

CreateServiceOrder

+
+
+
Responses
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HTTP CodeDescriptionSchema

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
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescriptionSchema

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 CodeDescriptionSchema

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
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescriptionSchema

Path

id
+required

string

Query

fields
+optional

Attribute selection

string

+
+
+
Responses
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HTTP CodeDescriptionSchema

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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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.

+
+ ++++ + + + + + + + + + + + + + + + + + + + + +
NameSchema

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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

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

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

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.

+
+ ++++ + + + + + + + + + + + + + + + + +
NameSchema

service
+required

Service

type
+required

RelationshipType

+
+
+

ServiceSpecificationRef

+
+

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

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSchema

@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

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/offeredapis/serviceOrder/markDown.md b/docs/offeredapis/serviceOrder/markDown.md new file mode 100644 index 0000000..5ee40cf --- /dev/null +++ b/docs/offeredapis/serviceOrder/markDown.md @@ -0,0 +1,463 @@ +# API ServiceOrder + + + +## Overview + +### Api URL + +[Swagger UI](https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/kl1kgvz1zR/swagger.json) + + +[plant UML UI](https://plantuml.rd.francetelecom.fr/proxy?fmt=svg&src=https://api-designer.sso.infra.ftgroup/api/1.0/apis/kl1kgvz1zR/plantuml&noCache=934804.0) + +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](#createserviceorder)| + + +##### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**201**|Success|[CreateServiceOrder](#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](#errorrepresentation)| +|**401**|Unauthorized

List of supported error codes:
- 40: Missing credentials
- 41: Invalid credentials
- 42: Expired credentials|[ErrorRepresentation](#errorrepresentation)| +|**403**|Forbidden

List of supported error codes:
- 50: Access denied
- 51: Forbidden requester
- 52: Forbidden user
- 53: Too many requests|[ErrorRepresentation](#errorrepresentation)| +|**404**|Not Found

List of supported error codes:
- 60: Resource not found|[ErrorRepresentation](#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](#errorrepresentation)| +|**500**|Internal Server Error

List of supported error codes:
- 1: Internal error|[ErrorRepresentation](#errorrepresentation)| +|**503**|Service Unavailable

List of supported error codes:
- 5: The service is temporarily unavailable
- 6: Orange API is over capacity, retry later !|[ErrorRepresentation](#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](#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](#errorrepresentation)| +|**401**|Unauthorized

List of supported error codes:
- 40: Missing credentials
- 41: Invalid credentials
- 42: Expired credentials|[ErrorRepresentation](#errorrepresentation)| +|**403**|Forbidden

List of supported error codes:
- 50: Access denied
- 51: Forbidden requester
- 52: Forbidden user
- 53: Too many requests|[ErrorRepresentation](#errorrepresentation)| +|**404**|Not Found

List of supported error codes:
- 60: Resource not found|[ErrorRepresentation](#errorrepresentation)| +|**422**|Unprocessable entity

Functional error|[ErrorRepresentation](#errorrepresentation)| +|**500**|Internal Server Error

List of supported error codes:
- 1: Internal error|[ErrorRepresentation](#errorrepresentation)| +|**503**|Service Unavailable

List of supported error codes:
- 5: The service is temporarily unavailable
- 6: Orange API is over capacity, retry later !|[ErrorRepresentation](#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](#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](#errorrepresentation)| +|**401**|Unauthorized

List of supported error codes:
- 40: Missing credentials
- 41: Invalid credentials
- 42: Expired credentials|[ErrorRepresentation](#errorrepresentation)| +|**403**|Forbidden

List of supported error codes:
- 50: Access denied
- 51: Forbidden requester
- 52: Forbidden user
- 53: Too many requests|[ErrorRepresentation](#errorrepresentation)| +|**404**|Not Found

List of supported error codes:
- 60: Resource not found|[ErrorRepresentation](#errorrepresentation)| +|**422**|Unprocessable entity

Functional error|[ErrorRepresentation](#errorrepresentation)| +|**500**|Internal Server Error

List of supported error codes:
- 1: Internal error|[ErrorRepresentation](#errorrepresentation)| +|**503**|Service Unavailable

List of supported error codes:
- 5: The service is temporarily unavailable
- 6: Orange API is over capacity, retry later !|[ErrorRepresentation](#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](#createserviceorderitem) > array| +|**orderRelationship**
*optional*||< [OrderRelationship](#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](#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](#actiontype)| +|**id**
*required*|Identifier of the line item (generally it is a sequence number 01, 02, 03, …)|string| +|**orderItemRelationship**
*optional*||< [OrderItemRelationship](#orderitemrelationship) > array| +|**service**
*required*||[Service](#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](#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](#relatedparty) > array| +|**serviceCharacteristic**
*optional*||< [ServiceCharacteristic](#servicecharacteristic) > array| +|**serviceRelationship**
*optional*||< [ServiceRelationship](#servicerelationship) > array| +|**serviceSpecification**
*optional*||[ServiceSpecificationRef](#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](#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](#serviceorderitem) > array| +|**orderRelationship**
*optional*||< [OrderRelationship](#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](#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](#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](#actiontype)| +|**id**
*required*|Identifier of the line item (generally it is a sequence number 01, 02, 03, …)|string| +|**orderItemRelationship**
*optional*||< [OrderItemRelationship](#orderitemrelationship) > array| +|**service**
*required*||[Service](#service)| +|**state**
*optional*||[StateType](#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](#service)| +|**type**
*required*|[RelationshipType](#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](#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| + -- cgit 1.2.3-korg