MEF Trouble Ticket API

openapi: 3.2.0
info:
  title: Mef Trouble Ticket API
  version: 5.0.0
  description: 'Operations tagged troubleTicket across 2 of this provider''s published API definitions: mef-lso-cantata-trouble-ticket-management-openapi.yml, mef-lso-sonata-trouble-ticket-management-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{serverBase}/mefApi/cantata/troubleTicket/v5/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
- url: https://{serverBase}/mefApi/sonata/troubleTicket/v5/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
tags:
- name: troubleTicket
paths:
  /troubleTicket:
    get:
      tags:
      - troubleTicket
      summary: List or found Trouble Ticket objects
      description: 'The Buyer requests a list of Trouble Tickets from the Seller based on a set of specified filter criteria. The Seller returns a summarized list of Trouble Tickets.

        '
      operationId: listTroubleTicket
      parameters:
      - name: externalId
        in: query
        description: ID given by the consumer and only understandable by him (to facilitate his searches afterward)
        required: false
        schema:
          type: string
      - name: priority
        in: query
        description: The priority (ITIL) is based on the assessment of the impact and urgency of how quickly the Ticket should be resolved as evaluated by the Buyer. The Priority is used by the Seller to determine the order in which Tickets get resolved across Buyers.
        required: false
        schema:
          $ref: '#/components/schemas/TroubleTicketPriorityType'
      - name: sellerPriority
        in: query
        description: The priority (ITIL) is based on the assessment of the impact and urgency of how quickly the Ticket should be resolved after evaluation by the Seller of the impact of the Issue on the Buyer.
        required: false
        schema:
          $ref: '#/components/schemas/TroubleTicketPriorityType'
      - name: severity
        in: query
        description: The severity or impact (ITIL) of the Ticket as evaluated by the Buyer.
        required: false
        schema:
          $ref: '#/components/schemas/TroubleTicketSeverityType'
      - name: sellerSeverity
        in: query
        description: The severity or impact (ITIL) of the Ticket on the Buyer as evaluated by the Seller.
        required: false
        schema:
          $ref: '#/components/schemas/TroubleTicketSeverityType'
      - name: ticketType
        in: query
        description: The presumed cause of the Trouble Ticket as evaluated by the Buyer.
        required: false
        schema:
          $ref: '#/components/schemas/TroubleTicketType'
      - name: status
        in: query
        description: The current status of the Trouble Ticket
        required: false
        schema:
          $ref: '#/components/schemas/TroubleTicketStatusType'
      - name: observedImpact
        in: query
        description: The type of impact observed by the Buyer.
        required: false
        schema:
          $ref: '#/components/schemas/MEFObservedImpactType'
      - name: relatedEntityId
        in: query
        description: ID of a related entity that this ticket is related to and is present in the `relatedEntity` list
        required: false
        schema:
          type: string
      - name: relatedEntityType
        in: query
        description: Type of a related entity that this ticket is related to and is present in the `relatedEntity` list
        required: false
        schema:
          type: string
          default: Product
      - name: creationDate.gt
        in: query
        description: The date on which the Trouble Ticket was created - greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: creationDate.lt
        in: query
        description: The date on which the Trouble Ticket was created - lower than
        required: false
        schema:
          type: string
          format: date-time
      - name: expectedResolutionDate.gt
        in: query
        description: The date provided by the Seller to indicate when the Ticket is expected to be resolved - greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: expectedResolutionDate.lt
        in: query
        description: The date provided by the Seller to indicate when the Ticket is expected to be resolved - lower than
        required: false
        schema:
          type: string
          format: date-time
      - name: resolutionDate.gt
        in: query
        description: The date the Ticket status was set to resolved by the Seller - greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: resolutionDate.lt
        in: query
        description: The date the Ticket status was set to resolved by the Seller - lower than
        required: false
        schema:
          type: string
          format: date-time
      - 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 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)
          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 records. E.g. if there are 50 matching records 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 records included in the response
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TroubleTicket_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'
        '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:
      - troubleTicket
      summary: Creates a TroubleTicket
      description: A request initiated by the Buyer to create a Ticket in the Seller's system to report an Issue experienced by the Buyer
      operationId: createTroubleTicket
      parameters:
      - 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
      requestBody:
        description: The TroubleTicket to be created
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/TroubleTicket_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/TroubleTicket'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '422':
          description: Unprocessable entity due to the business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
    servers:
    - url: https://{serverBase}/mefApi/cantata/troubleTicket/v5/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
  /troubleTicket/{id}:
    get:
      tags:
      - troubleTicket
      summary: Retrieves a TroubleTicket by ID
      description: The Buyer requests detailed information about a single Ticket based on a Ticket Identifier.
      operationId: retrieveTroubleTicket
      parameters:
      - name: id
        in: path
        description: Identifier of the TroubleTicket
        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/TroubleTicket'
        '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'
    patch:
      tags:
      - troubleTicket
      summary: Updates partially a TroubleTicket
      description: A request by the Buyer to patch a Ticket created by the Buyer in the Seller's system.
      operationId: patchTroubleTicket
      parameters:
      - name: id
        in: path
        description: Identifier of the TroubleTicket
        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
      requestBody:
        description: The TroubleTicket to be updated
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/TroubleTicket_Update'
        required: true
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/TroubleTicket'
        '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'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error409'
        '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/troubleTicket/v5/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
