Genesys Cloud workitems and task routing: a practical guide to Work Automation

Picture an insurer's claims line at 11:15. A customer reports a burst pipe; the agent records the claim in the system of record and releases it to the back-office claims team. The contact centre knows exactly how long the caller queued, how long the call lasted and how long wrap-up took. Then the caller hangs up, and the claim drops out of sight. Complex claims tend to wait while quicker ones are picked first, nobody is timing them, and two days later the customer rings back to ask what is happening. The front-office agent can only search the record and hope it is up to date.

Genesys Cloud Work Automation closes that gap. It turns tasks into workitems that Genesys Cloud CX can type, park, queue, route, time and automate, much as it does for conversations. Genesys's own overview uses an insurance example: a request to expand health cover creates a workitem of worktype Coverage Expansion in the status Screening, an automated workflow emails the customer for missing details, and the workitem then routes through a queue to an agent and moves to Assigned, to be resolved within an agreed five-day SLA. We first wrote about Work Automation when Genesys announced it in June 2023; this guide replaces that post with how it works today.

A workitem is a non-conversational object: a task, a request or a case step that typically needs an agent's attention. Before dedicated APIs existed, Genesys notes that many organisations routed tasks by piggybacking on the third-party email or chat APIs, which made it hard to keep tasks and real conversations apart. Work Automation makes workitems first-class objects with their own Task Management API, such as POST /api/v2/taskmanagement/workitems, and builds on Genesys Cloud process automation, meaning events, triggers and Architect workflows, to run the business logic around them. Users can also add workitems directly, and a workitem can route automatically to a queue like an ACD interaction.

Commercially, Work Automation is an add-on. Genesys documents that it requires a Genesys Cloud CX 1, CX 2 or CX 3 licence, and its billing FAQ states that any user holding any permission in the workitems namespace is a billable Work Automation user, which makes role design a commercial decision as well as a security one. Genesys has also announced a consumption-based model that bills by the number of workitems processed each month, introduced alongside Case Management, which requires it; existing licence-based customers can stay on that model until their next renewal. We confirm which model applies before we design roles and volumes.

A worktype defines the structure and behaviour of the workitems created from it: insurance claims, hardware requests, expense reports, password resets. Every workitem has exactly one worktype, which cannot change after creation. The worktype carries the defaults each new workitem inherits unless the creation request overrides them: its workbin, queue, routing language, priority and skills, plus a due date for SLA compliance, an expiration date for date-based automation and a life span that governs how long the item is kept. It can also nominate an agent script. Two choices are permanent: a worktype's division, which must match its default workbin, and its schema, although you can edit the schema's attributes to create a new version.

The schema is where the business data lives. Each schema is a set of custom attributes, from small and large text fields to numbers, identifiers, drop-downs, tags, checkboxes, dates and date-times, with up to 50 attributes per schema and up to 100 schemas per organisation. Saving a field generates a field key used in the API, and the key cannot be changed afterwards; nor can a saved schema or its attributes be deleted. Genesys advises against holding PII, PCI or PHI data in custom attributes. Attributes drive what agents see through the Schema Display tab, which can make fields read-only or editable, as well as Architect business logic and the filtering of workitems.

Statuses track a workitem's progress through your business process, and they belong to a worktype. Every status sits in one of four categories: Open, In progress, Waiting or Closed. Before workitems of a worktype can be created, it needs a default status and at least one Open and one Closed status; Genesys can create a basic Open and Closed pair for you. Each status lists the statuses it may move to, and an empty list allows a move to any other status. A Closed status can be set to terminate the workitem, which lets supervisors track closure and SLA compliance; Genesys notes that a workitem must be terminated for its due-date compliance to be checked.

Statuses can also move on by themselves. An automatic status transition fires after a set duration, from 60 seconds to 30 days, or at a set time of day when the duration is at least one day, and it can be switched off for an individual workitem. A workitem can make up to 500 automatic transitions a day. Crucially, status is not the same as assignment state. The assignment state follows routing: AcdStarted while queued, Alerting, Connected, Held, Parked, Disconnected and Terminated, with Declined or AlertTimeout sending the item to the next agent. A claim can be Waiting in your process while it sits Parked with the agent who owns it.

A workbin is the container every workitem lives in. A workitem is always in exactly one workbin, even while it is queued or assigned, and it can be moved between workbins in the same division. Workbins belong to a division that cannot be changed, an organisation can have up to 1,000 of them, and a workbin cannot be deleted while it holds workitems or is a worktype's default. On the worktype's Routing tab, Routing Enabled decides what happens next: on, and the workitem routes as an ACD interaction through its queue; off, and it stays in the workbin, where agents can assign items to themselves or automation can process it first.

Routed workitems follow the queue's settings with standard, bullseye or preferred agent routing, or direct routing set on the workitem through the API. Skills and language filter the eligible agents, higher priority items route first, and agents need the Workitems > Workitem > Accept permission in the workitem's division. Genesys recommends dedicated queues for workitems: there is no performance view that combines conversations and workitems, and many queue settings, such as auto-answer and after-call work, are not implemented for workitems. The developer guidance adds a sharper reason: when an agent becomes free, ACD scans only a limited number of queued items, so a queue full of unassignable workitems could delay calls in the same queue.

