openapi: 3.0.1
info:
title: Service Ordering Management
description: |
**This file forms part of Mplify 99.1**
Supported use cases:
- Create Service Order
- Retrieve List of Service Orders
- Retrieve Service Order by Service Order Identifier
- Register for Notifications
Copyright 2025 Mplify Alliance and its contributors.
This file includes content based on the TM Forum Service Order API (TMF641
v4.1.0) available at https://github.com/tmforum-apis/TMF641_ServiceOrder,
which is licensed by the TM Forum under the Apache License version 2.0. Such
content has been modified by the Mplify Alliance and its contributors.
version: 6.0.1
servers:
- 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
- name: Events subscription
description: Endpoints to register and terminate an Event Listener
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"
"/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"
/hub:
post:
tags:
- Events subscription
summary: Register a listener
description: >-
Sets the communication endpoint address the service instance must use to
deliver information about its health state, execution state, failures
and metrics.
operationId: registerListener
requestBody:
description: Data containing the callback endpoint to deliver the information
content:
application/json;charset=utf-8:
schema:
$ref: "#/components/schemas/EventSubscriptionInput"
required: true
responses:
"201":
description: Subscribed
content:
application/json;charset=utf-8:
schema:
$ref: "#/components/schemas/EventSubscription"
"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"
"/hub/{id}":
get:
tags:
- Events subscription
summary: Retrieves a EventSubscription by ID
description: This operation retrieves a EventSubscription entity.
operationId: retrieveEventSubscription
parameters:
- name: id
in: path
description: Identifier of the EventSubscription
required: true
schema:
type: string
responses:
"200":
description: Success
content:
application/json;charset=utf-8:
schema:
$ref: "#/components/schemas/EventSubscription"
"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"
delete:
tags:
- Events subscription
summary: Unregister a listener
description: >-
Resets the communication endpoint address the service instance must use
to deliver information about its health state, execution state, failures
and metrics.
operationId: unregisterListener
parameters:
- name: id
in: path
description: The id of the registered listener
required: true
schema:
type: string
responses:
"204":
description: Deleted
"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"
'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"
components:
schemas:
BusSofType:
description: An enumeration with BUS and SOF values.
type: string
enum:
- bus
- sof
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
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
Error:
description: >
Standard Class used to describe API response error Not intended to be
used directly. The `code` in the HTTP header is used as a discriminator
for the type of error returned in runtime.
type: object
properties:
message:
description: >-
Text that provides mode details and corrective actions related to
the error. This can be shown to a client user.
type: string
reason:
description: >-
Text that explains the reason for the error. This can be shown to a
client user.
type: string
maxLength: 255
referenceError:
description: URL pointing to documentation describing the error
type: string
format: uri
required:
- reason
Error400:
description: "Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)"
allOf:
- $ref: "#/components/schemas/Error"
- type: object
properties:
code:
description: >-
One of the following error codes:
- missingQueryParameter: The URI is missing a required
query-string parameter
- missingQueryValue: The URI is missing a required query-string
parameter value
- invalidQuery: The query section of the URI is invalid.
- invalidBody: The request has an invalid body
$ref: "#/components/schemas/Error400Code"
required:
- code
Error400Code:
description: >-
One of the following error codes:
- missingQueryParameter: The URI is missing a required query-string
parameter
- missingQueryValue: The URI is missing a required query-string
parameter value
- invalidQuery: The query section of the URI is invalid.
- invalidBody: The request has an invalid body
type: string
enum:
- missingQueryParameter
- missingQueryValue
- invalidQuery
- invalidBody
Error401:
description: "Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)"
allOf:
- $ref: "#/components/schemas/Error"
- type: object
properties:
code:
description: >-
One of the following error codes:
- missingCredentials: No credentials provided.
- invalidCredentials: Provided credentials are invalid or
expired
$ref: "#/components/schemas/Error401Code"
required:
- code
Error401Code:
description: |-
One of the following error codes:
- missingCredentials: No credentials provided.
- invalidCredentials: Provided credentials are invalid or expired
type: string
enum:
- missingCredentials
- invalidCredentials
Error403:
description: >-
Forbidden. This code indicates that the server understood the request
but refuses to authorize it.
(https://tools.ietf.org/html/rfc7231#section-6.5.3)
allOf:
- $ref: "#/components/schemas/Error"
- type: object
properties:
code:
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
$ref: "#/components/schemas/Error403Code"
required:
- code
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
Error404:
description: >-
Resource for the requested path not found.
(https://tools.ietf.org/html/rfc7231#section-6.5.4)
allOf:
- $ref: "#/components/schemas/Error"
- type: object
properties:
code:
description: >-
The following error code:
- notFound: A current representation for the target resource not
found
type: string
enum:
- notFound
required:
- code
Error422:
description: >-
Unprocessable entity due to a business validation problem.
(https://tools.ietf.org/html/rfc4918#section-11.2)
allOf:
- $ref: "#/components/schemas/Error"
- type: object
properties:
code:
description: |
One of the following error codes:
- missingProperty: The property that was expected is not present in the payload
- invalidValue: The property has an incorrect value
- invalidFormat: The property value does not comply with the expected value format
- referenceNotFound: The object referenced by the property cannot be identified in the target system
- unexpectedProperty: Additional, not expected property has been provided
- tooManyRecords: the number of records to be provided in the response exceeds the threshold.
- otherIssue: Other problem was identified (detailed information provided in a reason)
$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
required:
- code
Error422Code:
description: >
One of the following error codes:
- missingProperty: The property that was expected is not present in the
payload
- invalidValue: The property has an incorrect value
- invalidFormat: The property value does not comply with the expected
value format
- referenceNotFound: The object referenced by the property cannot be
identified in the target system
- unexpectedProperty: Additional, not expected property has been
provided
- tooManyRecords: the number of records to be provided in the response
exceeds the threshold.
- otherIssue: Other problem was identified (detailed information
provided in a reason)
type: string
enum:
- missingProperty
- invalidValue
- invalidFormat
- referenceNotFound
- unexpectedProperty
- tooManyRecords
- otherIssue
Error500:
description: >-
Internal Server Error.
(https://tools.ietf.org/html/rfc7231#section-6.6.1)
allOf:
- $ref: "#/components/schemas/Error"
- type: object
properties:
code:
description: >-
The following error code:
- internalError: Internal server error - the server encountered
an unexpected condition that prevented it from fulfilling the
request.
type: string
enum:
- internalError
required:
- code
EventSubscription:
description: |
This resource is used to respond to notification subscriptions.
type: object
properties:
callback:
description: >-
The value provided by in `EventSubscriptionInput` during
notification registration
type: string
id:
description: >-
An identifier of this Event Subscription assigned when a resource is
created.
type: string
query:
description: >-
The value provided by the `EventSubscriptionInput` during
notification registration
type: string
required:
- callback
- id
EventSubscriptionInput:
description: This class is used to register for Notifications.
type: object
properties:
callback:
description: >-
This callback value must be set to *host* property from Service
Order Notification API (serviceOrderNotification.api.yaml). This
property is appended with the base path and notification resource
path specified in that API to construct an URL to which notification
is sent. E.g. for "callback": "https://client.mef.com/listenerEndpoint",
the service order state change event notification will be sent to:
`https://client.mef.com/listenerEndpoint/mefApi/legato/serviceOrderingManagement/v6/listener/serviceOrderStateChangeEvent`
type: string
query:
description: >-
This attribute is used to define to which type of events to register
to. Example: "query":"eventType = serviceOrderStateChangeEvent". To
subscribe for more than one event type, put the values separated by
comma:
`eventType=serviceOrderStateChangeEvent,serviceOrderItemStateChangeEvent`.
The possible values are enumerated by 'serviceOrderEventType' in
serviceOrderNotification.api.yaml. An empty query is treated as
specifying no filters - ending in subscription for all event types.
type: string
required:
- callback
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
FormattedAddressRepresentation:
description:
'A freeform text representation agreed to by the BUS and SOF. '
type: object
properties:
formattedAddress:
description: >-
A formatted Address Representation that contains a non-fielded
address.
type: string
language:
description: >-
The language in which the address is expressed. Based on ISO
639:2023
type: string
minLength: 2
maxLength: 2
required:
- formattedAddress
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
GeographicAddress_Query:
description: >-
A list of representations being a subset of Geographic Address entity.
This is to be used when providing a list of representations to validate
a Geographic Address
type: object
properties:
fieldedAddressRepresentation:
description: A list of Fielded Address representations
type: array
items:
$ref: '#/components/schemas/FieldedAddressRepresentation'
formattedAddressRepresentation:
description: A list of Formatted Address representations
type: array
items:
$ref: '#/components/schemas/FormattedAddressRepresentation'
geographicPointRepresentation:
description: A list of Geographic Point Address representations
type: array
items:
$ref: '#/components/schemas/GeographicPointRepresentation'
labelRepresentation:
description: A list of Label Address representations
type: array
items:
$ref: '#/components/schemas/LabelRepresentation'
'@type':
description:
Used to unambiguously designate the class type when using `oneOf`
type: string
enum:
- GeographicAddress_Query
minProperties: 2
required:
- '@type'
GeographicPointRepresentation:
description: >
A GeographicPointRepresentation defines a geographic point through
coordinates.
type: object
properties:
spatialRef:
description: >-
The spatial reference system used to determine the coordinates. The
system used and the value of this field are to be agreed during the
onboarding process.
type: string
latitude:
description:
The latitude expressed in the format specified by the `spacialRef`
type: string
longitude:
description:
The longitude expressed in the format specified by the `spacialRef`
type: string
elevation:
description:
The elevation expressed in the format specified by the `spacialRef`
type: string
required:
- latitude
- longitude
- spatialRef
GeographicSiteRef:
description: >
A reference to a Geographic Site resource available through Service Site
API
type: object
properties:
href:
description: >
Hyperlink to the referenced Site. 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 Site.
type: string
'@type':
description:
Used to unambiguously designate the class type when using `oneOf`
type: string
enum:
- GeographicSiteRef
required:
- '@type'
- 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
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"
Note_BusSof:
description: >-
Extra information about a given entity. Only useful in processes
involving human interaction. Not applicable for an automated process.
type: object
properties:
author:
description: Author of the note
type: string
date:
description: Date of the note
type: string
format: date-time
id:
description: >-
Identifier of the note within its containing entity (may or may not
be globally unique, depending on provider implementation)
type: string
source:
description: Indicates if this Note was added by BUS or SOF.
$ref: "#/components/schemas/BusSofType"
text:
description: Text of the note
type: string
required:
- author
- date
- id
- source
- text
OrderCoordinatedAction:
description: >-
The interval after the completion of one or more related Order that this
Order can be started or completed
type: object
properties:
coordinatedActionDelay:
description: The period of time for which the coordinated action is delayed.
$ref: "#/components/schemas/Duration"
coordinationDependency:
description: A dependency between the Order and a related Order
$ref: "#/components/schemas/OrderItemCoordinationDependencyType"
orderId:
description: Specifies Order that is to be coordinated with this Order.
type: string
required:
- coordinatedActionDelay
- coordinationDependency
- orderId
OrderItemCoordinatedAction:
description: >-
The interval after the completion of one or more related Order Items
that this Order Item can be started or completed
type: object
properties:
coordinatedActionDelay:
description: The period of time for which the coordinated action is delayed.
$ref: "#/components/schemas/Duration"
coordinationDependency:
description: A dependency between the Order Item and a related Order Item
$ref: "#/components/schemas/OrderItemCoordinationDependencyType"
itemId:
description: Specifies Order Item that is to be coordinated with this Order Item.
type: string
required:
- coordinatedActionDelay
- coordinationDependency
- itemId
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
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'
RelatedContactInformation:
description: >-
Contact information of an individual or organization playing a role for
this Order Item. The rule for mapping a represented attribute value to a
`role` is to use the _lowerCamelCase_ pattern. In a given context it is always
specified by the SOF (e.g. SOF Contact Information) or by the
BUS.
type: object
properties:
role:
description: The role of the particular contact in the request
type: string
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
- role
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
SubUnit:
description: Allows for sub unit identification
type: object
properties:
subUnitNumber:
description: >-
The discriminator used for the subunit, often just a simple number
but may also be a range.
type: string
subUnitType:
description: >-
The type of subunit e.g. BERTH, FLAT, PIER, SUITE, SHOP, TOWER,
UNIT, WHARF.
type: string
required:
- subUnitNumber
- subUnitType
ServiceActionType:
description: |
Action to be applied to the Service referred by this Service Order
Item
type: string
enum:
- add
- modify
- delete
ServiceOrder:
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.
allOf:
- $ref: "#/components/schemas/ServiceOrder_Common"
- type: object
properties:
href:
description: Hyperlink reference
type: string
id:
description: unique identifier
type: string
completionDate:
description: Effective delivery date amended by the provider
type: string
format: date-time
expectedCompletionDate:
description: Expected delivery date amended by the provider
type: string
format: date-time
serviceOrderItem:
description: A list of service order items to be processed by this order
type: array
minItems: 1
items:
$ref: "#/components/schemas/ServiceOrderItem"
startDate:
description: Date when the order was started for processing
type: string
format: date-time
state:
description: The state of the Service Order
$ref: "#/components/schemas/ServiceOrderStateType"
orderDate:
description: >-
Date when the Service Order was created in the SOF's system and
a Service Order Identifier was assigned
type: string
format: date-time
required:
- id
- orderDate
- serviceOrderItem
- state
ServiceOrderItem:
allOf:
- $ref: "#/components/schemas/ServiceOrderItem_Common"
- description: |
An identified part of the order. A service order is decomposed into
one or more order items.
The modelling pattern introduces the `Common` supertype to
aggregate attributes that are common to both `ServiceOrderItem` and
`ServiceOrderItem_Create`. The `Create` type has a subset of
attributes of the response type and does not introduce any new,
thus the `Create` type has an empty definition
type: object
properties:
state:
description: State of the Service Order Item
$ref: "#/components/schemas/ServiceOrderItemStateType"
terminationError:
description: >-
When the SOF cannot process the request, the SOF returns a
text-based list of reasons here.
type: array
items:
$ref: "#/components/schemas/TerminationError"
required:
- state
ServiceOrderItemRef:
description: >-
A reference to a Service Order Item. When referencing item from within
the same Service Order, the `serviceOrderId` and `serviceOrderHref` MUST
be empty.
type: object
properties:
itemId:
description: Identifier of referenced item within the referenced Service Order
type: string
serviceOrderHref:
description: Link to the order to which the referenced item belongs to
type: string
serviceOrderId:
description: Identifier of the order to which the referenced item belongs to
type: string
required:
- itemId
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
ServiceOrderItemStateType:
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:
- Invalid information is provided through the `ServiceOrderItem` request
- The request fails to meet validation rules for `Service` delivery (processing)
If one `ServiceOrderItem` is rejected, then the entire `ServiceOrder` request is rejected and a _Error Response_ is sent. |
| inProgress | This state indicates that `ServiceOrderItem` have successfully passed the validations checks and the scheduled `Service` delivery/processing has started. |
| 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).
A _`pending`_ state can lead into automatic `failed` of an `ServiceOrderItem`, if no action is taken within the agreed timeframe.
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.
A _`held`_ state can lead into automatic `failed` of an `ServiceOrderItem`, if no action is taken within the agreed timeframe.
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.
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.
The `ServiceOrder` will be in _`completed`_ state if at _ALL_ `ServiceOrderItems` are in _`completed`_ state |
enum:
- acknowledged
- rejected
- pending
- held
- inProgress
- completed
- failed
ServiceOrderItem_Common:
description: >-
An identified part of the order. A service order is decomposed into one
or more order items. This type holds the attributes common to request
and response representation of the Service Order Item.
type: object
properties:
id:
description: >-
Identifier of the order item (generally it is a sequence number 01,
02, 03, ...)
type: string
action:
description: >-
Action to be applied to the Service referred by this Service Order
Item
$ref: "#/components/schemas/ServiceActionType"
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/OrderItemCoordinatedAction"
note:
description: >-
Extra-information about the order item; e.g. useful to add extra
delivery information that could be useful for a human process
type: array
items:
$ref: "#/components/schemas/Note_BusSof"
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"
service:
description: >-
A description of the service that is the subject of this service
order item.
$ref: "#/components/schemas/ServiceValue"
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 items can be both from within the same Service Order or from
other one. When referencing item within the same Service Order,
type: array
items:
$ref: "#/components/schemas/ServiceOrderItemRelationship"
required:
- action
- id
- service
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
ServiceOrderRef:
description: Reference to a Service Order instance.
properties:
href:
description: A hyperlink to the related order
type: string
id:
description: The id of the related order
type: string
required:
- id
ServiceOrderRelationship:
description: Reference to a related Service Order and the type of that association.
type: object
properties:
serviceOrder:
description: A reference to a Service Order
$ref: "#/components/schemas/ServiceOrderRef"
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
required:
- relationshipType
- serviceOrder
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:
- Invalid information is provided through the `ServiceOrder` / `ServiceOrderItem` request
- The request fails to meet validation rules for `Service` delivery (processing)
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.
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).
A _`pending`_ state can lead into automatic `failed` of an `ServiceOrderItem`, if no action is taken within the agreed timeframe.
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.
A _`held`_ state can lead into automatic `failed` of an `ServiceOrderItem`, if no action is taken within the agreed timeframe.
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.
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.
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`_. |
enum:
- acknowledged
- rejected
- pending
- held
- inProgress
- completed
- failed
- partial
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
ServiceOrder_Create:
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 extends `ServiceOrder_Common` and adds attributes specific to
the request response.
allOf:
- $ref: "#/components/schemas/ServiceOrder_Common"
- properties:
serviceOrderItem:
description: A list of service order items to be processed by this order
type: array
minItems: 1
items:
$ref: "#/components/schemas/ServiceOrderItem_Create"
required:
- serviceOrderItem
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
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
ServiceStateType:
description: |
Valid values for the lifecycle state of the Service.
| State | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| feasibilityChecked | Initial check whether the necessary resources are available and sufficient for the installation of a given service. |
| designed | The Service is designed. The resources are identified and/or allocated, but not reserved. |
| reserved | All required resources for given service are reserved and ready. |
| inactive | The service is deactivated and is no longer available. |
| active | The service is fully available and active |
| terminated | The service is 'logically deleted'. All associated resources are freed and made available for service to other users. |
type: string
enum:
- feasibilityChecked
- designed
- reserved
- inactive
- active
- terminated
ServiceValue:
description: ServiceValue is a base class for defining the Service.
type: object
properties:
href:
description: Hyperlink reference to a Service
type: string
id:
description: unique identifier of a Service
type: string
description:
description: Free-text description of the service
type: string
externalId:
description: ID given by the consumer to facilitate searches
type: string
startDate:
description: Date when the service starts
type: string
format: date-time
endDate:
description: Date when the service ends
type: string
format: date-time
state:
description: Represent the state of lifecycle of the Service Order.
$ref: "#/components/schemas/ServiceStateType"
note:
description: A list of notes made on this service
type: array
items:
$ref: "#/components/schemas/Note_BusSof"
serviceType:
description: Business type of the service
type: string
name:
description: Name of the service
type: string
serviceRelationship:
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: array
items:
$ref: "#/components/schemas/ServiceRelationship"
relatedContactInformation:
description: >-
Contact information of an individual or organization playing a role
for this Service
type: array
items:
$ref: "#/components/schemas/RelatedContactInformation"
place:
description: >-
The relationships between this Service Order Item and one or more
Places as defined in the Service Specification.
type: array
items:
$ref: "#/components/schemas/RelatedPlaceRefOrQuery"
serviceConfiguration:
description: >-
MEFServiceConfiguration is used to specify the MEF specific service
payload. This field MUST be populated for all item 'actions' other
than 'delete'. It MUST NOT be populated when an item `action` is
`delete`. The @type is used as a discriminator.
$ref: "#/components/schemas/MefServiceConfiguration"
serviceOrderItem:
description: A list of service order items related to this service
type: array
items:
$ref: '#/components/schemas/ServiceOrderItemRef'
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:
- missingProperty: The property the SOF has expected is not present in the payload
- invalidValue: The property has an incorrect value
- invalidFormat: The property value does not comply with the expected value format
- referenceNotFound: The object referenced by the property cannot be identified in the SOF system
- unexpectedProperty: Additional property, not expected by the SOF has been provided
- tooManyRecords: the number of records to be provided in the response exceeds the SOF's threshold.
- otherIssue: Other problem was identified (detailed information provided in a reason)
$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
TimeUnit:
description: |
Represents a unit of time.
type: string
enum:
- seconds
- minutes
- businessHours
- calendarHours
- businessDays
- calendarDays
- months
- years