openapi: 3.2.0 info: title: Mef Workorder API version: 3.0.0 description: 'Operations tagged workorder across 2 of this provider''s published API definitions: mef-lso-cantata-workorder-management-openapi.yml, mef-lso-sonata-workorder-management-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://{serverBase}/mefApi/cantata/workOrderManagement/v3/ variables: serverBase: description: The base of Seller's URL. default: mplify.net - url: https://{serverBase}/mefApi/sonata/workOrderManagement/v3/ variables: serverBase: description: The base of Seller's URL. default: mplify.net tags: - name: workorder paths: /workorder/{id}: get: tags: - workorder summary: Retrieves a WorkOrder by ID description: The Buyer requests detailed information about a single WorkOrder based on a WorkOrder Identifier. operationId: retrieveWorkOrder parameters: - name: id in: path description: Unique (within the Seller domain) identifier for the WorkOrder. required: true schema: type: string - name: buyerId in: query description: The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only 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 only when responding entity represents more than one Seller. required: false 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/WorkOrder' '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/cantata/workOrderManagement/v3/ variables: serverBase: description: The base of Seller's URL. default: mplify.net /workorder: get: tags: - workorder summary: Retrieves a WorkOrder by ID description: The Buyer requests detailed information about a single WorkOrder based on a WorkOrder Identifier. operationId: listWorkOrder parameters: - name: geographicalSiteId in: query description: A site identifier that is associated to the Appointment. required: false schema: type: string - name: geographicalAddressId in: query description: A address identifier that is associated to the Appointment. required: false schema: type: string - name: relatedEntityType in: query description: The type of Related Entity (e.g. Trouble Ticket). required: false schema: type: string - name: relatedEntityId in: query description: Identifier of the Related Entity. required: false schema: type: string - name: state in: query description: The state of the WorkOrder. required: false schema: type: string enum: - cancelled - completed - inProgress - open - planned - unableToComplete - name: appointmentRequired in: query description: Indicates that the Buyer must schedule an Appointment to fulfill the WorkOder. required: false schema: type: boolean - name: buyerId in: query description: The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only 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 only when responding entity represents more than one Seller. required: false schema: type: string - name: offset in: query description: Requested index for the start of resources to be provided in response required: false schema: type: integer - name: limit in: query description: Requested number of resources to be provided in response required: false schema: type: integer format: int32 responses: '200': description: OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1) content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/WorkOrder_Find' '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 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/cantata/workOrderManagement/v3/ variables: serverBase: description: The base of Seller's URL. default: mplify.net components: schemas: 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 Note: description: Extra information about a given entity. Only useful in processes involving human interaction. Not applicable to 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 the Buyer or Seller. $ref: '#/components/schemas/MEFBuyerSellerType' text: description: Text of the note type: string required: - author - date - id - source - text 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 Seller (e.g. Seller Contact Information) or by the Buyer. 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 Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer 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 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 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 WorkOrder: description: 'A set of tasks to be scheduled and performed under the responsibility of a Seller Technician(s) ' type: object properties: id: description: Unique (within the Seller domain) identifier for the WorkOrder. type: string href: description: Hyperlink, a reference to the WorkOrder entity type: string appointmentRequired: description: The Seller requires the Buyer to schedule an Appointment. If set to true, the Seller is Requesting the Buyer to schedule an Appointment. type: boolean appointment: description: A reference to a set of Appointments for the WorkOrder. A WorkOrder may contain only one open Appointment at a time (e.g. with the state of 'scheduled'). type: array items: $ref: '#/components/schemas/AppointmentRef' duration: description: The current state of the WorkOrder $ref: '#/components/schemas/TimeDuration' note: description: A set of unstructured comments or information associated to the WorkOrder type: array items: $ref: '#/components/schemas/Note' place: description: The location where the WorkOrder Tasks are to be performed. If an appointment is needed, this will also be the location where the Appointment takes place and includes the site contact which the Seller technician may need to get access to the Buyer's site during the Appointment. This could be an end-user, security personnel or any authorized person type: array items: $ref: '#/components/schemas/RelatedPlaceRefOrQuery' plannedExecutionDate: description: The date provided by the Seller to indicate when the Workorder is expected to be started. type: string format: date-time relatedContactInformation: description: 'Party playing a role in this WorkOrder. The ''role'' is to specify the type of contact as specified in MEF 113: Technical Contact (''role=technicalContact'') - REQUIRED to be set by the Seller. The Seller technical contact responsible for the WorkOrder. Technician (''role=technician'') - The Seller technician assigned to the WorkOrder and responsible for performing a set of tasks. In certain instances this could be a Buyer technician that works on behalf of the Seller.' type: array minItems: 1 items: $ref: '#/components/schemas/RelatedContactInformation' relatedEntity: description: An entity that is related to the WorkOrder such as a service, a product, etc. The entity which the WorkOrder is associated with. type: array minItems: 1 items: $ref: '#/components/schemas/RelatedEntity' state: description: The current state of the WorkOrder $ref: '#/components/schemas/WorkOrderStateType' task: description: A set of tasks to be performed under the responsibility of the Technician to fulfil the WorkOrder. Each item is a description of a specific task to be performed under the responsibility of the Technician. type: array minItems: 1 items: type: string required: - appointmentRequired - duration - id - place - relatedContactInformation - relatedEntity - state - task 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 Error401Code: description: 'One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired' type: string enum: - missingCredentials - invalidCredentials 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 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 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 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 Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer 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 TimeDurationUnits: description: The unit of measure in the duration. For example, if an interval is 2ms, this element is MS. type: string enum: - NS - US - MS - SEC - MIN - HOUR - DAY - WEEK - MONTH - YEAR 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 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 RelatedEntity: description: A reference to an entity, where the type of the entity is not known in advance. type: object properties: '@referredType': description: The actual type of the target instance when needed for disambiguation. type: string default: Product href: description: Reference of the related entity. type: string id: description: Unique identifier of a related entity. type: string role: description: The role of an entity. type: string required: - '@referredType' - id - role MEFBuyerSellerType: description: An enumeration with buyer and seller values. type: string enum: - buyer - seller 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 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 RelatedContactInformation: 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 Seller (e.g. Seller Contact Information) or by the Buyer. 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 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 or search for 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 required: - '@type' minProperties: 2 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 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:\n - missingProperty: The property the Seller 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 Seller system\n - unexpectedProperty: Additional property, not expected by the Seller has been provided\n - tooManyRecords: the number of records to be provided in the response exceeds the Seller'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 required: - code Error422Code: description: "One of the following error codes:\n - missingProperty: The property the Seller 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 Seller system\n - unexpectedProperty: Additional property, not expected by the Seller has been provided\n - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.\n - otherIssue: Other problem was identified (detailed information provided in a reason)\n" type: string enum: - missingProperty - invalidValue - invalidFormat - referenceNotFound - unexpectedProperty - tooManyRecords - otherIssue TimeDuration: description: This class is used to describe durations expressed as a 2-tuple, (value, units). The units from nanoseconds to years. type: object properties: timeDurationValue: description: The value of the duration. For example, if the duration is 20 ms, this element is 20. type: integer timeDurationUnits: description: The unit of measure in the duration. For example, if an interval is 2ms, this element is MS. $ref: '#/components/schemas/TimeDurationUnits' required: - timeDurationUnits - timeDurationValue 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 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 AppointmentRef: description: 'A reference to an Appointment resource available through Appointment API. ' type: object properties: href: description: 'Hyperlink to the referenced Appointment. Hyperlink MAY be used by the Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request ' type: string id: description: Identifier of the referenced Appointment. type: string required: - id WorkOrder_Find: description: 'A set of tasks to be scheduled and performed under the responsibility of a Seller Technician(s) ' type: object properties: id: description: Unique (within the Seller domain) identifier for the WorkOrder. type: string appointmentRequired: description: The Seller requires the Buyer to schedule an Appointment. If set to true, the Seller is Requesting the Buyer to schedule an Appointment. type: boolean place: description: The location where the WorkOrder Tasks are to be performed. If an appointment is needed, this will also be the location where the Appointment takes place and includes the site contact which the Seller technician may need to get access to the Buyer's site during the Appointment. This could be an end-user, security personnel or any authorized person type: array items: $ref: '#/components/schemas/RelatedPlaceRefOrQuery' relatedEntity: description: An entity that is related to the WorkOrder such as a service, a product, etc. The entity which the WorkOrder is associated with. type: array minItems: 1 items: $ref: '#/components/schemas/RelatedEntity' state: description: The current state of the WorkOrder $ref: '#/components/schemas/WorkOrderStateType' required: - appointmentRequired - id - place - relatedEntity - state FormattedAddressRepresentation: description: 'A freeform text representation agreed to by the Buyer and Seller. ' 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 x-refined-from: - mef-lso-cantata-workorder-management-openapi.yml - mef-lso-sonata-workorder-management-openapi.yml