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