Discovery Guide : Ticketing system

To efficiently complete API Discovery & Documentation, you’ll need to familiarize yourself with your ticketing system’s APIs and documentation.

Make sure you have the latest API documentation for your ticketing system, which is typically available on the system’s help site. For example, in the case of Fresh-service (an ITSM system), the relevant ticketing API documentation provides details on available endpoints and attributes.

The goal of this exercise is to clearly understand:

• Which API endpoints are available and their specifications.
• What data fields and states are exposed by the system.

Required ticketing system details

Every ITSM ticketing system follows a defined structure. To configure your system in Moveworks ticketing, you will first need to understand its model and capture the following details:

*ITSM system → Ticket Types → Individual tickets*

• Ticket types (e.g., Incident, Request, Change)
• Core fields on each Ticket Types (e.g., ID, subject, description, status, priority)
• Custom fields specific to your workflows
• Valid states and transitions across the ticket lifecycle
• Requester and assignee attributes (e.g., user IDs, email, group mappings)
• Comment types (internal notes vs. public comments)

Required Endpoints

Review your ticketing system’s API documentation to confirm whether the following types of endpoints exist. These endpoints are essential for enabling Moveworks to perform key ticketing actions.

• Create Ticket – Allows end users to file a ticket through the Moveworks AI Assistant.
  • Method: POST (requires a request body)
  • Example: POST /tickets
  • Key questions:
    • What ticket types can be created (INC, RITM, CHG)?
    • What fields are required at creation?
    • How do users create tickets today (Portal, Email, Bot)?
    • How are attachments uploaded at creation?
    • For form-driven tickets, how is the originating form identified?
• Query Ticket by ID – Allows users to fetch ticket details by providing a ticket ID.
  • Method: GET (ticket ID in path or query parameters)
  • Example: GET /tickets/{ticketId}
  • Key questions:
    • Which core fields are retrievable?
• Query Tickets by Time Range – Allows Moveworks to proactively poll tickets created within a given timeframe, so users receive updates when progress is made.
  • Method: GET (requires startTime and endTime as query parameters)
  • Example: GET /tickets?startTime=...&endTime=...
  • Key questions:
    • Which core fields are retrievable?
    • Are comments/work notes accessible via this endpoint? (If not, a separate API action is required.)
    • Does the updatedDate change when comments are added?
• Query Tickets by Requester – Allows users to fetch all of their tickets via the AI Assistant.
  • Method: GET (requires requester ID or email as query parameter)
  • Example: GET /tickets?requestor={idOrEmail}
  • Key questions:
    • Which core fields are retrievable?
• Update Ticket Fields – Allows Moveworks to update ticket fields based on user input or triage model predictions.
  • Method: PUT (requires updated fields in request body and ticket ID in path)
  • Example: PUT /tickets/{ticketId}/fields
  • Key questions:
    • Which fields are mutable vs. immutable?
    • Can custom fields also be updated?
• Update Ticket Assignment – Allows Moveworks to update the ticket assignee (e.g., based on triage model predictions).
  • Method: PUT (requires assignee details in request body and ticket ID in path)
  • Example: PUT /tickets/{ticketId}/assignment
  • Key questions:
    • Which attributes change (assignee, group)?
    • Can tickets be left unassigned?
• Update Ticket State – Allows Moveworks to change a ticket’s state and advance it through the lifecycle.
  • Method: PUT (requires state in request body and ticket ID in path)
  • Example: PUT /tickets/{ticketId}/state
  • Key questions:
    • What are the valid state transitions?
    • Are additional details required to move to the next state?
    • What happens when agents comment (e.g., WIP → Pending)?
    • What happens when employees comment (e.g., Pending → WIP)?
• Resolve Ticket – Allows end users to close a ticket through the AI Assistant.
  • Method: POST (requires ticket ID in path or query parameters)
  • Example: POST /tickets/{ticketId}/resolve
  • Key questions:
    • What fields are required (resolution code, closure notes)?
    • Do any fields need to be updated before resolution?
    • Can an unassigned ticket be resolved?
• Reopen Ticket – Allows end users to reopen a previously closed ticket.
  • Method: POST (requires ticket ID in path and any required fields in request body)
  • Example: POST /tickets/{ticketId}/reopen
  • Key questions:
    • Under what conditions can a ticket be reopened?
    • What fields are required to configure reopening?
• Post Comment / Work Note – Allows end users to add a comment or work note to a ticket.
  • Method: POST (requires ticket ID in path and comment/work note in request body)
  • Example: POST /tickets/{ticketId}/notes
  • Key questions:
    • How do agents and employees communicate on tickets?
    • Is there an attribute that differentiates internal notes vs. public comments?
    • Are comments retrievable via API?
    • Do comments trigger state changes (e.g., Pending → WIP)?

📘

Note: If your system does not provide a direct API matching the examples above, you can chain multiple API calls to achieve the same outcome. The process of chaining API calls will be covered in the configuration section.

Document your API endpoints based on the guidance above. These endpoints will be referenced in the configuration phase to create HTTP actions. Each HTTP action will call the corresponding API in sequence, aligned with the ticketing action being performed for the end user.

Once you’ve identified the details above, you can proceed with the configuration process outlined below.