Workflow: Schedules


Schedules raise tickets on a repeating cycle, such as a monthly inspection of a set of assets. Each time the schedule comes due, it raises a ticket, or puts an existing ticket back into its starting status and queue.

This article will cover how a schedule runs and how to manage schedules. You can read about tickets in Workflow: Tickets.

Data model

interface ISchedule {
    // Unique ID for the schedule.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 200 characters.
    // Also used as the name of each raised ticket's own Entity.
    Name: string;
    // Copied to each raised ticket's description.
    Description?: string;
    // ISO 8601 date time string of the first run.
    "Start.DateTime": string;
    // Days between runs. Must be greater than 0.
    // Default is 30.
    "Recurrence.Days"?: number;
    // The type, status and queue each raised ticket is given. All three are required.
    "Workflow.ItemType.ID": number;
    "Workflow.ItemStatus.ID": number;
    "Workflow.Queue.ID": number;
    // Days after a run that the ticket is due. Leave empty for no due date.
    "DueDate.Interval.Days"?: number | null;
    // Internal IDs of the Entities each raised ticket is about.
    // An Entity's internal ID is its "Bruce.InternalID" value.
    "Subject.Entity.InternalID"?: number[];
    // If true then each run puts the same ticket back into the starting status and queue,
    // rather than raising a new one. See below.
    "Reset.On"?: boolean;
    // ID of the ticket that is put back each run. Set by the API on the first run.
    "Reset.Workflow.Item.ID"?: number | null;
    // ID of a bookmark showing where the work is. Limited to 40 characters.
    "UI.Slide.ID"?: string;
    // ID of a Client File used as each ticket's thumbnail. Limited to 64 characters.
    "Thumbnail.ClientFile.ID"?: string;
    // Set by the API.
    "Created.DateTime"?: string;
    "Created.ByUser.ID"?: string;
}

How a schedule runs

A schedule comes due at its start time and every "Recurrence.Days" after that. Each time it comes due:

  • If a ticket it raised is still in the schedule's status and queue, nothing happens. The work from the last cycle has not started, so no second ticket is raised.
  • Otherwise, if "Reset.On" is true and the schedule has a ticket to put back, that ticket is moved back into the schedule's type, status and queue, with a new due date.
  • Otherwise a new ticket is raised, with a new Entity of the type's Entity Type. When "Reset.On" is true, this ticket becomes the one that is put back on later runs.

Tickets are raised as the user who created the schedule, and the queue's user groups are notified as usual. The type must have an Entity Type set, or the schedule is skipped.

Requesting records

You can list every schedule, or only the schedules about a given Entity.

Get a list of schedules

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

Get schedule by ID

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

Create and update records

You can create a schedule by setting the ID as '0', or update one by its ID. When updating, only the properties you include are changed. Send null for "DueDate.Interval.Days" to remove the due date.

Create or update schedule

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

Delete a record

Deleting a schedule stops future runs. Tickets it already raised are kept.

Delete schedule

Javascript example