MEF Service Order API

openapi: 3.2.0
info:
  title: Mef Service Order API
  version: '1.0'
  description: 'Operations tagged Service Order across 3 of this provider''s published API definitions: mef-lso-allegro-service-ordering-management-openapi.yml, mef-lso-interlude-service-ordering-management-openapi.yml, mef-lso-legato-service-ordering-management-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{serverBase}/mefApi/allegro/serviceOrderingManagement/v1/
  variables:
    serverBase:
      description: The base of SOF's URL.
      default: mplify.net
- url: https://{serverBase}/mefApi/interlude/serviceOrderingManagement/v1/
  variables:
    serverBase:
      description: The base of SOF's URL.
      default: mplify.net
- url: https://{serverBase}/mefApi/legato/serviceOrderingManagement/v6/
  variables:
    serverBase:
      description: The base of SOF's URL.
      default: mplify.net
tags:
- name: Service Order
  description: Operations for Service Order Resource
paths:
  /serviceOrder:
    get:
      tags:
      - Service Order
      summary: List or find ServiceOrder objects
      description: This operation retrieves list of ServiceOrder entities.
      operationId: listServiceOrder
      parameters:
      - name: state
        in: query
        description: State of the Service Order
        required: false
        schema:
          $ref: '#/components/schemas/ServiceOrderStateType'
      - name: orderDate.gt
        in: query
        description: Date when the order was created greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: orderDate.lt
        in: query
        description: Date when the order was created lesser than
        required: false
        schema:
          type: string
          format: date-time
      - name: completionDate.gt
        in: query
        description: Effective completion date greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: completionDate.lt
        in: query
        description: Effective completion date lesser than
        required: false
        schema:
          type: string
          format: date-time
      - name: expectedCompletionDate.gt
        in: query
        description: Expected delivery date greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: expectedCompletionDate.lt
        in: query
        description: Expected delivery date lesser than
        required: false
        schema:
          type: string
          format: date-time
      - name: startDate.gt
        in: query
        description: Date when the order was started for processing
        required: false
        schema:
          type: string
          format: date-time
      - name: startDate.lt
        in: query
        description: Date when the order was started for processing
        required: false
        schema:
          type: string
          format: date-time
      - name: offset
        in: query
        description: Requested index for start of item to be provided in response requested by the client. Note that the index starts with "0".
        required: false
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Requested number of items to be provided in response requested by client
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)
          headers:
            X-Pagination-Throttled:
              description: 'Used to indicate that result page was throttled to maximum possible size  and there are additional results that can be fetched

                '
              schema:
                type: boolean
            X-Total-Count:
              description: 'The total number of matching items. E.g. if there are 50 matching items in total, but the request has offset=10 and limit=10, then the X-Total-Count is 50.

                '
              schema:
                type: integer
            X-Result-Count:
              description: The number of items included in the response
              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/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '422':
          description: Unprocessable entity due to business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
    post:
      tags:
      - Service Order
      summary: Creates a ServiceOrder
      description: This operation creates a ServiceOrder entity.
      operationId: createServiceOrder
      requestBody:
        description: The ServiceOrder to be created
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceOrder_Create'
        required: true
      responses:
        '201':
          description: Created (https://tools.ietf.org/html/rfc7231#section-6.3.2)
          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/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '422':
          description: Unprocessable entity due to the business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
    servers:
    - url: https://{serverBase}/mefApi/allegro/serviceOrderingManagement/v1/
      variables:
        serverBase:
          description: The base of SOF's URL.
          default: mplify.net
  /serviceOrder/{id}:
    get:
      tags:
      - Service Order
      summary: Retrieves a ServiceOrder by ID
      description: This operation retrieves a ServiceOrder entity.
      operationId: retrieveServiceOrder
      parameters:
      - name: id
        in: path
        description: Identifier of the ServiceOrder
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)
          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/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
    servers:
    - url: https://{serverBase}/mefApi/allegro/serviceOrderingManagement/v1/
      variables:
        serverBase:
          description: The base of SOF's URL.
          default: mplify.net
