Clockwork

Roles

Roles are named slots declared in a workflow template (e.g., "account-manager", "legal-reviewer") that get filled with actual resources when the template is instantiated. This keeps templates generic and reusable while instances remain specific to real people or agents.

When to use client.roles

  • Assigning real people to named positions in a newly created workflow instance
  • Checking which role slots are still unfilled on a running instance
  • Reassigning a role when a team member changes mid-workflow

Methods

MethodDescription
listForInstance(instanceId)List all role slots for an instance, with fulfillment status
fill(instanceId, slotName, resourceId)Fill a slot with a resource

roles.listForInstance(instanceId)

Returns each slot defined in the template, merged with its current fulfillment (if any).

typescript
const { data: roles } = await client.roles.listForInstance('wi_abc123')
 
for (const role of roles) {
  console.log(role.slotName, role.required, role.resourceId ?? 'UNFILLED')
}
// account-manager  true   res_alice
// legal-reviewer   false  null

roles.fill(instanceId, slotName, resourceId)

Assigns a resource to a slot. Reassigning is safe — calling fill() again replaces the previous assignment.

typescript
await client.roles.fill('wi_abc123', 'legal-reviewer', 'res_bob')

Defining slots in a template

Slots are declared when creating or publishing a template:

typescript
await client.workflowTemplates.publish('tmpl_abc123', {
  manifest: { /* task graph */ },
  roles: [
    { slotName: 'account-manager', required: true, description: 'Leads the client relationship' },
    { slotName: 'legal-reviewer', required: false },
    { slotName: 'technical-lead', required: true },
  ],
})

Type reference

typescript
interface InstanceRole {
  slotName: string
  description: string | null
  required: boolean
  constraints: Record<string, unknown>
  resourceId: string | null  // null if unfilled
  assignedAt: string | null
}
 
interface RoleAssignment {
  id: string
  instanceId: string
  slotName: string
  resourceId: string
  assignedAt: string
  unassignedAt: string | null
}

Related