2 This work is licensed under a Creative Commons Attribution 4.0 International License.
3 http://creativecommons.org/licenses/by/4.0
15 https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/kl1kgvz1zR/swagger.json[Swagger UI]
18 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]
20 serviceOrder API designed for ONAP Beijing Release.
21 This API is build from TMF open API18.0 (applying TMF Guideline 3.0);
22 Only operations GET (by id and list) and POST are available.
25 === Version information
27 __Version__ : 1.0.0_inProgress
33 __BasePath__ : /nbi/api/v1
39 * 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.
44 * `application/json;charset=utf-8`
49 * `application/json;charset=utf-8`
55 [[_serviceorder_resource]]
57 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.
60 [[_serviceordercreate]]
61 ==== Create a service order
68 This operation creates a service order entity.
69 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.
70 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.
72 Specific business errors for current operation will be encapsulated in
74 HTTP Response 422 Unprocessable entity
76 * 100: OrderItem with 'add' action but serviceSpecification id missing
78 * 101: OrderItem with 'change'/'noChange'/'remove' but service id missing
80 * 102: OrderItem with 'add' action - serviceSpecification id provided but not existing
82 * 103: OrderItem with 'add' action but service id already existing in the inventory
84 * 104: A customer for existing service(s) is provided but he did not exist
86 * 105: OrderItem with 'change'/'noChange'/'remove' - Service id provided but it is not existing in the inventory
88 * 106: [Not managed for current Relese] Issue with lcpCloudRegionId and tenantId provided
93 [options="header", cols=".^2,.^3,.^4"]
96 |**Body**|**serviceOrder** +
97 __required__|<<_createserviceorder,CreateServiceOrder>>
103 [options="header", cols=".^2,.^14,.^4"]
105 |HTTP Code|Description|Schema
106 |**201**|Success|<<_createserviceorder,CreateServiceOrder>>
109 List of supported error codes:
110 - 20: Invalid URL parameter value
113 - 23: Missing body field
114 - 24: Invalid body field
116 - 26: Invalid header value
117 - 27: Missing query-string parameter
118 - 28: Invalid query-string parameter value|<<_errorrepresentation,ErrorRepresentation>>
119 |**401**|Unauthorized
121 List of supported error codes:
122 - 40: Missing credentials
123 - 41: Invalid credentials
124 - 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>>
127 List of supported error codes:
129 - 51: Forbidden requester
131 - 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>>
134 List of supported error codes:
135 - 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>>
136 |**422**|Unprocessable entity
140 Specific encapsulated business errors for current operation
142 * 100: OrderItem with 'add' action but serviceSpecification id missing
144 * 101: OrderItem with 'change'/'noChange'/'remove' but service id missing
146 * 102: OrderItem with 'add' action - serviceSpecification id provided but not existing
148 * 103: OrderItem with 'add' action but service id already existing in the inventory
150 * 104: A customer for existing service(s) is provided but he did not exist
152 * 105: OrderItem with 'change'/'noChange'/'remove' - Service id provided but it is not existing in the inventory
154 * 106: [Not managed for current Relese] Issue with lcpCloudRegionId and tenantId provided|<<_errorrepresentation,ErrorRepresentation>>
155 |**500**|Internal Server Error
157 List of supported error codes:
158 - 1: Internal error|<<_errorrepresentation,ErrorRepresentation>>
159 |**503**|Service Unavailable
161 List of supported error codes:
162 - 5: The service is temporarily unavailable
163 - 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>>
167 [[_serviceorderfind]]
168 ==== List service orders
175 Retrieve and list service order entities according to given criteria.
176 Only a predefined set of attribute is proposed.
177 Attribute selection could be described in the fields attribute.
179 Specific business errors for current operation will be encapsulated in
181 HTTP Response 422 Unprocessable entity
186 [options="header", cols=".^2,.^3,.^9,.^4"]
188 |Type|Name|Description|Schema
189 |**Query**|**description** +
191 |**Query**|**externalId** +
193 |**Query**|**fields** +
194 __optional__|this attribute could be used to filter retrieved attribute(s) and/or sort SO.|string
195 |**Query**|**limit** +
196 __optional__|The maximum number of elements to retrieve (it can be greater than the actual available number of items).|integer (int32)
197 |**Query**|**offset** +
198 __optional__|The index of the first element to retrieve. Zero is the first element of the collection.|integer (int32)
199 |**Query**|**orderDate.gt** +
200 __optional__|order date greather than|string
201 |**Query**|**orderDate.lt** +
202 __optional__|order date lower than|string
203 |**Query**|**state** +
204 __optional__|state of the order(s) to be retrieved|string
210 [options="header", cols=".^2,.^14,.^4"]
212 |HTTP Code|Description|Schema
215 `X-Total-Count` (integer (int32)) +
216 `X-Result-Count` (integer (int32))|< <<_serviceorder,ServiceOrder>> > array
219 List of supported error codes:
220 - 20: Invalid URL parameter value
223 - 23: Missing body field
224 - 24: Invalid body field
226 - 26: Invalid header value
227 - 27: Missing query-string parameter
228 - 28: Invalid query-string parameter value|<<_errorrepresentation,ErrorRepresentation>>
229 |**401**|Unauthorized
231 List of supported error codes:
232 - 40: Missing credentials
233 - 41: Invalid credentials
234 - 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>>
237 List of supported error codes:
239 - 51: Forbidden requester
241 - 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>>
244 List of supported error codes:
245 - 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>>
246 |**422**|Unprocessable entity
248 Functional error|<<_errorrepresentation,ErrorRepresentation>>
249 |**500**|Internal Server Error
251 List of supported error codes:
252 - 1: Internal error|<<_errorrepresentation,ErrorRepresentation>>
253 |**503**|Service Unavailable
255 List of supported error codes:
256 - 5: The service is temporarily unavailable
257 - 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>>
262 ==== Retrieve a service order
264 GET /serviceOrder/{id}
269 This operation retrieves a service order entity.
270 Attribute selection is enabled for all first level attributes.
272 Specific business errors for current operation will be encapsulated in
274 HTTP Response 422 Unprocessable entity
279 [options="header", cols=".^2,.^3,.^9,.^4"]
281 |Type|Name|Description|Schema
284 |**Query**|**fields** +
285 __optional__|Attribute selection|string
291 [options="header", cols=".^2,.^14,.^4"]
293 |HTTP Code|Description|Schema
294 |**200**|Success|<<_serviceorder,ServiceOrder>>
297 List of supported error codes:
298 - 20: Invalid URL parameter value
301 - 23: Missing body field
302 - 24: Invalid body field
304 - 26: Invalid header value
305 - 27: Missing query-string parameter
306 - 28: Invalid query-string parameter value|<<_errorrepresentation,ErrorRepresentation>>
307 |**401**|Unauthorized
309 List of supported error codes:
310 - 40: Missing credentials
311 - 41: Invalid credentials
312 - 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>>
315 List of supported error codes:
317 - 51: Forbidden requester
319 - 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>>
322 List of supported error codes:
323 - 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>>
324 |**422**|Unprocessable entity
326 Functional error|<<_errorrepresentation,ErrorRepresentation>>
327 |**500**|Internal Server Error
329 List of supported error codes:
330 - 1: Internal error|<<_errorrepresentation,ErrorRepresentation>>
331 |**503**|Service Unavailable
333 List of supported error codes:
334 - 5: The service is temporarily unavailable
335 - 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>>
344 Action type to be describer on the order item.
345 modify is not managed in Beijing release
347 __Type__ : enum (add, modify, delete, noChange)
350 [[_createserviceorder]]
351 === CreateServiceOrder
352 This structure is used in the operation POST for a serviceOrder request.
353 Attribute description is not accurate and should be find in the serviceOrder class.
356 [options="header", cols=".^3,.^11,.^4"]
358 |Name|Description|Schema
361 |**@schemaLocation** +
366 __optional__|Used to categorize the order that can be useful for the OM system (e.g. “broadband”, “TVOption”, …)|string
368 __optional__|A free-text description of the service order|string
370 __optional__|ID given by the consumer and only understandable by him (to facilitate his searches)|string
372 __optional__||< <<_createserviceorderitem,CreateServiceOrderItem>> > array
373 |**orderRelationship** +
374 __optional__||< <<_orderrelationship,OrderRelationship>> > array
376 __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
378 __optional__||< <<_relatedparty,RelatedParty>> > array
379 |**requestedCompletionDate** +
380 __optional__|Requested delivery date from the requestor perspective|string (date-time)
381 |**requestedStartDate** +
382 __optional__|Order start date wished by the requestor|string (date-time)
386 [[_createserviceorderitem]]
387 === CreateServiceOrderItem
388 This structure is used in the operation POST for a serviceOrder request to describe an item.
389 Attribute description is not accurate and should be find in the serviceOrderItem class.
392 [options="header", cols=".^3,.^11,.^4"]
394 |Name|Description|Schema
396 __optional__|Indicates the base type of the resource.|string
397 |**@schemaLocation** +
398 __optional__|A link to the schema describing this REST resource|string
400 __optional__|Indicates the type of resource.|string
402 __optional__||<<_actiontype,ActionType>>
404 __required__|Identifier of the line item (generally it is a sequence number 01, 02, 03, …)|string
405 |**orderItemRelationship** +
406 __optional__||< <<_orderitemrelationship,OrderItemRelationship>> > array
408 __required__||<<_service,Service>>
412 [[_errorrepresentation]]
413 === ErrorRepresentation
414 Representation of an error.
417 [options="header", cols=".^3,.^11,.^4"]
419 |Name|Description|Schema
420 |**@schemaLocation** +
421 __optional__|it provides a link to the schema describing a REST resource|string
423 __optional__|The class type of a REST resource|string
425 __required__|Application related code (as defined in the API or from a common list)|integer (int32)
427 __optional__|Text that provide more details and corrective actions related to the error. This can be shown to a client user|string
429 __required__|Text that explains the reason for error. This can be shown to a client user.|string
430 |**referenceError** +
431 __optional__|url pointing to documentation describing the error|string
433 __optional__|http error code extension like 400-2|string
439 An HUB resource is used by client side to subscribe to notification.
440 Not managed in the Beijing release.
443 [options="header", cols=".^3,.^4"]
455 [[_orderitemrelationship]]
456 === OrderItemRelationship
457 Linked order item to the one containing this attribute.
458 nbi component used this relationship to sort request to ONAP.
461 [options="header", cols=".^3,.^11,.^4"]
463 |Name|Description|Schema
465 __required__|Unique identifier of an order item|string
467 __required__||<<_relationshiptype,RelationshipType>>
471 [[_orderrelationship]]
472 === OrderRelationship
473 Linked order to the one containing this attribute.
474 This relationship is not used to sort ONAP request.
477 [options="header", cols=".^3,.^11,.^4"]
479 |Name|Description|Schema
481 __optional__|Type of the referred order.|string
483 __optional__|A hyperlink to the related order|string
485 __required__|The id of the related order|string
487 __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
493 A related party defines party which are involved in this order and the role they are playing.
495 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:
496 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.
497 o If no relatedParty are provided the service will be affected to ‘generic’ customer (dummy customer) – we assume this ‘generic’ customer always exists.
500 [options="header", cols=".^3,.^11,.^4"]
502 |Name|Description|Schema
506 __optional__|An hyperlink to the party - not used in Beijnig release|string
508 __required__|Unique identifier of a related party|string
510 __optional__|Name of the related party|string
512 __required__|The role of the related party (e.g. Owner, requester, fullfiller etc).
513 ONLY 'ONAPcustomer' is considered|string
517 [[_relationshiptype]]
520 Only reliesOn is managed in Beijing release.
522 __Type__ : enum (reliesOn)
527 Service (to be added, modified, deleted) description
530 [options="header", cols=".^3,.^11,.^4"]
532 |Name|Description|Schema
533 |**@schemaLocation** +
534 __optional__|The URL to get the resource schema.
535 Not managed in Beijing Release|string
537 __optional__|To define the service type
538 Not managed in Beijing Release|string
540 __optional__|Reference to the Service (useful for delete or modify command).
541 Not managed in Beijing release.|string
543 __required__|Identifier of a service instance.
544 It must be valued if orderItem action is 'delete' and corresponds to a AAI service.id|string
546 __optional__|Name of the service - When orderItem action is 'add' this name will be used in ONAP/SO request as InstaceName.|string
548 __optional__||< <<_relatedparty,RelatedParty>> > array
549 |**serviceCharacteristic** +
550 __optional__||< <<_servicecharacteristic,ServiceCharacteristic>> > array
551 |**serviceRelationship** +
552 __optional__||< <<_servicerelationship,ServiceRelationship>> > array
553 |**serviceSpecification** +
554 __optional__||<<_servicespecificationref,ServiceSpecificationRef>>
556 __optional__|The lifecycle state of the service requested;
557 Not managed in Beijing release.|string
561 [[_servicecharacteristic]]
562 === ServiceCharacteristic
563 ServiceCharacteristic
566 [options="header", cols=".^3,.^11,.^4"]
568 |Name|Description|Schema
570 __required__|Name of characteristic|string
572 __optional__||<<_value,Value>>
580 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
583 [options="header", cols=".^3,.^11,.^4"]
585 |Name|Description|Schema
588 |**@schemaLocation** +
593 __optional__|Used to categorize the order that can be useful for the OM system (e.g. “broadband”, “TVOption”, …)|string
594 |**completionDateTime** +
595 __optional__|Date when the order was completed|string (date-time)
597 __optional__|A free-text description of the service order|string
598 |**expectedCompletionDate** +
599 __optional__||string (date-time)
601 __optional__|ID given by the consumer and only understandable by him (to facilitate his searches)|string
603 __optional__|Hyperlink to access the order|string
605 __required__|ID created on repository side|string
607 __optional__||string (date-time)
609 __optional__||< <<_serviceorderitem,ServiceOrderItem>> > array
610 |**orderRelationship** +
611 __optional__||< <<_orderrelationship,OrderRelationship>> > array
613 __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
615 __optional__||< <<_relatedparty,RelatedParty>> > array
616 |**requestedCompletionDate** +
617 __optional__|Requested delivery date from the requestor perspective|string (date-time)
618 |**requestedStartDate** +
619 __optional__|Order start date wished by the requestor|string (date-time)
621 __optional__|Date when the order was started for processing|string (date-time)
623 __optional__||<<_statetype,StateType>>
627 [[_serviceorderitem]]
629 An identified part of the order. A service order is decomposed into one or more order items.
632 [options="header", cols=".^3,.^11,.^4"]
634 |Name|Description|Schema
636 __optional__|not used in Beijing relase|string
637 |**@schemaLocation** +
638 __optional__|not used in Beijing relase|string
640 __optional__|Used to extend the order item.
641 not used in Beijing relase|string
643 __optional__||<<_actiontype,ActionType>>
645 __required__|Identifier of the line item (generally it is a sequence number 01, 02, 03, …)|string
646 |**orderItemRelationship** +
647 __optional__||< <<_orderitemrelationship,OrderItemRelationship>> > array
649 __required__||<<_service,Service>>
651 __optional__||<<_statetype,StateType>>
660 [options="header", cols=".^3,.^11,.^4"]
662 |Name|Description|Schema
664 __optional__|Reference of the service|string
666 __required__|Unique identifier of the service|string
670 [[_servicerelationship]]
671 === ServiceRelationship
672 Linked Services to the one instantiate
673 nbi component used this relationship to sort request to ONAP.
676 [options="header", cols=".^3,.^4"]
680 __required__|<<_service,Service>>
682 __required__|<<_relationshiptype,RelationshipType>>
686 [[_servicespecificationref]]
687 === ServiceSpecificationRef
688 The service specification (these attributes are fetched from the catalogue).
691 [options="header", cols=".^3,.^11,.^4"]
693 |Name|Description|Schema
695 __optional__|Not used in Beijing release|string
696 |**@schemaLocation** +
697 __optional__|Not used in Beijing release|string
699 __optional__|Not used in Beijing release|string
701 __optional__|Reference of the service specification
702 Not used in Beijing release.|string
704 __required__|Unique identifier of the service specification
705 This information will be used to retrieve SDC information + mapped to SO ModelNameVersionIdin the request.|string
707 __optional__|Name of the service specification
708 Not used in Beijing release|string
709 |**targetServiceSchema** +
710 __optional__||<<_targetserviceschema,TargetServiceSchema>>
712 __optional__|Version of the service Specification
713 Not used in Beijing release|string
719 List of possible state for the order and the orderItem.
721 __Type__ : enum (acknowledged, rejected, pending, held, inProgress, cancelled, completed, failed, partial)
724 [[_targetserviceschema]]
725 === TargetServiceSchema
726 Target to the schema describing the service spec resource
729 [options="header", cols=".^3,.^11,.^4"]
731 |Name|Description|Schema
732 |**@schemaLocation** +
733 __required__|This field provided a link to the schema describing this REST resource.|string
735 __required__|Indicates the (class) type of resource.|string
741 Value is a descriptive structure for service characteristic;
742 For Beijing we only manage 'basic' attribute - the serviceCharacteristicValue must be used.
745 [options="header", cols=".^3,.^11,.^4"]
747 |Name|Description|Schema
748 |**@schemaLocation** +
749 __optional__|This field provided a link to the schema describing this REST resource.
750 Not used in Beijing Release|string
752 __optional__|Indicates the (class) type of resource.
753 Not used in Beijing Release|string
754 |**serviceCharacteristicValue** +
755 __optional__|Value of the characteristic.
756 This attribute must be used in Beijing Release to provide characteristic value.|string