diff options
Diffstat (limited to 'docs/offeredapis/serviceOrder/asciiDoc.adoc')
| -rw-r--r-- | docs/offeredapis/serviceOrder/asciiDoc.adoc | 752 |
1 files changed, 752 insertions, 0 deletions
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 +|=== + |