path: root/docs/offeredapis/swaggers/serviceOrder_1_0_0.yaml

# This work is licensed under a Creative Commons Attribution 4.0 International License.
# http://creativecommons.org/licenses/by/4.0
# Copyright 2018 Orange

swagger: "2.0"
info:
  description: "serviceOrder API designed for ONAP Beijing Release.\nThis API is build\
    \ from TMF open API18.0 (applying TMF Guideline 3.0);\nOnly operations GET (by\
    \ id and list) and POST are available."
  version: "1.0.0_inProgress"
  title: "API ServiceOrder"
  x-logo:
    url: "/redoc/logo.png"
    backgroundColor: "#FFFFFF"
host: "serverRoot"
basePath: "/nbi/api/v1"
schemes:
- "https"
consumes:
- "application/json;charset=utf-8"
produces:
- "application/json;charset=utf-8"
tags:
- name: "ServiceOrder"
  description: "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."
paths:
  /serviceOrder:
    post:
      tags:
      - "ServiceOrder"
      operationId: "serviceOrderCreate"
      summary: "Create a service order"
      description: "This operation creates a service order entity.\nThe 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.\nPOST 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.\n\nSpecific business errors for current\
        \ operation will be encapsulated in\n\nHTTP Response 422 Unprocessable entity\n\
        \n - 100: OrderItem with 'add' action but serviceSpecification id missing\n\
        \   \n - 101: OrderItem with 'change'/'noChange'/'remove' but service id missing\n\
        \   \n - 102: OrderItem with 'add' action - serviceSpecification id provided\
        \ but not existing\n   \n - 103: OrderItem with 'add' action but service id\
        \ already existing in the inventory\n   \n - 104: A customer for existing\
        \ service(s) is provided but he did not exist\n   \n - 105: OrderItem with\
        \ 'change'/'noChange'/'remove' - Service id provided but it is not existing\
        \ in the inventory\n   \n - 106: [Not managed for current Relese] Issue with\
        \ lcpCloudRegionId  and tenantId provided\n   "
      deprecated: false
      parameters:
      - name: "serviceOrder"
        required: true
        in: "body"
        description: ""
        schema:
          $ref: "#/definitions/CreateServiceOrder"
      responses:
        201:
          description: "Success"
          schema:
            $ref: "#/definitions/CreateServiceOrder"
        400:
          description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
            \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
            \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
            \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
            \ parameter value"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        401:
          description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
            \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        403:
          description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
            \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
            \ requests"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        404:
          description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
            \ not found"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        422:
          description: "Unprocessable entity\n\nFunctional error\n\nSpecific encapsulated\
            \ business errors for current operation\n\n - 100: OrderItem with 'add'\
            \ action but serviceSpecification id missing\n   \n - 101: OrderItem with\
            \ 'change'/'noChange'/'remove' but service id missing\n   \n - 102: OrderItem\
            \ with 'add' action - serviceSpecification id provided but not existing\n\
            \   \n - 103: OrderItem with 'add' action but service id already existing\
            \ in the inventory\n   \n - 104: A customer for existing service(s) is\
            \ provided but he did not exist\n   \n - 105: OrderItem with 'change'/'noChange'/'remove'\
            \ - Service id provided but it is not existing in the inventory\n   \n\
            \ - 106: [Not managed for current Relese] Issue with lcpCloudRegionId\
            \  and tenantId provided\n   "
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        500:
          description: "Internal Server Error\n\nList of supported error codes:\n\
            - 1: Internal error"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        503:
          description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
            \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
            \ retry later !"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
    get:
      tags:
      - "ServiceOrder"
      operationId: "serviceOrderFind"
      summary: "List service orders"
      description: "Retrieve and list service order entities according to given criteria.\n\
        Only a predefined set of attribute is proposed.\nAttribute selection could\
        \ be described in the fields attribute.\n\nSpecific business errors for current\
        \ operation will be encapsulated in\n\nHTTP Response 422 Unprocessable entity\n"
      deprecated: false
      parameters:
      - name: "externalId"
        required: false
        in: "query"
        description: ""
        type: "string"
      - name: "state"
        required: false
        in: "query"
        description: "state of the order(s) to be retrieved"
        type: "string"
      - name: "description"
        required: false
        in: "query"
        description: ""
        type: "string"
      - name: "orderDate.gt"
        required: false
        in: "query"
        description: "order date greather than"
        type: "string"
      - name: "orderDate.lt"
        required: false
        in: "query"
        description: "order date lower than"
        type: "string"
      - name: "fields"
        required: false
        in: "query"
        description: "this attribute could be used to filter retrieved attribute(s)\
          \ and/or sort SO."
        type: "string"
      - name: "offset"
        required: false
        in: "query"
        description: "The index of the first element to retrieve. Zero is the first\
          \ element of the collection."
        type: "integer"
        format: "int32"
      - name: "limit"
        required: false
        in: "query"
        description: "The maximum number of elements to retrieve (it can be greater\
          \ than the actual available number of items)."
        type: "integer"
        format: "int32"
      responses:
        200:
          description: "Success"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ServiceOrder"
          headers:
            X-Total-Count:
              description: ""
              type: "integer"
              format: "int32"
            X-Result-Count:
              description: ""
              type: "integer"
              format: "int32"
        400:
          description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
            \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
            \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
            \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
            \ parameter value"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        401:
          description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
            \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        403:
          description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
            \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
            \ requests"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        404:
          description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
            \ not found"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        422:
          description: "Unprocessable entity\n\nFunctional error"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        500:
          description: "Internal Server Error\n\nList of supported error codes:\n\
            - 1: Internal error"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        503:
          description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
            \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
            \ retry later !"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
  /serviceOrder/{id}:
    get:
      tags:
      - "ServiceOrder"
      operationId: "serviceOrderGet"
      summary: "Retrieve a service order"
      description: "This operation retrieves a service order entity. \nAttribute selection\
        \ is enabled for all first level attributes.\n\nSpecific business errors for\
        \ current operation will be encapsulated in\n\nHTTP Response 422 Unprocessable\
        \ entity\n"
      deprecated: false
      parameters:
      - name: "id"
        in: "path"
        required: true
        type: "string"
        description: ""
      - name: "fields"
        required: false
        in: "query"
        description: "Attribute selection"
        type: "string"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/ServiceOrder"
        400:
          description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
            \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
            \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
            \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
            \ parameter value"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        401:
          description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
            \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        403:
          description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
            \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
            \ requests"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        404:
          description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
            \ not found"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        422:
          description: "Unprocessable entity\n\nFunctional error"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        500:
          description: "Internal Server Error\n\nList of supported error codes:\n\
            - 1: Internal error"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
        503:
          description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
            \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
            \ retry later !"
          schema:
            $ref: "#/definitions/ErrorRepresentation"
