Request types, workflows and approvals

Enterprise feature (1.19.0, helpdesk). See the Helpdesk overview.

Request types

A request type is one card in Get help: New laptop or device, Access to a space or app, Report a problem. Desk settings → Request types (Request types capability) creates, orders and switches them off. Each has:

• a title, a description, an icon and a category;
• the team that owns its requests, and the priority it starts at (which picks its reply targets);
• who may use it: everyone, or only chosen groups;
• a line saying how long it usually takes (“Usually 3 to 5 days”);
• a form, and optionally a workflow.

Forms

The form builder adds questions of these types: Choice (cards with an optional hint, such as “16-inch, 32 GB · £1,450”), Select (a list), Text, Long text, Date, Number, Person (someone from the workspace), and Checkbox. Each question has a label, optional help text, and can be required.

A question can be filled in from the directory (such as the requester’s cost centre or office), so people don’t type what CompassDocs already knows; the requester sees From your directory entry and can change it.

Each question has a key (start_date, laptop) that conditions, routing and messages refer to.

Workflows

A workflow is what happens after a request is sent. Build them in the desk under Workflows (Workflows capability) and attach one to a request type. A request of that type starts a run of the workflow.

Steps

Step	What it does
Approval	Waits for a decision from a team, a named person, the requester’s manager or, for access requests, the space’s owner. See Approval steps.
Task	Opens a task for a team: a ticket of its own in that team’s queue, titled “Laptop and accounts: New starter: Sam Lee”, linked to the request. The step is done when the task is solved.
At the same time	A group of tasks for several teams that run in parallel; the group is done when every task in it is.
Wait	Waits until a date from the form (the start date), a number of days before or after it, or for a number of hours.
Notify	Sends a message (bell and email) to the requester, a person or a team.
Finish	Solves the request, and asks the satisfaction question if the survey is on.

A task’s due date is a number of days before or after a date in the form (three days before the start date) or a number of hours after the task opens. Waits, task due dates and approval reminders count calendar time unless you choose business time (see Counting business time).

From 1.19.2 a task step can add up to five checklists to its task’s ticket when the task starts (Checklists → Add checklist in the step’s settings). Their required items must be ticked before the task is done. A Finish step whose request still has required items open leaves the request open, with an internal note, and tells its owner; the request is solved by hand once they’re ticked, with the Finish step’s survey choice.

Counting business time

From 1.19.1 a Wait step, a task’s due date and an approval’s reminder each have a Count choice:

• Calendar days or Calendar hours (the default): weekends and holidays count. Every step saved before 1.19.1 counts this way, so existing workflows and runs on their way are unchanged.
• Business days or Business hours: only a team’s office hours count, skipping weekends and holidays (see Calendars).

Whose calendar picks the team whose office hours and holidays count. By default a task counts in The task’s team’s calendar, and a wait or a reminder in The request type’s team’s (or the request’s team when the type has none). A step can name any other team. A calendar with no business days counts calendar days instead, and the builder says so.

The rules for business time:

• N business days before a date is the Nth business day before it. The date itself never counts. N days after is the Nth business day after it, and On the day is the date, or the next business day when it isn’t one.
• A wait ends when that business day opens; a task is due when it closes.
• N business hours count from the moment the step starts.
• A day with a part-day holiday is still a business day. A whole-day holiday is not.

For an offset from a form date, the builder shows a worked example from the team’s real calendar. With 31 December and 1 January as holidays, a wait set to 2 days before a start date of Monday 4 January moves on on Tuesday 29 December: Wednesday 30 December is the first business day before it, and Tuesday the second.

A step that counts business time shows a Business days or Business hours chip in the builder, and its card says how it counts. In calendar mode, a delay the builder used to label “1 business day” now reads “8 hours”, which is what it always counted.

Drafts, publishing and versions

Changes to a workflow are a draft until you Publish them; Discard changes throws the draft away. A request already running keeps the version it started with, so editing a workflow never changes requests in flight.

Test run

Test run walks a workflow with sample answers for every question and a sample requester, without creating anything. It shows who would approve each approval, which steps would be skipped and why, which team each task would go to, and when each task would be due. For a step that counts business time, it also shows whose calendar counted and the holidays it skipped. Hand-offs that don’t exist yet are assumed to pass, with a note.

Approval steps

An approval goes to one of:

• A team: any one member of the team decides.
• A named person.
• The requester’s manager, from the requester’s directory entry (“Reports to”).
• The space’s owner (for Request access): the owner named in the space’s policy defaults, otherwise the people who manage space access. The approver sees which space the request is for; the requester sees only “the people who look after the space”.

When there is nobody to ask (no manager in the directory, the approver is the requester, the approving team or person was deleted), the request type’s team leads decide instead, or any member of the team when it has no lead, or the helpdesk admins; the request says who stands in and why.

The approver gets an email and a bell notice, sees the request in Approvals and on the dashboard’s Needs your attention, and can approve, decline with a note, or ask the requester a question. An approval can send one reminder after a number of hours, calendar or business.

