Workflow: Tickets


Tickets are pieces of work raised about an Entity, such as an inspection or a repair. Each ticket has a type, moves through statuses, and sits in a queue that dictates who works on it. The API calls tickets Workflow Items.

Types, statuses, queues and schedules are set up separately, and tickets refer to them by ID. You can read about them in Workflow: Types and statuses, Workflow: Queues and Workflow: Schedules.

This article will cover how to manage tickets, search them, and work with their attachments and history.

Data model

Below is the core data model for a ticket.

interface ITicket {
    // Unique ID for the ticket. This is the ticket number people see.
    // Exclude this value for new records.
    ID?: number;
    // ID of the ticket's own Entity, which holds the ticket's attribute data.
    // See below for how this works.
    "Entity.ID"?: string;
    // Workflow type ID. Set when the ticket is created.
    "ItemType.ID"?: number;
    // Status ID the ticket is currently in.
    "ItemStatus.ID"?: number;
    // Queue ID the ticket is currently in.
    "Queue.ID"?: number;
    // Text describing the work.
    Description?: string;
    // ISO 8601 date time string the ticket is due by.
    DueDate?: string | null;
    // Whole number priority. Higher and lower meanings are up to you.
    Priority?: number | null;
    // ID of a parent ticket, making this a sub-ticket.
    "Parent.Item.ID"?: number | null;
    // ID of the schedule that raised the ticket. 0 means none.
    "Workflow.Schedule.ID"?: number;
    // ID of a bookmark showing where the work is. Limited to 40 characters.
    "UI.Slide.ID"?: string;
    // ID of a Client File used as the ticket's thumbnail image. Limited to 64 characters.
    "Thumbnail.ClientFile.ID"?: string;
    // ID of the user who raised the ticket, set by the API.
    "CreatedBy.User.ID"?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}

Each ticket has its own Entity, created with the ticket. The Entity holds the ticket's attributes, laid out by the Entity Type the workflow type names, so each type of ticket can collect its own data. Comments on a ticket are comments on this Entity.

The Entity the ticket is about is called its subject. It is named by the "Subject.Entity.ID" attribute on the ticket's own Entity.

// The ticket's own Entity, with its subject.
{
    "Subject.Entity.ID": "<id of the Entity the ticket is about>",
    // Any other attributes from the Entity Type's schema.
    "inspection": {
        "result": "Pass"
    },
    "Bruce": {
        "EntityType.ID": "<the workflow type's Entity Type>"
    }
}

Who can see a ticket

Power users can see and update every ticket. Other users can see and update the tickets they raised, and the tickets in a queue linked to one of their user groups. A ticket linked to a bookmark is also hidden from users who cannot open that bookmark's Project View.

Requesting a ticket

Get ticket by ID

Response
// The ticket record, as specified at the top of the article, with two additions.
interface IResponse extends ITicket {
    // The ticket's own Entity.
    Entity?: any;
    // That Entity's Entity Type, including its schema.
    EntityType?: any;
}
Javascript example

Searching tickets

You can search tickets with any combination of the filters below. A filter can take several values, either by repeating the parameter or as a comma separated list, and a ticket matches when it has any of them.

Results are paged. The first page includes the total count, and "NextPageURL" gives the request for the next page. Set both "pageSize" and "pageIndex" to -1 to get only the count.

Search tickets

Response
interface IResponse {
    // Array of tickets. See the data model above for the record structure.
    Items: ITicket[];
    // Total matching tickets. Only included on the first page.
    TotalCount?: number;
    // If there are more pages.
    NextPage: boolean;
    // Request URL for the next page.
    NextPageURL?: string;
}
Javascript example

Ticket statistics

You can count tickets grouped by the Entity Type of their subject, for example to chart how many open tickets each kind of asset has. The type, status and queue filters work the same way as in the search above.

Get ticket statistics