definitions:
  ActionType:
    description: "Action type to be describer on the order item.\nmodify is not managed\
      \ in Beijing release"
    type: "string"
    enum:
    - "add"
    - "modify"
    - "delete"
    - "noChange"
  StateType:
    description: "List of possible state for the order and the orderItem."
    type: "string"
    enum:
    - "acknowledged"
    - "rejected"
    - "pending"
    - "held"
    - "inProgress"
    - "cancelled"
    - "completed"
    - "failed"
    - "partial"
  RelationshipType:
    description: "Relationship type;\nOnly reliesOn is managed in Beijing release."
    type: "string"
    enum:
    - "reliesOn"
  ErrorRepresentation:
    description: "Representation of an error."
    required:
    - "code"
    - "reason"
    type: "object"
    properties:
      code:
        description: "Application related code (as defined in the API or from a common\
          \ list)"
        type: "integer"
        format: "int32"
      reason:
        description: "Text that explains the reason for error. This can be shown to\
          \ a client user."
        type: "string"
      message:
        description: "Text that provide more details and corrective actions related\
          \ to the error. This can be shown to a client user"
        type: "string"
      status:
        description: "http error code extension like 400-2"
        type: "string"
      referenceError:
        description: "url pointing to documentation describing the error"
        type: "string"
      '@type':
        description: "The class type of a REST resource"
        type: "string"
      '@schemaLocation':
        description: "it provides a link to the schema describing a REST resource"
        type: "string"
  ServiceRelationship:
    description: "Linked Services to the one instantiate\nnbi component used this\
      \ relationship to sort request to ONAP."
    required:
    - "type"
    - "service"
    type: "object"
    properties:
      type:
        $ref: "#/definitions/RelationshipType"
      service:
        $ref: "#/definitions/Service"
  ServiceRef:
    description: "Service references"
    required:
    - "id"
    type: "object"
    properties:
      id:
        description: "Unique identifier of the service"
        type: "string"
      href:
        description: "Reference of the service"
        type: "string"
  ServiceCharacteristic:
    description: "ServiceCharacteristic"
    required:
    - "name"
    type: "object"
    properties:
      name:
        description: "Name of characteristic"
        type: "string"
      valueType:
        description: ""
        type: "string"
      value:
        $ref: "#/definitions/Value"
  RelatedParty:
    description: "A related party defines party which are involved in this order and\
      \ the role they are playing.\nfor Beijing release:\nWith 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:\no\tIt 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.\no\tIf no relatedParty are provided the service\
      \ will be affected to ‘generic’ customer (dummy customer) – we assume this ‘\
      generic’ customer always exists."
    required:
    - "id"
    - "role"
    type: "object"
    properties:
      id:
        description: "Unique identifier of a related party"
        type: "string"
      href:
        description: "An hyperlink to the party - not used in Beijnig release"
        type: "string"
      role:
        description: "The role of the related party (e.g. Owner, requester, fullfiller\
          \ etc).\nONLY 'ONAPcustomer' is considered"
        type: "string"
      name:
        description: "Name of the related party"
        type: "string"
      '@referredType':
        description: ""
        type: "string"
  ServiceSpecificationRef:
    description: "The service specification (these attributes are fetched from the\
      \ catalogue)."
    required:
    - "id"
    type: "object"
    properties:
      id:
        description: "Unique identifier of the service specification\nThis information\
          \ will be used to retrieve SDC information + mapped to SO ModelNameVersionIdin\
          \ the request."
        type: "string"
      href:
        description: "Reference of the service specification\nNot used in Beijing\
          \ release."
        type: "string"
      name:
        description: "Name of the service specification\nNot used in Beijing release"
        type: "string"
      version:
        description: "Version of the service Specification\nNot used in Beijing release"
        type: "string"
      targetServiceSchema:
        $ref: "#/definitions/TargetServiceSchema"
      '@type':
        description: "Not used in Beijing release"
        type: "string"
      '@schemaLocation':
        description: "Not used in Beijing release"
        type: "string"
      '@baseType':
        description: "Not used in Beijing release"
        type: "string"
  Service:
    description: "Service (to be added, modified, deleted) description"
    required:
    - "id"
    type: "object"
    properties:
      id:
        description: "Identifier of a service instance.\nIt must be valued if orderItem\
          \ action is 'delete' and corresponds to a AAI service.id"
        type: "string"
      href:
        description: "Reference to the Service (useful for delete or modify command).\n\
          Not managed in Beijing release."
        type: "string"
      name:
        description: "Name of the service - When orderItem action is 'add' this name\
          \ will be used in ONAP/SO request as InstaceName."
        type: "string"
      serviceState:
        description: "The lifecycle state of the service requested;\nNot managed in\
          \ Beijing release."
        type: "string"
      '@type':
        description: "To define the service type\nNot managed in Beijing Release"
        type: "string"
      '@schemaLocation':
        description: "The URL to get the resource schema.\nNot managed in Beijing\
          \ Release"
        type: "string"
      serviceCharacteristic:
        type: "array"
        items:
          $ref: "#/definitions/ServiceCharacteristic"
      serviceRelationship:
        type: "array"
        items:
          $ref: "#/definitions/ServiceRelationship"
      relatedParty:
        type: "array"
        items:
          $ref: "#/definitions/RelatedParty"
      serviceSpecification:
        $ref: "#/definitions/ServiceSpecificationRef"
  OrderItemRelationship:
    description: "Linked order item to the one containing this attribute.\nnbi component\
      \ used this relationship to sort request to ONAP."
    required:
    - "type"
    - "id"
    type: "object"
    properties:
      type:
        $ref: "#/definitions/RelationshipType"
      id:
        description: "Unique identifier of an order item"
        type: "string"
  ServiceOrderItem:
    description: "An identified part of the order. A service order is decomposed into\
      \ one or more order items."
    required:
    - "id"
    - "service"
    type: "object"
    properties:
      id:
        description: "Identifier of the line item (generally it is a sequence number\
          \ 01, 02, 03, …)"
        type: "string"
      action:
        $ref: "#/definitions/ActionType"
      state:
        $ref: "#/definitions/StateType"
      '@type':
        description: "Used to extend the order item.\nnot used in Beijing relase"
        type: "string"
      '@schemaLocation':
        description: "not used in Beijing relase"
        type: "string"
      '@baseType':
        description: "not used in Beijing relase"
        type: "string"
      orderItemRelationship:
        type: "array"
        items:
          $ref: "#/definitions/OrderItemRelationship"
      service:
        $ref: "#/definitions/Service"
  ServiceOrder:
    description: "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"
    required:
    - "id"
    type: "object"
    properties:
      id:
        description: "ID created on repository side"
        type: "string"
      href:
        description: "Hyperlink to access the order"
        type: "string"
      externalId:
        description: "ID given by the consumer and only understandable by him (to\
          \ facilitate his searches)"
        type: "string"
      priority:
        description: "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)"
        type: "string"
      description:
        description: "A free-text description of the service order"
        type: "string"
      category:
        description: "Used to categorize the order that can be useful for the OM system\
          \ (e.g. “broadband”, “TVOption”, ...)"
        type: "string"
      state:
        $ref: "#/definitions/StateType"
      orderDate:
        description: ""
        type: "string"
        format: "date-time"
      completionDateTime:
        description: "Date when the order was completed"
        type: "string"
        format: "date-time"
      requestedStartDate:
        description: "Order start date wished by the requestor"
        type: "string"
        format: "date-time"
      requestedCompletionDate:
        description: "Requested delivery date from the requestor perspective"
        type: "string"
        format: "date-time"
      expectedCompletionDate:
        description: ""
        type: "string"
        format: "date-time"
      startDate:
        description: "Date when the order was started for processing"
        type: "string"
        format: "date-time"
      '@baseType':
        description: ""
        type: "string"
      '@type':
        description: ""
        type: "string"
      '@schemaLocation':
        description: ""
        type: "string"
      relatedParty:
        type: "array"
        items:
          $ref: "#/definitions/RelatedParty"
      orderRelationship:
        type: "array"
        items:
          $ref: "#/definitions/OrderRelationship"
      orderItem:
        type: "array"
        items:
          $ref: "#/definitions/ServiceOrderItem"
  OrderRelationship:
    description: "Linked order to the one containing this attribute.\nThis relationship\
      \ is not used to sort ONAP request."
    required:
    - "id"
    type: "object"
    properties:
      type:
        description: "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)"
        type: "string"
      id:
        description: "The id of the related order"
        type: "string"
      href:
        description: "A hyperlink to the related order"
        type: "string"
      '@referredType':
        description: "Type of the referred order."
        type: "string"
  TargetServiceSchema:
    description: "Target to the schema describing the service spec resource"
    required:
    - "@type"
    - "@schemaLocation"
    type: "object"
    properties:
      '@type':
        description: "Indicates the (class) type of resource."
        type: "string"
      '@schemaLocation':
        description: "This field provided a link to the schema describing this REST\
          \ resource."
        type: "string"
  Value:
    description: "Value is a descriptive structure for service characteristic;\nFor\
      \ Beijing we only manage 'basic' attribute - the serviceCharacteristicValue\
      \ must be used."
    type: "object"
    properties:
      '@type':
        description: "Indicates the (class) type of resource.\nNot used in Beijing\
          \ Release"
        type: "string"
      '@schemaLocation':
        description: "This field provided a link to the schema describing this REST\
          \ resource.\nNot used in Beijing Release"
        type: "string"
      serviceCharacteristicValue:
        description: "Value of the characteristic.\nThis attribute must be used in\
          \ Beijing Release to provide characteristic value."
        type: "string"
  CreateServiceOrderItem:
    description: "This structure is used in the operation POST for a serviceOrder\
      \ request to describe an item.\nAttribute description is not accurate and should\
      \ be find in the serviceOrderItem class."
    required:
    - "id"
    - "service"
    type: "object"
    properties:
      id:
        description: "Identifier of the line item (generally it is a sequence number\
          \ 01, 02, 03, …)"
        type: "string"
      action:
        $ref: "#/definitions/ActionType"
      '@type':
        description: "Indicates the type of resource."
        type: "string"
      '@schemaLocation':
        description: "A link to the schema describing this REST resource"
        type: "string"
      '@baseType':
        description: "Indicates the base type of the resource."
        type: "string"
      orderItemRelationship:
        type: "array"
        items:
          $ref: "#/definitions/OrderItemRelationship"
      service:
        $ref: "#/definitions/Service"
  CreateServiceOrder:
    description: "This structure is used in the operation POST for a serviceOrder\
      \ request.\nAttribute description is not accurate and should be find in the\
      \ serviceOrder class."
    type: "object"
    properties:
      externalId:
        description: "ID given by the consumer and only understandable by him (to\
          \ facilitate his searches)"
        type: "string"
      priority:
        description: "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)"
        type: "string"
      description:
        description: "A free-text description of the service order"
        type: "string"
      category:
        description: "Used to categorize the order that can be useful for the OM system\
          \ (e.g. “broadband”, “TVOption”, ...)"
        type: "string"
      requestedStartDate:
        description: "Order start date wished by the requestor"
        type: "string"
        format: "date-time"
      requestedCompletionDate:
        description: "Requested delivery date from the requestor perspective"
        type: "string"
        format: "date-time"
      '@baseType':
        description: ""
        type: "string"
      '@type':
        description: ""
        type: "string"
      '@schemaLocation':
        description: ""
        type: "string"
      relatedParty:
        type: "array"
        items:
          $ref: "#/definitions/RelatedParty"
      orderRelationship:
        type: "array"
        items:
          $ref: "#/definitions/OrderRelationship"
      orderItem:
        type: "array"
        items:
          $ref: "#/definitions/CreateServiceOrderItem"
  Hub:
    description: "An HUB resource is used by client side to subscribe to notification.\n\
      Not managed in the Beijing release."
    discriminator: "id"
    required:
    - "callback"
    type: "object"
    properties:
      id:
        description: ""
        type: "string"
      query:
        description: ""
        type: "string"
      callback:
        description: ""
        type: "string"