openapi: 3.1.0
info:
  title: ServiceNow Trouble Ticket Open API
  description: |
    The Trouble Ticket Open API provides endpoints to create, update, and retrieve data from the Case [sn_customerservice_case], 
    Incident [incident], and Service Problem Case [sn_sprb_mgmt_case] tables.

    Use this API to manage ticket information between external ticketing systems and the ServiceNow AI Platform.

    This API is a ServiceNow implementation of the TM Forum Trouble Ticket Management API REST specification, 
    based on TMF621 Trouble Ticket Management API User Guide v5.0.0, September 2024.

    **Authentication**: The calling user must have the `ticket_integrator` role.
  version: Zurich
  contact:
    name: ServiceNow
    url: https://docs.servicenow.com
  x-namespace: sn_ind_tsm_sdwan

servers:
- url: https://{instance}.servicenow.com/api/sn_ind_tsm_sdwan/ticket
  description: ServiceNow instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name

security:
- basicAuth: []

tags:
- name: Trouble Ticket
  description: Operations for managing trouble tickets (Cases, Incidents, and Service Problem Cases)

paths:
  /troubleTicket:
    get:
      tags:
      - Trouble Ticket
      summary: Servicenow Retrieve All Trouble Tickets
      description: Retrieves a list of all trouble ticket records from the Case, Incident, and Service Problem Case tables.
      operationId: getTroubleTickets
      parameters:
      - name: fields
        in: query
        description: List of fields to return in the response. Invalid fields are ignored.
        required: false
        schema:
          type: string
        example: "id,name,description,status,severity,ticketType"
      - name: id
        in: query
        description: Filter trouble tickets by sys_id
        required: false
        schema:
          type: string
        example: abc123
      - name: limit
        in: query
        description: Maximum number of records to return
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 10
      - name: offset
        in: query
        description: Starting index at which to begin retrieving records
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        example: 10
      - name: severity
        in: query
        description: Filter trouble tickets by severity
        required: false
        schema:
          type: string
        example: example_value
      - name: status
        in: query
        description: Filter trouble tickets by status
        required: false
        schema:
          type: string
        example: example_value
      - name: ticketType
        in: query
        description: Filter trouble tickets by ticket type
        required: false
        schema:
          type: string
          enum:
          - Case
          - Incident
          - Service Problem Case
        example: Case
      responses:
        '200':
          description: Request successfully processed. Full resource returned in response (no pagination).
          headers:
            Content-Type:
              schema:
                type: string
                default: application/json
            X-Total-Count:
              description: Total number of records available on the server
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TroubleTicket'
              examples:
                Gettroubletickets200Example:
                  summary: Default getTroubleTickets 200 response
                  x-microcks-default: true
                  value:
                  - '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - {}
                    relatedEntity:
                    - {}
                    relatedParty:
                    - {}
        '206':
          description: Partial resource returned in response (with pagination).
          headers:
            Content-Range:
              description: Range of content returned in a paginated call
              schema:
                type: string
              example: "items 3-5"
            Content-Type:
              schema:
                type: string
                default: application/json
            Link:
              description: Links to navigate through query results (first, last, next, previous)
              schema:
                type: string
            X-Total-Count:
              description: Total number of records available on the server
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TroubleTicket'
              examples:
                Gettroubletickets206Example:
                  summary: Default getTroubleTickets 206 response
                  x-microcks-default: true
                  value:
                  - '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - {}
                    relatedEntity:
                    - {}
                    relatedParty:
                    - {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Gettroubletickets400Example:
                  summary: Default getTroubleTickets 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Record not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Gettroubletickets404Example:
                  summary: Default getTroubleTickets 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Trouble Ticket
      summary: Servicenow Create a Trouble Ticket
      description: Creates a record in the Case, Incident, or Service Problem Case table.
      operationId: createTroubleTicket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TroubleTicketCreate'
            examples:
              CreatetroubleticketRequestExample:
                summary: Default createTroubleTicket request
                x-microcks-default: true
                value:
                  name: Example Title
                  description: A sample description.
                  severity: "1"
                  status: example_value
                  ticketType: Case
                  channel:
                    name: Example Title
                  note:
                  - text: example_value
                    '@type': comments
                  relatedEntity:
                  - id: abc123
                    '@referredType': asset
                  relatedParty:
                  - id: abc123
                    '@referredType': customer
      responses:
        '201':
          description: Successful. The request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TroubleTicket'
              examples:
                Createtroubleticket201Example:
                  summary: Default createTroubleTicket 201 response
                  x-microcks-default: true
                  value:
                    '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - '@type': example_value
                      text: example_value
                      date: '2026-01-15T10:30:00Z'
                      author: example_value
                    relatedEntity:
                    - '@type': example_value
                      id: abc123
                      href: example_value
                      name: Example Title
                      role: example_value
                      '@referredType': asset
                    relatedParty:
                    - id: abc123
                      name: Example Title
                      '@referredType': assigned_to
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Createtroubleticket400Example:
                  summary: Default createTroubleTicket 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /troubleTicket/{id}:
    get:
      tags:
      - Trouble Ticket
      summary: Servicenow Retrieve a Specific Trouble Ticket
      description: Retrieves a specified record from the Case, Incident, or Service Problem Case table.
      operationId: getTroubleTicketById
      parameters:
      - name: id
        in: path
        description: Sys_id of the case or incident record to retrieve
        required: true
        schema:
          type: string
        example: abc123
      - name: fields
        in: query
        description: List of fields to return in the response. Invalid fields are ignored.
        required: false
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successful. The request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TroubleTicket'
              examples:
                Gettroubleticketbyid200Example:
                  summary: Default getTroubleTicketById 200 response
                  x-microcks-default: true
                  value:
                    '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - '@type': example_value
                      text: example_value
                      date: '2026-01-15T10:30:00Z'
                      author: example_value
                    relatedEntity:
                    - '@type': example_value
                      id: abc123
                      href: example_value
                      name: Example Title
                      role: example_value
                      '@referredType': asset
                    relatedParty:
                    - id: abc123
                      name: Example Title
                      '@referredType': assigned_to
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Gettroubleticketbyid400Example:
                  summary: Default getTroubleTicketById 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Record not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Gettroubleticketbyid404Example:
                  summary: Default getTroubleTicketById 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      tags:
      - Trouble Ticket
      summary: Servicenow Update a Trouble Ticket
      description: Updates a specified record in the Case, Incident, or Service Problem Case table.
      operationId: updateTroubleTicket
      parameters:
      - name: id
        in: path
        description: Sys_id of the case or incident record to update
        required: true
        schema:
          type: string
        example: abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TroubleTicketUpdate'
            examples:
              UpdatetroubleticketRequestExample:
                summary: Default updateTroubleTicket request
                x-microcks-default: true
                value:
                  name: Example Title
                  description: A sample description.
                  severity: "1"
                  status: example_value
                  channel:
                    name: Example Title
                  note:
                  - text: example_value
                    '@type': comments
                  relatedEntity:
                  - id: abc123
                    '@referredType': asset
                  relatedParty:
                  - id: abc123
                    '@referredType': customer
      responses:
        '200':
          description: Successful. The request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TroubleTicket'
              examples:
                Updatetroubleticket200Example:
                  summary: Default updateTroubleTicket 200 response
                  x-microcks-default: true
                  value:
                    '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - '@type': example_value
                      text: example_value
                      date: '2026-01-15T10:30:00Z'
                      author: example_value
                    relatedEntity:
                    - '@type': example_value
                      id: abc123
                      href: example_value
                      name: Example Title
                      role: example_value
                      '@referredType': asset
                    relatedParty:
                    - id: abc123
                      name: Example Title
                      '@referredType': assigned_to
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updatetroubleticket400Example:
                  summary: Default updateTroubleTicket 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Record not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Updatetroubleticket404Example:
                  summary: Default updateTroubleTicket 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with ServiceNow credentials. User must have the ticket_integrator role.

  schemas:
    TroubleTicket:
      type: object
      properties:
        '@type':
          type: string
          default: TroubleTicket
          description: This value is always TroubleTicket
          example: example_value
        id:
          type: string
          description: The sys_id of the case or incident record
          example: abc123
        href:
          type: string
          description: Relative link to the case or incident record
          example: example_value
        creationDate:
          type: string
          format: date-time
          description: The date that the case or incident record was created
          example: '2026-01-15T10:30:00Z'
        lastUpdate:
          type: string
          format: date-time
          description: The date the record was last updated
          example: '2026-01-15T10:30:00Z'
        name:
          type: string
          description: The name of the trouble ticket, typically a short description of the issue
          example: Example Title
        description:
          type: string
          description: The description of the issue from the ticket
          example: A sample description.
        severity:
          type: string
          description: The severity of the issue described by the trouble ticket
          example: "2 - High"
        status:
          type: string
          description: The current status of the trouble ticket
          example: example_value
        ticketType:
          type: string
          enum:
          - Case
          - Incident
          - Service Problem Case
          description: The type of ticket
          example: Case
        channel:
          $ref: '#/components/schemas/Channel'
        note:
          type: array
          description: A list of all comments on the ticket (excludes work notes)
          items:
            $ref: '#/components/schemas/Note'
          example: []
        relatedEntity:
          type: array
          description: List of impacted assets, products, sold products, configuration items, or services
          items:
            $ref: '#/components/schemas/RelatedEntity'
          example: []
        relatedParty:
          type: array
          description: Details about contacts for the ticket
          items:
            $ref: '#/components/schemas/RelatedParty'

          example: []
    TroubleTicketCreate:
      type: object
      required:
      - description
      - severity
      - status
      properties:
        name:
          type: string
          description: Name of the trouble ticket, typically a short description of the issue
          example: Example Title
        description:
          type: string
          description: A description of the issue
          example: A sample description.
        severity:
          type: string
          enum:
          - "1"
          - "2"
          - "3"
          - "4"
          - "5"
          description: |
            The severity of the issue (must provide choice value only):
            - 1: Critical
            - 2: High
            - 3: Moderate
            - 4: Low
            - 5: Planning (Incident only)
          example: "1"
        status:
          type: string
          description: The current status of the trouble ticket (can provide choice label or value)
          example: example_value
        ticketType:
          type: string
          enum:
          - Case
          - Incident
          - Service Problem Case
          default: Incident
          description: The type of ticket to create
          example: Case
        channel:
          $ref: '#/components/schemas/ChannelInput'
        note:
          type: array
          description: List of work notes and comments to add to the ticket
          items:
            $ref: '#/components/schemas/NoteInput'
          example: []
        relatedEntity:
          type: array
          description: List of impacted assets, products, sold products, configuration items, or services
          items:
            $ref: '#/components/schemas/RelatedEntityInput'
          example: []
        relatedParty:
          type: array
          description: Details about contacts for the ticket
          items:
            $ref: '#/components/schemas/RelatedPartyInput'

          example: []
    TroubleTicketUpdate:
      type: object
      properties:
        name:
          type: string
          description: Name of the trouble ticket, typically a short description of the issue
          example: Example Title
        description:
          type: string
          description: Description of the issue
          example: A sample description.
        severity:
          type: string
          enum:
          - "1"
          - "2"
          - "3"
          - "4"
          - "5"
          description: |
            The severity of the issue (must provide choice value only):
            - 1: Critical
            - 2: High
            - 3: Moderate
            - 4: Low
            - 5: Planning (Incident only)
          example: "1"
        status:
          type: string
          description: The current status of the trouble ticket (can provide choice label or value)
          example: example_value
        channel:
          $ref: '#/components/schemas/ChannelInput'
        note:
          type: array
          description: List of work notes and comments to add to the ticket
          items:
            $ref: '#/components/schemas/NoteInput'
          example: []
        relatedEntity:
          type: array
          description: List of impacted assets, products, sold products, configuration items, or services
          items:
            $ref: '#/components/schemas/RelatedEntityInput'
          example: []
        relatedParty:
          type: array
          description: Details about contacts for the ticket
          items:
            $ref: '#/components/schemas/RelatedPartyInput'

          example: []
    Channel:
      type: object
      properties:
        name:
          type: string
          description: The name of the contact method

          example: Example Title
    ChannelInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the contact method (can provide choice label or value, e.g., 'Virtual Agent' or 'virtual_agent')

          example: Example Title
    Note:
      type: object
      properties:
        '@type':
          type: string
          default: comments
          description: The type of note (always 'comments' in responses)
          example: example_value
        text:
          type: string
          description: The comment text
          example: example_value
        date:
          type: string
          format: date-time
          description: The date the comment was created
          example: '2026-01-15T10:30:00Z'
        author:
          type: string
          description: The name of the user who wrote the comment

          example: example_value
    NoteInput:
      type: object
      required:
      - text
      - '@type'
      properties:
        text:
          type: string
          description: Note text
          example: example_value
        '@type':
          type: string
          enum:
          - comments
          - work_notes
          description: Type of note (determines whether recorded in Work notes or Additional comments field)

          example: comments
    RelatedEntity:
      type: object
      properties:
        '@type':
          type: string
          default: relatedEntity
          description: This value is always relatedEntity
          example: example_value
        id:
          type: string
          description: Sys_id of the impacted item or service
          example: abc123
        href:
          type: string
          description: Returns an empty string
          example: example_value
        name:
          type: string
          description: Name of the impacted item or service
          example: Example Title
        role:
          type: string
          description: Description of the impacted item or service
          example: example_value
        '@referredType':
          type: string
          enum:
          - asset
          - product
          - product_inventory
          - cmdb_ci
          - cmdb_ci_service
          description: Type of item or service

          example: asset
    RelatedEntityInput:
      type: object
      required:
      - id
      - '@referredType'
      properties:
        id:
          type: string
          description: Sys_id of the impacted item or service
          example: abc123
        '@referredType':
          type: string
          enum:
          - asset
          - product
          - product_inventory
          - cmdb_ci
          - cmdb_ci_service
          description: Type of item or service

          example: asset
    RelatedParty:
      type: object
      properties:
        id:
          type: string
          description: Sys_id of the related party
          example: abc123
        name:
          type: string
          description: Name of the related party
          example: Example Title
        '@referredType':
          type: string
          enum:
          - assigned_to
          - assignment_group
          - customer
          - customer_contact
          description: |
            Type of related party:
            - assigned_to: User assigned to work on the ticket
            - assignment_group: Group assigned to work on the ticket
            - customer: Company or account for the ticket
            - customer_contact: Caller or contact for the ticket

          example: assigned_to
    RelatedPartyInput:
      type: object
      required:
      - id
      - '@referredType'
      properties:
        id:
          type: string
          description: Sys_id of the related party
          example: abc123
        '@referredType':
          type: string
          enum:
          - customer
          - customer_contact
          description: |
            Type of related party:
            - customer: Company or account for the ticket
            - customer_contact: Caller or contact for the ticket

          example: customer
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message
            detail:
              type: string
              description: Detailed error information
          example: example_value