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.
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.
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
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
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
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
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
Deleting a ticket
Deleting a ticket also deletes its own Entity, unless that Entity is also the ticket's subject.
Delete ticket
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
Delete attachment
Delete several attachments
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.