When declined, the step either closes the request (it is solved with the approver’s note, and the requester is told) or carries on with the next step, as the step is set.

Request access to a space. When a Request access run finishes with its space-owner approval given for that same space, the requester is given read access to that space (the Space member role on that space) and nothing more. Only a Request access request can name a space, and only a private space the requester can’t read yet; on any other request the space is quietly dropped. The grant is in the audit log as helpdesk.space_access.granted.

Workflows across teams

A request often needs several teams: a new starter needs HR, IT and Facilities. These step options make that work.

Only if

Any step can run Only if its rules are true (All of these or Any of these). A rule reads:

• the request form: an answer (“Laptop is one of Standard or Developer”, “Needs a laptop is Yes”);
• the requester’s directory entry: department, office, location, title, manager, or another directory field (“Office is London”);
• an earlier task’s hand-off field (“Badge number is not empty”).

Tests are is, is not, is any of, contains, is empty, is not empty, yes and no, compared as text, ignoring case. A skipped step is listed on the request’s progress with the reason (“Skipped: Desk and badge (Office is not London)”).

Route to team by answer

A task can choose its team from an answer or from the requester’s directory entry, instead of always going to one team: “By Office: London → Facilities UK, Paris → Facilities FR; anything else → Facilities”. List the answers and their teams, and the team for Anything else.

Hand-off fields

A task can ask its team for what the next teams need when it is done: a laptop’s asset tag, a badge number, a desk. Each hand-off field has a label, a type (text, number, date, a choice, or yes/no) and can be required (“Needed to finish”). The team fills them in when it marks the task done, with an optional Note for the next teams.

Later steps can use them: an Only if rule can test them, and messages can quote them ({{outputs.it.asset_tag}}). The request’s progress shows each team’s hand-off.

A task with required hand-off fields can’t be solved without them, however it is solved: the status menu, a reply with Send and set, a macro or an automation.

If the team can’t do it

A task team can mark its task Can’t be done, with a reason (“Why can’t it be done?”). The step says what happens next:

• Carry on: the next steps start anyway, and the team’s reason shows on the request’s progress.
• Wait for the coordinating team (the default): the run stops and the request’s team sees a banner with three choices: Retry step (open the task again), Skip and carry on, or Cancel workflow (“Workflow cancelled. The request is yours to finish.”).

The coordinating team is notified when a run stops (“Workflow stopped”). Deleting a task ticket counts as the task being finished, so the workflow carries on. From 1.19.4 a deleted ticket goes to the recycle bin first: a task binned on its own holds its step until it is restored or deleted for good, and only then does the workflow carry on. A request in the bin holds its whole run, which moves on again when it is restored.

What task teams see

A task team works its task in its own queue, with a Part of request #1047 · New starter: Sam Lee link. Open request (read-only) shows the request’s answers, the progress across teams and the hand-offs; the request’s internal notes stay hidden, and they can’t change it. Someone who can see the task but not the request reads “You can see this task, but not the request it belongs to.”

Progress across teams

The request’s team sees Progress across teams on the request: every team’s task, its state (Waiting, In progress, Finished, Handed back, Skipped, Stopped), who did it and when, and what each team handed on. The time each team spends on its part is in Reports (Workflow time by team).

Placeholders

A Notify message and a task’s description can use:

Placeholder	Becomes
{{requester}}	The requester’s name
{{subject}}	The request’s subject
{{number}}	The request’s number
{{request_type}}	The request type’s title
{{workflow}}	The workflow’s title
{{tasks}}	A summary of the tasks so far
{{answer.KEY}} or {{KEY}}	A form answer, by its key: {{answer.start_date}}, {{start_date}}
{{outputs.STEP.KEY}}	A hand-off field from an earlier task: {{outputs.it.asset_tag}}

An unknown placeholder is left as written, so a typo shows in the message instead of vanishing.

The starter workflows

The starter set adds three:

• New laptop or device: the requester’s manager approves, then an IT task, then finish.
• Access to a space or app: the space’s owner approves, then the grant, then finish.
• New starter: HR approves, then IT, Facilities and HR tasks at the same time, then wait until the start date, then tell the requester, then finish.

Runs that need a hand

A stopped run shows its banner on the request to the request’s team, with Retry step, Skip and carry on and Cancel workflow (see If the team can’t do it). Each choice is in the audit log.

In the audit log

Action	Shown as
helpdesk.request_type.created / .updated / .deleted / .reordered	Created / Edited / Deleted / Reordered request types
helpdesk.workflow.created / .updated / .deleted	Created / Edited / Deleted workflow
helpdesk.workflow.published	Published workflow
helpdesk.workflow.draft_discarded	Discarded workflow changes
helpdesk.workflow.test_run	Tested workflow
helpdesk.approval.approved / .declined	Approved / Declined a request
helpdesk.space_access.granted	Granted space access from a request
helpdesk.workflow_run.step_retried	Retried a workflow step
helpdesk.workflow_run.step_skipped	Skipped a workflow step
helpdesk.workflow_run.cancelled	Cancelled a workflow run