Workflow: Types and statuses


Every ticket has a workflow type and a status. The type says what kind of work it is, such as an inspection or a repair, and which statuses that work moves through. Statuses are shared across the account, and each type picks the ones it uses and the moves allowed between them.

This article will cover how to manage statuses and types, and how a type's status flow is set. You can read about tickets in Workflow: Tickets.

Statuses

Below is the data model for a status. A ticket is finished when its status is an end status.

interface IStatus {
    // Unique ID for the status.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 30 characters.
    DisplayName: string;
    // Description of what the status means.
    Description?: string;
    // css colour used for the status. Limited to 12 characters. Eg: "#8F8".
    Color?: string;
    // If true then a ticket in this status is finished.
    // Default is false.
    IsEnd?: boolean;
    // "E" for an end status, "P" for a status where work is still in progress.
    // Default is "P". Set it to match "IsEnd", as Operator reads this one.
    Type?: "E" | "P";
    // Only returned when requesting a type's statuses.
    // The status IDs a ticket of that type can move to next from this status.
    "NextStatus.ID"?: number[];
}

Get a list of statuses

Response
interface IResponse {
    Items: IStatus[];
}
Javascript example

Get status by ID

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

You can create a status by setting the ID as '0', or update one by its ID. When updating, only the properties you include are changed.

Create or update status

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

A status cannot be deleted while a ticket, schedule or type still uses it.

Delete status

Javascript example

Types

Below is the data model for a type. When a ticket is created, it starts in the type's default status and queue, and its own Entity is created with the type's Entity Type.

interface IType {
    // Unique ID for the type.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 30 characters.
    DisplayName: string;
    // Description of what the type is for.
    Description?: string;
    // css colour used for the type. Limited to 12 characters.
    Color?: string;
    // Status ID new tickets start in.
    "Default.Status.ID"?: number;
    // Queue ID new tickets start in.
    "Default.Queue.ID"?: number;
    // Entity Type ID for each ticket's own Entity, which sets the attributes a ticket collects.
    // Limited to 64 characters.
    "Default.EntityType.ID"?: string;
    // The statuses this type uses and the moves allowed between them.
    // See the Types: Status flow section below.
    StatusSettingsDiagram?: IStatusDiagram;
    Settings?: {
        AutoCleanup?: {
            // Deletes tickets that have sat in an end status, untouched, for this many days.
            DeleteClosed?: {
                Enabled: boolean;
                // At least 1 when enabled.
                Days: number;
            };
        };
    };
}

Get a list of types

Response
interface IResponse {
    Items: IType[];
}
Javascript example

Get type by ID

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

You can create a type by setting the ID as '0', or update one by its ID. When updating, only the properties you include are changed.

Create or update type

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

Deleting a type also deletes every ticket and schedule of that type. Its Entity Type is deleted too, when it holds nothing but those tickets and no other type uses it.

Delete type

Javascript example

Types: Status flow

A type's "StatusSettingsDiagram" is the flow chart Operator draws for it. Each shape is a status the type uses, and each connection is a move allowed from one status to another.

Saving a type with a diagram replaces its statuses and allowed moves with the ones in the diagram, so always send the whole diagram.

interface IStatusDiagram {
    // The statuses the type uses.
    Shapes: {
        // Status ID.
        Key: number;
        // Status name shown on the shape.
        Text?: string;
        // Where the shape is drawn, in pixels.
        Position?: { X: number; Y: number; };
        Size?: { Width: number; Height: number; };
        Shape?: "Circle";
        Color?: string;
    }[];
    // The moves allowed between statuses.
    Connections: {
        // Shape is the status ID. Socket is the side of the shape the line is drawn from: "L", "R", "T" or "B".
        From: { Shape: number; Socket?: string; };
        To: { Shape: number; Socket?: string; };
    }[];
}

Here is a flow where a ticket moves from "In progress" (4) to "Testing" (6), and from there to either "Complete" (7) or "Failed" (8).

{
    Shapes: [
        { Key: 4, Text: "In progress", Position: { X: 100, Y: 200 } },
        { Key: 6, Text: "Testing", Position: { X: 350, Y: 200 } },
        { Key: 7, Text: "Complete", Position: { X: 600, Y: 100 } },
        { Key: 8, Text: "Failed", Position: { X: 600, Y: 300 } }
    ],
    Connections: [
        { From: { Shape: 4, Socket: "R" }, To: { Shape: 6, Socket: "L" } },
        { From: { Shape: 6, Socket: "R" }, To: { Shape: 7, Socket: "L" } },
        { From: { Shape: 6, Socket: "R" }, To: { Shape: 8, Socket: "L" } }
    ]
}

Types: Enabled statuses

You can request the statuses a type uses, each with the status IDs a ticket can move to next. Use this to offer only the allowed moves, as the API does not check them when a ticket is updated.

Get a type's statuses

Response
interface IResponse {
    // Statuses as specified above, each with "NextStatus.ID".
    Items: IStatus[];
}
Javascript example

You can also add or remove statuses without changing the diagram. These do not change the allowed moves, and the next save of the type with a diagram replaces them.

Add statuses to a type

Request body
interface IBody {
    "WorkflowStatus.ID": number[];
}
Javascript example

Remove statuses from a type

Request body
interface IBody {
    "WorkflowStatus.ID": number[];
}
Javascript example