TM Forum serviceOrder API

openapi: 3.2.0
info:
  title: ServiceOrdering Service Order API
  description: "## TMF API Reference : TMF 641 - Service Ordering Management\n\n Version 4.1 \n\nThe Service Order API provides a standardized mechanism for managing Service Order, a type of order which can be used to place an order between internal Customer Order management system to service order management system or between a service provider and a partner and vice versa.\n\n### Service Order resource\nA service order will describe a list of service order items.  A service order item references an action on an existing  or  future  service.  By  service  we  designed  Customer Facing  Service  (CFS)  as  well  as  Resource Facing Service (RFS).\nFrom a component perspective, a service order should be available\n- from a Service Orchestration Component (and it could mix CFS and RFS)\n- from an Infrastructure Control & Management component (and it would have only RFS)\n\n### TMF641 performs the following operations on service order resource :\n- Retrieval of a service order or a collection of service orders depending on filter criteria\n- Partial update of a service order (including updating rules)\n- Creation of a service order (including default values and creation rules)\n- Deletion of service order (for administration purposes)\n- Notification of events on Service order\n\n**Cancel Service Order resource**\n\nThis resource is used to request a service order cancellation.\n\n**TMF641 provides following operations on Cancel Service Order resource :**\n\n- Retrieval of a cancel service order or a collection of cancel service orders \n- Creation of a cancel service order \n- Notification of events on cancel service order.\n\nCopyright © TM Forum 2020. All Rights Reserved"
  version: 4.1.0