Assignment itself is flexible. The QueueAssignmentAlerting and AgentAssignmentAlerting operations on PATCH /api/v2/taskmanagement/workitems/{workitemId} send an item to a queue or straight to a person, a user with the right permission can assign a queued item manually, and a non-alerting assignment places an item in someone's list without ringing their roster. Agents accept, decline, park, unpark and transfer workitems from the workspace, and integrations can follow a user's assignments on the v2.taskmanagement.workitems.users.{id} notification topic.

There are two complementary ways to automate. The first is the worktype's Rules tab with an Architect workitem flow. Rules fire on creation (one rule per worktype), on dates, before, on or after the due or expiry date, after creation or before the life span ends, with up to five rules each for due and expiry dates and three for life span, timed from 15 minutes to 30 days, and on status transitions. Architect generates the flow from the worktype, with workitemCreated, workitemStatusChange and workitemDateBasedEvent event types. Each worktype has one workitem flow, its worktype cannot be changed later, and only one execution runs at a time per workitem.

The second is process automation. A trigger created with POST /api/v2/processautomation/triggers listens to the v2.taskmanagement.workitems.{id} notification topic, whose events carry an operation of add, edit, delete or purge, and launches an Architect workflow when its match criteria are met. With the JSON data format, the workflow receives the whole event, including custom fields, as Flow.jsonData. That is where we call data actions to update a CRM, fetch missing information, or send the customer an update when a status changes, the proactive notification that stops them chasing the contact centre.

One gap is worth designing for. Genesys notes that there is currently no direct relationship between a workitem and the calls, messages or emails made while working it. Its interim advice is to keep attributes free for conversation IDs and write them into the workitem as each interaction completes, or in post-processing, with triggers and workflows doing the work. We build that link into the schema from day one, so a supervisor can move from a claim to every conversation about it.

Illustrative Process Automation trigger, following the Genesys Developer Center pattern: launch a workflow when a workitem with a given custom field value is edited.

POST /api/v2/processautomation/triggers
{
  "name": "Claims - customer details updated",
  "topicName": "v2.taskmanagement.workitems.{id}",
  "target": {
    "type": "Workflow",
    "id": "<Architect workflow id>",
    "workflowTargetSettings": { "dataFormat": "Json" }
  },
  "enabled": true,
  "matchCriteria": [
    { "jsonPath": "operation", "operator": "Equal", "value": "edit" },
    { "jsonPath": "customFields.claim_channel_text.value", "operator": "Equal", "value": "Web" }
  ]
}

Supervisors and administrators get dedicated workitem performance views: Queue Workitems Performance Summary and Detail, and Agent Workitems Performance Summary and Detail, alongside a workitems list that shows priority, due date, status, worktype, queue and routing state for a supervisor's agents and queues. For integration and audit, the Task Management API exposes history and versions for workbins, worktypes and workitems, such as GET /api/v2/taskmanagement/workitems/{id}/history, which returns the changes between versions. That answers the auditor's question of who changed a claim's priority, and when.

Some outcomes need more than one task. Case Management bundles workitems into a case that moves through up to three predefined stages, each owned by a team and each generating its own workitem, and closes automatically when the final stage completes. A refund that needs capture, approval and payout is the classic shape. Because Genesys ties Case Management to the consumption-based Work Automation model, we treat the step from workitems to cases as both a design and a commercial decision, and we model worktypes so that the move to cases is a natural extension rather than a rebuild.

Work Automation succeeds or fails on the process model, so we start in the back office, not in the admin screens. In Discover, our Senior Business Consultant walks the real process with the teams who do the work and measures volumes, handling times and where items wait. In Define, every status, permitted transition and SLA becomes a requirement with Given/When/Then acceptance criteria, and every system that will create or update workitems gets an interface contract. In Design, the Solution Architect fixes the decisions that cannot be undone, divisions, schemas, field keys and the worktype-to-flow pairing, in the low-level design and the design decision log, together with dedicated queues, skills, languages and the roles that carry workitems permissions.

Senior Developers build workbins, worktypes and statuses with CX as Code in version control where appropriate, and write workitem flows, workflows, triggers and data actions under the Senior Platform Practice Lead's engineering standards and four-eyes review. Our Systems Integration Tester then proves the lifecycle end to end: every permitted and forbidden transition, automatic transitions and date rules firing at the right moment, triggers matching only what they should, a workitem with a language no agent has, declines and alert timeouts, and failure paths when a data action times out. User acceptance testing is run with back-office team leaders on their own scenarios.

Transition is delivered remotely: role-based training shows agents how to accept, park, unpark and transfer workitems, and supervisors how to read the workitem views. In Run and evolve, we review Genesys release notes for Work Automation changes and tune priorities, due dates and automation against the SLAs the business set. The squad typically brings together a Solution Architect, Senior Business Consultant, Senior Developers, a Systems Integration Tester and a Trainer, backed by the whole practice. Every delivery team member holds, or is completing, Genesys Cloud certification.