Clockwork

Constraints

A Constraint is a reusable scheduling rule — a deadline, time window, or capacity limit — that can be attached to workflow instances or individual tasks. When a constraint is violated, Clockwork creates a Conflict.

When to use client.constraints

  • Enforcing regulatory deadlines that apply across multiple workflows (e.g., "all KYC tasks must complete within 5 business days")
  • Defining working-hours windows so tasks aren't scheduled overnight
  • Creating capacity rules for shared resources

Methods

MethodDescription
create(input)Define a constraint
list(opts?)List constraints in a project
attach(constraintId, input)Attach to a workflow instance or task

constraints.create(input)

Parameters

ParameterTypeRequiredDescription
namestringyesHuman-readable constraint name
typestringyesConstraint type (e.g., 'deadline', 'time_window', 'capacity')
definitionRecord<string, unknown>noType-specific configuration
projectIdstringnoDefaults to personal project
typescript
// A hard deadline constraint
const { data: constraint } = await client.constraints.create({
  name: 'KYC 5-day deadline',
  type: 'deadline',
  definition: {
    offsetDays: 5,
    relativeTo: 'instance_start',
  },
})
 
// A time-window constraint (no work outside business hours)
const { data: hoursConstraint } = await client.constraints.create({
  name: 'Business hours only',
  type: 'time_window',
  definition: {
    daysOfWeek: [1, 2, 3, 4, 5], // Mon–Fri
    startTime: '09:00',
    endTime: '17:00',
    timezone: 'America/New_York',
  },
})

constraints.attach(constraintId, input)

Attaches a constraint to a workflow instance or task.

typescript
await client.constraints.attach('con_abc123', {
  targetType: 'workflow_instance',
  targetId: 'wi_xyz',
})
 
await client.constraints.attach('con_abc123', {
  targetType: 'task',
  targetId: 'tsk_xyz',
})

Type reference

typescript
interface Constraint {
  id: string
  projectId: string | null
  name: string
  type: string
  definition: Record<string, unknown> | null
  createdAt: string
}

Related