servers:
- url: https://serverRoot/tmf-api/serviceOrdering/v4
tags:
- name: serviceOrder
paths:
  /serviceOrder:
    get:
      operationId: listServiceOrder
      summary: List or find ServiceOrder objects
      description: This operation list or find ServiceOrder entities
      tags:
      - serviceOrder
      parameters:
      - name: fields
        description: Comma-separated properties to be provided in response
        required: false
        in: query
        schema:
          type: string
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceOrder'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createServiceOrder
      summary: Creates a ServiceOrder
      description: This operation creates a ServiceOrder entity.
      tags:
      - serviceOrder
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceOrder'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceOrder_Create'
        description: The ServiceOrder to be created
        required: true
  /serviceOrder/{id}:
    get:
      operationId: retrieveServiceOrder
      summary: Retrieves a ServiceOrder by ID
      description: This operation retrieves a ServiceOrder entity. Attribute selection is enabled for all first level attributes.
      tags:
      - serviceOrder
      parameters:
      - name: id
        description: Identifier of the ServiceOrder
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Comma-separated properties to provide in response
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceOrder'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchServiceOrder
      summary: Updates partially a ServiceOrder
      description: This operation updates partially a ServiceOrder entity.
      tags:
      - serviceOrder
      parameters:
      - name: id
        description: Identifier of the ServiceOrder
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceOrder'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceOrder_Update'
        description: The ServiceOrder to be updated
        required: true
    delete:
      operationId: deleteServiceOrder
      summary: Deletes a ServiceOrder
      description: This operation deletes a ServiceOrder entity.
      tags:
      - serviceOrder
      parameters:
      - name: id
        description: Identifier of the ServiceOrder
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ServiceOrderItem:
      type: object
      required:
      - id
      - action
      - service
      properties:
        id:
          type: string
          description: Identifier of the individual line item
        quantity:
          type: integer
          description: Quantity ordered
        action:
          $ref: '#/components/schemas/OrderItemActionType'
          description: 'The action to be carried out on the Service. Can be: add, modify, delete, noChange'
        appointment:
          $ref: '#/components/schemas/AppointmentRef'
          description: An appointment that was set up with a related party for this order item
        errorMessage:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItemErrorMessage'
          description: the error(s) cause an order item status change
        service:
          $ref: '#/components/schemas/ServiceRefOrValue'
          description: The Service to be acted on by the order item
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItem'
          description: A list of order items embedded to this order item
        serviceOrderItemRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItemRelationship'
          description: A list of order items related to this order item
        state:
          $ref: '#/components/schemas/ServiceOrderItemStateType'
          description: 'State of the order item: described in the state machine diagram. This is the requested state.'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    Error:
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
      type: object
      required:
      - code
      - reason
      properties:
        code:
          type: string
          description: Application relevant detail, defined in the API or a common list.
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.
        status:
          type: string
          description: HTTP Error code extension
        referenceError:
          type: string
          format: uri
          description: URI of documentation describing the error.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name.
    Feature:
      type: object
      description: Configuration feature.
      required:
      - featureCharacteristic
      - name
      properties:
        id:
          type: string
          description: Unique identifier of the feature.
        isBundle:
          type: boolean
          description: True if this is a feature group. Default is false.
        isEnabled:
          type: boolean
          description: True if this feature is enabled. Default is true.
        name:
          type: string
          description: This is the name for the feature.
        constraint:
          type: array
          items:
            $ref: '#/components/schemas/ConstraintRef'
          description: This is a list of feature constraints.
        featureCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
          minItems: 1
          description: This is a list of Characteristics for a particular feature.
        featureRelationship:
          type: array
          items:
            $ref: '#/components/schemas/FeatureRelationship'
    RelatedPlaceRefOrValue:
      type: object
      description: Related Entity reference. A related place defines a place described by reference or by value linked to a specific entity. The polymorphic attributes @type, @schemaLocation & @referredType are related to the place entity and not the RelatedPlaceRefOrValue class itself
      required:
      - role
      properties:
        id:
          type: string
          description: Unique identifier of the place
        href:
          type: string
          description: Unique reference of the place
        name:
          type: string
          description: A user-friendly name for the place, such as [Paris Store], [London Store], [Main Home]
        role:
          type: string
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    ServiceOrder_Create:
      type: object
      description: '

        Skipped properties: id,href,orderDate,completionDate,expectedCompletionDate,startDate,state,jeopardyAlert,errorMessage,milestone'
      required:
      - serviceOrderItem
      properties:
        cancellationDate:
          type: string
          format: date-time
          description: 'Date when the order is cancelled. This is used when order is cancelled. '
        cancellationReason:
          type: string
          description: 'Reason why the order is cancelled. This is used when order is cancelled. '
        category:
          type: string
          description: 'Used to categorize the order, useful for the OM system, such as: Broadband, TVOption'
        description:
          type: string
          description: A free-text description of the service order
        externalId:
          type: string
          description: ID given by the consumer to facilitate searches
        notificationContact:
          type: string
          description: Contact attached to the order to send back information regarding this order
        priority:
          type: string
          description: Can be used by consumers to prioritize orders in a Service Order Management system
        requestedCompletionDate:
          type: string
          format: date-time
          description: Requested delivery date from the requestors perspective
        requestedStartDate:
          type: string
          format: date-time
          description: Order start date wished by the requestor
        externalReference:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
          description: Extra-information about the order; e.g. useful to add extra delivery information that could be useful for a human process
        orderRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderRelationship'
          description: A list of service orders related to this order (e.g. prerequisite, dependent on)
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: A list of parties which are involved in this order and the role they are playing
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItem'
          minItems: 1
          description: A list of service order items to be processed by this order
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    CharacteristicRelationship:
      type: object
      description: Another Characteristic that is related to the current Characteristic;
      properties:
        id:
          type: string
          description: Unique identifier of the characteristic
        href:
          type: string
          format: uri
          description: Hyperlink reference
        relationshipType:
          type: string
          description: The type of relationship
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format
    ServiceOrderMilestone:
      type: object
      description: ServiceOrderMilestone represents an action or event marking a significant change or stage in processing of a service order.
      properties:
        id:
          type: string
          description: identifier of the Milestone
        description:
          type: string
          description: free-text description of the Milestone
        message:
          type: string
          description: A string represents the message of the milestone
        milestoneDate:
          type: string
          format: date-time
          description: A date time( DateTime). The date that the milestone happens
        name:
          type: string
          description: A string used to give a name to the milestone
        status:
          type: string
          description: The milestone status
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItemRef'
          description: A list of order item references corresponded to this milestone
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    ServiceRelationship:
      type: object
      required:
      - relationshipType
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        relationshipType:
          type: string
        service:
          $ref: '#/components/schemas/ServiceRefOrValue'
        serviceRelationshipCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    Note:
      type: object
      description: Extra information about a given entity
      required:
      - text
      properties:
        id:
          example:
          - afa9-3d90aaa8da0f
          type: string
          description: Identifier of the note within its containing entity
        author:
          example:
          - Mr. N. Bene
          type: string
          description: Author of the note
        date:
          example:
          - '2020-11-20T08:00:00Z'
          type: string
          format: date-time
          description: Date of the note
        text:
          example:
          - This is important
          type: string
          description: Text of the note
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    ServiceSpecificationRef:
      type: object
      description: 'Service specification reference: ServiceSpecification(s) required to realize a ProductSpecification.'
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        version:
          type: string
          description: Service specification version
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    ServiceOrderRelationship:
      type: object
      description: Linked service order to the one containing this attribute
      required:
      - id
      - relationshipType
      properties:
        id:
          type: string
          description: The id of the related order
        href:
          type: string
          description: A hyperlink to the related order
        relationshipType:
          type: string
          description: 'The type of related order, such as: [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)'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The entity type of the related order
    ServiceStateType:
      type: string
      description: Valid values for the lifecycle state of the service
      enum:
      - feasibilityChecked
      - designed
      - reserved
      - inactive
      - active
      - terminated
    ServiceOrder:
      type: object
      properties:
        id:
          type: string
          description: ID created on repository side
        href:
          type: string
          description: Hyperlink to access the order
        cancellationDate:
          type: string
          format: date-time
          description: 'Date when the order is cancelled. This is used when order is cancelled. '
        cancellationReason:
          type: string
          description: 'Reason why the order is cancelled. This is used when order is cancelled. '
        category:
          type: string
          description: 'Used to categorize the order, useful for the OM system, such as: Broadband, TVOption'
        completionDate:
          type: string
          format: date-time
          description: Effective delivery date amended by the provider
        description:
          type: string
          description: A free-text description of the service order
        expectedCompletionDate:
          type: string
          format: date-time
          description: Expected delivery date amended by the provider
        externalId:
          type: string
          description: ID given by the consumer to facilitate searches
        notificationContact:
          type: string
          description: Contact attached to the order to send back information regarding this order
        orderDate:
          type: string
          format: date-time
        priority:
          type: string
          description: Can be used by consumers to prioritize orders in a Service Order Management system
        requestedCompletionDate:
          type: string
          format: date-time
          description: Requested delivery date from the requestors perspective
        requestedStartDate:
          type: string
          format: date-time
          description: Order start date wished by the requestor
        startDate:
          type: string
          format: date-time
          description: Date when the order was started for processing
        errorMessage:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderErrorMessage'
          description: the error(s) cause an order status change
        externalReference:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        jeopardyAlert:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderJeopardyAlert'
          description: A list of jeopardy alerts related to this order
        milestone:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderMilestone'
          description: A list of milestones related to this order
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
          description: Extra-information about the order; e.g. useful to add extra delivery information that could be useful for a human process
        orderRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderRelationship'
          description: A list of service orders related to this order (e.g. prerequisite, dependent on)
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: A list of parties which are involved in this order and the role they are playing
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItem'
          description: A list of service order items to be processed by this order
        state:
          $ref: '#/components/schemas/ServiceOrderStateType'
          description: 'State of the order: described in the state-machine diagram'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tm-forum/refs/heads/main/openapi/tm-forum-serviceorder-api-openapi.yml