Keys

Workflows, phases, and fields each have a generated _id and an optional key — a stable, human-defined name (up to 64 characters) set on them in the workspace configuration (via the Hailer SDK or the Hailer UI). Keys let an app reference a workflow's structure by name instead of by its generated id, so the same code works against a workflow without hard-coding ids.

Keys are unique within a workspace.

How resolution works

Anywhere a workflow, phase, or field is expected, the value is checked: a 24-character hex string is treated as an _id and used directly; anything else is resolved as a key.

Activities themselves are identified by their _id (they have no key). Get an activity's _id from activity.list, then use it with activity.get, activity.update, and activity.remove.

Where keys are accepted

Method	Accepts a key for
activity.list(processId, phaseId, options?)	processId (workflow), phaseId
activity.create(workflowId, activities, options?)	workflow argument, each activity's phaseId, the field keys in fields
activity.update(activities, options?)	each activity's phaseId, the field keys in fields

Resolving a workflow key needs a workspaceId

Because a key is only unique within a workspace, resolving a workflow key requires a workspaceId. Pass it in the options object:

// Workflow, phase, and fields all by key
const created = await hailer.activity.create(
  'support_tickets',                       // workflow key
  [{ name: 'New ticket', phaseId: 'open', fields: { priority: 'High' } }],
  { workspaceId },                         // resolves the workflow key
);

const activities = await hailer.activity.list('support_tickets', 'open', { workspaceId });

Passing a real workflow _id needs no workspaceId.

Field values with keys

Inside fields, the object keys are field keys (or field ids) and the values are the field values:

await hailer.activity.update([
  { _id: activityId, fields: { priority: 'Closed', assignee: userId } },
]);

Related

• Reference: activity — the methods that accept keys.