WorkOrder Management Notification — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Cantata SDK, Kylie release. LSO Cantata is the Interface Reference Point between a Customer (typically an enterprise) and a Service Provider, covering the business/product layer. 3 path(s), 3 operation(s). Apache-2.0 licensed and openly downloadable from public GitHub.
openapi: 3.0.1
info:
title: WorkOrder Management Notification
description: |
**This file forms part of Mplify 137.1**
**This API implements Business Requirements described in MEF 113.**
It allows the Buyer to create, retrieve, and update WorkOrders as well
as receive notifications about Incidents and WorkOrders updates.
This allows managing issues and situations that are not part of normal
operations of the Product provided by the Seller.
List of supported use cases:
- Send WorkOrder Notification
Copyright 2025 Mplify Alliance and its contributors
This file includes content based on the TM Forum Work Order API (TMF697
v4.0.0) available at https://github.com/tmforum-apis/TMF697_Work_Order,
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: 3.0.0
servers:
- url: 'https://{serverBase}/mefApi/cantata/workOrderNotification/v3/'
variables:
serverBase:
description: The base of Buyer's URL.
default: mplify.net
tags:
- name: Notification listeners
description: |
The Buyer's endpoint to send particular event types notifications to.
paths:
/listener/workOrderCreateEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity WorkOrder Create Event
description:
Client listener for receiving the notification WorkOrder Create Event
operationId: listenToWorkOrderCreateEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/WorkOrderCreateEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'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'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/workOrderStateChangeEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity workOrderStateChangeEvent
description:
Client listener for receiving the workOrderStateChangeEvent notification
operationId: listenToWorkOrderStateChangeEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/WorkOrderStateChangeEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'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'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/workOrderAppointmentRequiredEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity workOrderAppointmentRequiredEvent
description: >-
Client listener for receiving the workOrderAppointmentRequiredEvent
notification
operationId: listenToWorkOrderAppointmentRequiredEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/WorkOrderAppointmentRequiredEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'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'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
components:
schemas:
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:
reason:
description: >-
Text that explains the reason for the error. This can be shown to a
client user.
type: string
maxLength: 255
message:
description: >-
Text that provides mode details and corrective actions related to
the error. This can be shown to a client user.
type: string
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
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
Event:
description: >-
Event class is used to describe information structure used for
notification.
type: object
properties:
eventId:
description: Id of the event
type: string
eventTime:
description: Date-time when the event occurred
type: string
format: date-time
eventType:
description: The type of the notification.
type: string
event:
description: The event linked to the involved resource object
type: object
required:
- event
- eventId
- eventTime
- eventType
WorkOrderAppointmentRequiredEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- workOrderAppointmentRequiredEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/WorkOrderEventPayload'
required:
- event
- eventType
WorkOrderCreateEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- workOrderCreateEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/WorkOrderEventPayload'
required:
- event
- eventType
WorkOrderEventPayload:
description: The identifier of the WorkOrder is subject of this event.
type: object
properties:
id:
description: ID of the WorkOrder attributed by quoting system
type: string
href:
description: Hyperlink to access the WorkOrder
type: string
required:
- id
WorkOrderStateChangeEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- workOrderStateChangeEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/WorkOrderStateChangeEventPayload'
required:
- event
- eventType
WorkOrderStateChangeEventPayload:
description:
The identifier of the Product Offering being subject of this event.
type: object
properties:
id:
description: ID of the Product Offering attributed by the Seller
type: string
href:
description: Hyperlink to access the Product Offering
type: string
format: uri
state:
description: The current state of the WorkOrder
$ref: '#/components/schemas/WorkOrderStateType'
required:
- id
- status
WorkOrderStateType:
description: |
Possible values for the state of the WorkOrder
| state | MEF 113 name | Description |
| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `completed` | COMPLETED | The Seller Technician responsible for the WorkOrder has successfully completed all the assigned Tasks. |
| `cancelled` | CANCELLED | The WorkOrder has been cancelled by the Seller or due to the Buyer requesting to cancel the WorkOrder. |
| `inProgress` | IN_PROGRESS | The Seller Technician responsible for the WorkOrder has been assigned and started one or more of the assigned Tasks. |
| `open` | OPEN | A WorkOrder was initiated by the Seller to be assigned to a Technician responsible for resolving the WorkOrder. |
| `planned` | PLANNED | The WorkOrder has been given an execution date for resolving one or more Tasks. |
| `unableToComplete` | UNABLE_TO_COMPLETE | The Seller Technician responsible for the WorkOrder was unable to complete one or more of the assigned Tasks, because additional skills or information is required. Additional tasks are required to resolve the WorkOrder and a new WorkOrder needs to be opened. |
type: string
enum:
- cancelled
- completed
- inProgress
- open
- planned
- unableToComplete