components:
  schemas:
    TroubleTicket_Create:
      description: A Trouble Ticket is a record of an issue that is created, tracked, and managed by a Trouble Ticket management system The modeling pattern introduces the `Common` supertype to aggregate attributes that are common to both `TroubleTicket` and `TroubleTicket_Create`. It this case 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.
      allOf:
      - $ref: '#/components/schemas/TroubleTicket_Common'
      - type: object
    Note:
      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 the Buyer or Seller.
          $ref: '#/components/schemas/MEFBuyerSellerType'
        text:
          description: Text of the note
          type: string
      required:
      - author
      - date
      - id
      - source
      - text
    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
    IssueRelationship:
      description: Represents relationships to other Trouble Tickets and Incidents
      type: object
      properties:
        '@referredType':
          description: The type of the referred Issue (Incident or TroubleTicket)
          type: string
        creationDate:
          description: The date the relationship was created
          type: string
          format: date-time
        description:
          description: A description of the reason for the Relation Source to set the relationship
          type: string
        href:
          description: Reference of the Trouble Ticket or Incident
          type: string
        id:
          description: Unique identifier of the referenced Issue (Trouble Ticket od Incident)
          type: string
        relationshipType:
          description: Type of the Trouble Ticket relationship can be blocks, depends on, duplicates, causes, etc...
          type: string
        source:
          description: Indicates if this Related Issue was added by the Buyer or the Seller.
          $ref: '#/components/schemas/MEFBuyerSellerType'
      required:
      - '@referredType'
      - creationDate
      - description
      - id
      - relationshipType
      - source
    TroubleTicketStatusType:
      description: 'Possible values for the status of the Trouble Ticket


        | status                  | MEF 113 name           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

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

        | `acknowledged`          | ACKNOWLEDGED           | A request to create a Ticket was received and accepted by the Seller. The Ticket create request has been validated and a Ticket has been created by the Seller and allocated a unique `id`.                                                                                                                                                                                                                                                                                                                        |

        | `assessingCancellation` | ASSESSING_CANCELLATION | A request has been made by the Buyer to cancel the Ticket and is being assessed by the Seller to determine whether to just close the Ticket, or continue to resolve the Issue to prevent similar Create Ticket requests from other Buyers. If the Seller chooses to resolve the Issue, the Seller might create an Incident or an internal Ticket for the Issue, but that is outside the scope of this document. After the Seller has completed the assessment, the Seller updates the Ticket State to `cancelled`. |

        | `cancelled`             | CANCELLED              | The Ticket has been successfully cancelled by the Buy-er. The Buyer will receive no further Event Notifications for the Ticket. This is a terminal state.                                                                                                                                                                                                                                                                                                                                               |

        | `closed`                | CLOSED                 | The Buyer has confirmed that the Issue they reported is no longer observed, or the pre-defined time frame (agreed upon between Buyer and Seller) for confirming that the Issue has been resolved has passed without a response by the Buyer. This is a terminal state.                                                                                                                                                                                                                                             |

        | `inProgress`            | IN_PROGRESS            | The Ticket is in the process of being handled and investigated for resolution by the Seller.                                                                                                                                                                                                                                                                                                                                                                                                                       |

        | `pending`               | PENDING                | The Seller is waiting on the Buyer to provide additional information for the Ticket, or the Buyer to schedule an Appointment for the WorkOrder (linked to the Ticket) in order to continue processing the Ticket. This may result in the clock being stopped for the service level agreement until the Buyer has responded to the request.                                                                                                                                                                         |

        | `reopened`              | REOPENED               | The Buyer has verified that the Issue described in the Ticket is still observed and has not been resolved satisfactorily. The Buyer rejects the Seller''s request to close the Ticket. The Ticket has been reopened and is waiting for further actions from the Seller.                                                                                                                                                                                                                                             |

        | `resolved`              | RESOLVED               | The Buyer''s Issue described in the Ticket was resolved by the Seller. The Seller assumes that normal operation is re-established for the Buyer''s product and i snow waiting for the Buyer to confirm that the Issue they reported is no longer observed.                                                                                                                                                                                                                                                           |

        '
      type: string
      enum:
      - acknowledged
      - assessingCancellation
      - cancelled
      - closed
      - inProgress
      - pending
      - resolved
      - reopened
    DataSizeUnit:
      description: The unit of measure in the data size.
      type: string
      enum:
      - BYTES
      - KBYTES
      - MBYTES
      - GBYTES
      - TBYTES
      - PBYTES
      - EBYTES
      - ZBYTES
      - YBYTES
    TroubleTicketType:
      description: 'Possible values for the type of the Trouble Ticket:

        - assistance: Requesting help for a situation (not a failure) requiring attention that is not categorized.

        - information: Buyer is requesting information on the Issue

        - installation: Related to installation issue. Provisioning is complete, but Product is not operational.

        - maintenance: Any scheduled or non-scheduled maintenance related Issue.

        '
      type: string
      enum:
      - assistance
      - information
      - installation
      - maintenance
    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
    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
    AttachmentValue:
      description: Complements the description of an element (for instance a product) through video, pictures...
      type: object
      properties:
        author:
          description: The name of the person or organization who added the Attachment.
          type: string
        creationDate:
          description: The date the Attachment was added.
          type: string
          format: date-time
        description:
          description: A narrative text describing the content of the attachment
          type: string
        mimeType:
          description: Attachment mime type such as extension file for video, picture and document
          type: string
        name:
          description: The name of the attachment
          type: string
        size:
          description: The size of the attachment.
          $ref: '#/components/schemas/MEFByteSize'
        source:
          description: Indicates if the attachment was added by the Buyer or the Seller.
          $ref: '#/components/schemas/MEFBuyerSellerType'
        url:
          description: URL where the attachment is located.
          type: string
      required:
      - author
      - 

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