components:
  schemas:
    TimeUnit:
      description: 'Represents a unit of time.

        '
      type: string
      enum:
      - seconds
      - minutes
      - businessHours
      - calendarHours
      - businessDays
      - calendarDays
      - months
      - years
    ServiceOrderItemRelationship:
      description: 'Specifies the type (nature) of the relationship to the related

        Service. The nature of required relationships varies for Services of

        different types. For example, a UNI or ENNI Service may not have any

        relationships, but an E-Line may have two mandatory

        relationships (related to the UNI on one end and the ENNI on the

        other). More complex Services such as multipoint IP or Firewall

        Services may have more complex relationships. As a result, the

        allowed and mandatory `relationshipType` values are defined in the

        Service Specification.

        Related item can be both from within the same Service Order or from

        other one. When referencing item from within the same Service Order,

        the `orderItem.serviceOrderId` and `orderItem.serviceOrderHref` MUST

        be empty.

        '
      type: object
      properties:
        orderItem:
          description: A reference to a Service Order Item
          $ref: '#/components/schemas/ServiceOrderItemRef'
        relationshipType:
          description: Specifies the nature of the relationship to the related Service Order Item. A string that is one of the relationship types specified in the Service Specification.
          type: string
      required:
      - orderItem
      - relationshipType
    RelatedPlaceRefOrQuery:
      description: Allows pointing to a place by referring to a GeographicAddress, GeographicSite, or providing GeographicAddress by value. It also provides additional information like the `role` the place plays for given Product and `contact` needed access to this place.
      type: object
      properties:
        place:
          $ref: '#/components/schemas/PlaceRefOrQuery'
        role:
          description: Role of this place. The values that can be specified here are described by Product Specification (e.g. "INSTALL_LOCATION").
          type: string
        contact:
          description: The person to call to get access to this place in case such access is required to complete the evaluation of this POQ Item.
          type: array
          items:
            $ref: '#/components/schemas/ContactInformation'
      required:
      - place
      - role
    OrderItemCoordinationDependencyType:
      description: 'Possible values of the Order Item Coordination Dependency


        | OrderItemCoordinationDependencyType | Description                                                                                        |

        |-------------------------------------|----------------------------------------------------------------------------------------------------|

        | startToStart                        | Work on the Specified Order Item can only be started after the Coordinated Order Items are started |

        | startToFinish                       | The Coordinated Order Items must complete before work on the Specified Order Item begins           |

        | finishToStart                       | Work on the Related Order Items begins after the completion of the Specified Order Item            |

        | finishToFinish                      | Work on the Related Order Items completes at the same time as the Specified Order Item             |

        '
      type: string
      enum:
      - startToStart
      - startToFinish
      - finishToStart
      - finishToFinish
    ContactInformation:
      description: Contact data for a person or organization that is involved in the product offering qualification. In a given context it is always specified by the SOF (e.g. SOF Contact Information) or by the BUS.
      type: object
      properties:
        number:
          description: Phone number
          type: string
        emailAddress:
          description: Email address
          type: string
        postalAddress:
          description: Identifies the postal address of the person or office to be contacted.
          $ref: '#/components/schemas/FieldedAddressRepresentation'
        organization:
          description: The organization or company that the contact belongs to
          type: string
        name:
          description: Name of the contact
          type: string
        numberExtension:
          description: Phone number extension
          type: string
      required:
      - emailAddress
      - name
      - number
    PlaceRefOrQuery:
      description: A place described by reference to a Geographic Address, Geographic Site or by Geographic Address Representations.
      type: object
      discriminator:
        propertyName: '@type'
        mapping:
          GeographicAddressRef: '#/components/schemas/GeographicAddressRef'
          GeographicSiteRef: '#/components/schemas/GeographicSiteRef'
          GeographicAddress_Query: '#/components/schemas/GeographicAddress_Query'
      oneOf:
      - $ref: '#/components/schemas/GeographicAddressRef'
      - $ref: '#/components/schemas/GeographicSiteRef'
      - $ref: '#/components/schemas/GeographicAddress_Query'
    GeographicAddressRef:
      description: 'A reference to a Geographic Address resource available through Address Validation API.

        '
      type: object
      properties:
        href:
          description: 'Hyperlink to the referenced Address. Hyperlink MAY be used by the SOF in responses. Hyperlink MUST be ignored by the SOF in case it is provided by the BUS in a request.

            '
          type: string
        id:
          description: Identifier of the referenced Geographic Address. This identifier is assigned during a successful address validation request (Geographic Address Management API)
          type: string
        '@type':
          description: Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
          - GeographicAddressRef
      required:
      - '@type'
      - id
    Duration:
      description: A Duration in a given unit of time e.g. 3 hours, or 5 days.
      type: object
      properties:
        amount:
          description: Duration (number of seconds, minutes, hours, etc.)
          type: integer
          minimum: 0
        units:
          description: Time unit enumerated
          $ref: '#/components/schemas/TimeUnit'
      required:
      - amount
      - units
    TerminationError:
      description: This indicates an error that caused an Item to be terminated. The code and propertyPath should be used like in Error422.
      type: object
      properties:
        code:
          description: "One of the following error codes:\n  - missingProperty: The property the SOF has expected is not present in the payload\n  - invalidValue: The property has an incorrect value\n  - invalidFormat: The property value does not comply with the expected value format\n  - referenceNotFound: The object referenced by the property cannot be identified in the SOF system\n  - unexpectedProperty: Additional property, not expected by the SOF has been provided\n  - tooManyRecords: the number of records to be provided in the response exceeds the SOF's threshold.\n  - otherIssue: Other problem was identified (detailed information provided in a reason)\n"
          $ref: '#/components/schemas/Error422Code'
        propertyPath:
          description: 'A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used.

            Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901).

            '
          type: string
        value:
          description: Text to describe the reason of the termination.
          type: string
    Error403Code:
      description: 'This code indicates that the server understood

        the request but refuses to authorize it because

        of one of the following error codes:

        - accessDenied: Access denied

        - forbiddenRequester: Forbidden requester

        - tooManyUsers: Too many users'
      type: string
      enum:
      - accessDenied
      - forbiddenRequester
      - tooManyUsers
    MefServiceConfiguration:
      description: MefServiceConfiguration is used as an extension point for MEF specific service payload. The `@type` attribute is used as a discriminator
      type: object
      properties:
        '@type':
          description: The value of the "$id" as defined in the JSON schema of the service.
          type: string
      required:
      - '@type'
      discriminator:
        propertyName: '@type'
    ServiceRef:
      description: Reference to a Service instance.
      type: object
      properties:
        href:
          description: Hyperlink reference to Service
          type: string
        id:
          description: unique identifier of Service
          type: string
      required:
      - id
    LabelRepresentation:
      description: A unique identifier controlled by a generally accepted independent administrative authority that specifies a fixed geographical location.
      type: object
      properties:
        label:
          description: The unique reference to a Geographic Address assigned by the Administrative Authority.
          type: string
        administrativeAuthority:
          description: The organization or standard from the organization that administers this Geographic Address Label ensuring it is unique within the Administrative Authority.
          type: string
        language:
          description: The language in which the label is expressed. Based on ISO 639:2023
          type: string
          minLength: 2
          maxLength: 2
      required:
      - administrativeAuthority
      - label
    BusSofType:
      description: An enumeration with BUS and SOF values.
      type: string
      enum:
      - bus
      - sof
    FieldedAddressRepresentation:
      description: A type of Address that has a discrete field and value for each type of boundary or identifier down to the lowest level of detail. For example "street number" is one field, "street name" is another field, etc.
      type: object
      properties:
        streetNr:
          description: Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses.
          type: string
        streetNrSuffix:
          description: The first street number suffix (in a street number range) or the suffix for the street number if there is no range
          type: string
        streetNrLast:
          description: Last number in a range of street numbers allocated to an Address
          type: string
        streetNrLastSuffix:
          description: Last street number suffix for a ranged Address
          type: string
        streetPreDirection:
          description: The direction of the street that appears before the Street Name
          type: string
        streetName:
          description: Name of the street or other street type
          type: string
        streetType:
          description: The type of street (e.g., alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf)
          type: string
        streetPostDirection:
          description: A modifier denoting a relative direction that appears after the Street Name.
          type: string
        poBox:
          description: Number identifying a specific location in a post office.
          type: string
        locality:
          description: An area of defined or undefined boundaries within a local authority or other legislatively defined area.
          type: string
        city:
          description: City in which the Address is located.
          type: string
        postcode:
          description: A descriptor for a postal delivery area used to speed and simplify the delivery of mail (also known as zip code)
          type: string
        postcodeExtension:
          description: 'The extension used on a postal code. Note: there are different use codes for this attribute depending upon the country.'
          type: string
        stateOrProvince:
          description: The State or Province in which the Address is located.
          type: string
        countryCode:
          description: Country in which the Address is located, defined using two characters as defined in ISO 3166
          type: string
          minLength: 2
          maxLength: 2
        subUnit:
          description: The Sub Unit represented as a list. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A
          type: array
          items:
            $ref: '#/components/schemas/SubUnit'
        buildingName:
          description: 'The well-known name of a building that is located at this Address (e.g., where there is one Address for a campus).

            '
          type: string
        privateStreetNumber:
          description: Street number on a private street within the Address.
          type: string
        privateStreetName:
          description: Private streets internal to a property (e.g., a university) may have internal names that are not recorded by the land title office.
          type: string
        language:
          description: The language in which the address is expressed. It MUST use the ISO 639:2023 two letter code 639:2023
          type: string
          minLength: 2
          maxLength: 2
    ServiceRelationship:
      description: A relationship to an existing Service. The requirements for usage for given Service are described in the Service Specification.
      type: object
      properties:
        relationshipType:
          description: 'Specifies the type (nature) of the relationship to the related

            Service. The nature of required relationships varies for Services of

            different types. For example, a UNI or ENNI Service may not have any

            relationships, but an Access E-Line may have two mandatory

            relationships (related to the UNI on one end and the ENNI on the

            other). More complex Services such as multipoint IP or Firewall

            Services may have more complex relationships. As a result, the

            allowed and mandatory `relationshipType` values are defined in the

            Service Specification.

            '
          type: string
        service:
          description: A reference to a Service
          $ref: '#/components/schemas/ServiceRef'
      required:
      - relationshipType
      - service
    ServiceOrder_Common:
      description: 'A Service Order is used to request operations on a Service instance. A

        Service Order groups one or more one Service Order Items - one per

        specific action on a Service instance. The Action associated with the

        Service Order Item describes the operation (add, modify, delete) to be

        applied on the specified Service instance.The Service Order Item and its

        associated Action can operate on both existing (modify, delete) as well

        as future (add) Service instance.The Service Order is triggered from the

        Business Application (BA) system in charge of the Service Order

        management to the Service Orchestration Function (SOF) system that will

        orchestrate the Service fulfillment.


        This type defines all attributes common to objects used in request and

        response.

        '
      type: object
      properties:
        coordinatedAction:
          description: The interval after the completion of one or more related Service Order Items that this Service Order Item can be started or completed
          type: array
          items:
            $ref: '#/components/schemas/OrderCoordinatedAction'
        description:
          description: A free-text description of the service order
          type: string
        externalId:
          description: ID given by the consumer to facilitate searches
          type: string
        note:
          description: Extra-information about the order; e.g. useful to add extra delivery information that could be useful for a human process
          type: array
          items:
            $ref: '#/components/schemas/Note_BusSof'
        orderRelationship:
          description: A list of service orders related to this order
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderRelationship'
        relatedContactInformation:
          description: 'Contact information of an individual or organization playing a role for this Service Order.

            For providing Notification Contact, `role=notificationContact` MUST be used.'
          type: array
          items:
            $ref: '#/components/schemas/RelatedContactInformation'
        requestedCompletionDate:
          description: Requested delivery date from the requestors perspective
          type: string
          format: date-time
        requestedStartDate:
          description: Order start date wished by the requestor
          type: string
          format: date-time
      required:
      - requestedCompletionDate
      - requestedStartDate
    ServiceOrderItem_Create:
      allOf:
      - $ref: '#/components/schemas/ServiceOrderItem_Common'
      - description: 'An identified part of the order. A service order is decomposed into one or more order items. This type is used in the request.

          '
        type: object
    ServiceOrderStateType:
      description: 'Possible values for the state of a Service Order


        | State        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

        | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

        | acknowledged | A `ServiceOrder` request has been received and has passed message and basic validations and a _Success Response_ has been sent.                                                                                                                                                                                                                                                                                                                                                                                                                       |

        | rejected     | This state indicates that: <br>- Invalid information is provided through the `ServiceOrder` / `ServiceOrderItem` request <br>- The request fails to meet validation rules for `Service` delivery (processing) <br>If one `ServiceOrderItem` is rejected, then the entire `ServiceOrder` request is rejected and a _Error Response_ is sent.                                                                                                                                                                                                           |

        | inProgress   | This state indicates that all `ServiceOrderItems` have successfully passed the validations checks and the scheduled `Service` delivery/processing has started. <br> The `ServiceOrder` will be in _`inProgress`_ state if _at least one_ `ServiceOrderItem` is in _`inProgress`_ state                                                                                                                                                                                                                                                                |

        | pending      | This state indicates that a `ServiceOrderItem` is currently in a waiting stage for an action/activity to be completed before the order-processing can progress further (this may happen also via non-API channel). <br> A _`pending`_ state can lead into automatic `failed` of an `ServiceOrderItem`, if no action is taken within the agreed timeframe.<br>The `ServiceOrder` will be in _`pending`_ state if _at least one_ `ServiceOrderItem` is in _`pending`_ state                                                                               |

        | held         | This state indicates that a `ServiceOrderItem` cannot be progressed due to an issue. The `Service` delivery (processing) has been temporarily delayed to resolve an infrastructure shortfall to facilitate supply of order. Upon resolution of the issue, the `ServiceOrderItem` will continue to progress.<br> A _`held`_ state can lead into automatic `failed` of an `ServiceOrderItem`, if no action is taken within the agreed timeframe.<br>The `ServiceOrder` will be in _`held`_ state if at least one `ServiceOrderItem` is in _`held`_ state |

        | failed       | This state indicates that `Service` delivery (processing) associated with a `ServiceOrderItem` has failed. This indicates an irrecoverable error as opposed to _`held`_ or _`pending`_ issues.<br>The `ServiceOrder` will be in _`failed`_ state if at _ALL_ `ServiceOrderItems` are in _`failed`_ state                                                                                                                                                                                                                                              |

        | completed    | This state indicates that `Service` delivery (processing) associated with a `ServiceOrderItem` has completed. <br>The `ServiceOrder` will be in _`completed`_ state if at _ALL_ `ServiceOrderItems` are in _`completed`_ state                                                                                                                                                                                                                                                                                                                        |

        | partial      | This state indicates that some `ServiceOrderItem` are in _`completed`_ state while others are in _`failed`_ states, so the entire `ServiceOrder` is in a _`partial`_ state. Not applicable to _`ServiceOrderItem`_.                                                                                                                                                                                                                                 

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-service-order-api-openapi.yml