Response
interface IResponse {
    EntityTypes: {
        EntityType: { ID: string; Name?: string; };
        WorkflowItemsCount: number;
    }[];
    // Only included when expanded.
    ParentEntityTypes?: {
        ParentEntityType: { ID: string; Name?: string; };
        WorkflowItemsCount: number;
    }[];
    // Only included when expanded.
    Ontologies?: {
        Ontology: { ID: number; Name?: string; };
        WorkflowItemsCount: number;
    }[];
}
Javascript example

Creating a ticket

A ticket is created for a workflow type. Its status and queue start as the type's defaults, and its own Entity is created from the attributes you send, using the type's Entity Type.

You can give a different Entity Type in the URL, which needs edit access to that Entity Type. You can also send "Entity.ID" to use an Entity that already exists instead of creating one, which needs edit access to it.

Create ticket

Request body
interface IBody {
    // Attributes for the ticket's own Entity, including the subject.
    Entity?: any;
    // Use an existing Entity instead of creating one.
    "Entity.ID"?: string;
    Description?: string;
    DueDate?: string;
    Priority?: number;
    "Parent.Item.ID"?: number;
    "Workflow.Schedule.ID"?: number;
    "UI.Slide.ID"?: string;
    "Thumbnail.ClientFile.ID"?: string;
}
Response
interface IResponse {
    // The ticket's own Entity.
    Entity: any;
    // The new ticket. See the data model above for the record structure.
    WorkflowItem: ITicket;
}
Javascript example

Updating a ticket

When updating, only the properties you include are changed. Send null for "DueDate", "Priority", "Parent.Item.ID" or "Workflow.Schedule.ID" to clear it. Changing "ItemStatus.ID" or "Queue.ID" moves the ticket, and users in the new queue's user groups are notified.

Include "Entity" to update the ticket's own Entity at the same time. Its attributes are merged into the existing ones.

The API does not check a status change against the statuses the workflow type allows next, so check them yourself before moving a ticket.

Update ticket

Request body
// Body is the ticket JSON as specified at the top of the article.
// Optionally include "Entity" with attributes to merge into the ticket's own Entity.
Response
// The ticket record, as specified at the top of the article.
// When "Entity" was sent, the response also includes "Entity" and "EntityType" as in the GET request.
Javascript example

Deleting a ticket

Deleting a ticket also deletes its own Entity, unless that Entity is also the ticket's subject.

Delete ticket

Javascript example

Tickets: Attachments

Files attached to a ticket are stored as Entity Attachments on the ticket's own Entity, with the "Document" attachment type. You can list them with the Entity Attachments requests, which you can read about in Entity Attachments.

Upload attachment

Request body
// The body must be multipart/form-data, with the file in a part named "file".
Response
// The response is the new Entity Attachment record directly.

Delete attachment

Javascript example

Delete several attachments

Request body
interface IBody {
    // IDs of the attachments to delete.
    "Attachment.ID": number[];
}
Javascript example

Tickets: History

Every time a ticket is saved, a history record is kept of its type, status, queue and attributes at that moment. Together they show how the ticket moved over time.

Power users can also add, edit and delete history records, for example to backfill work done before the ticket existed.

interface ITicketHistory {
    // Unique ID for the history record.
    // Exclude this value for new records.
    ID?: number;
    // ID of the ticket this record belongs to.
    "Workflow.Item.ID"?: number;
    // ISO 8601 date time string of the change.
    DateTime?: string;
    // ID of the user who made the change.
    "UpdatedByUser.ID"?: string;
    // The ticket's type, status and queue IDs after the change.
    "Workflow.ItemType.ID"?: number;
    "Workflow.ItemStatus.ID"?: number;
    "Workflow.Queue.ID"?: number;
    // The ticket's own Entity attributes after the change.
    JSONData?: any;
    // Text describing the change.
    Comment?: string;
}

Get ticket history

Response
interface IResponse {
    // History records, newest first.
    Items: ITicketHistory[];
    TotalCount: number;
}
Javascript example

Get history record by ID

Response
// The response is the history record directly.
Javascript example

Create or update history record

Request body
// Body should be the history record JSON as specified above.
Response
// The response is the history record directly.
Javascript example

Delete history record

Javascript example