hailer.activity

Read and write activities (the records inside workflows), and print documents from them.

Method	Host op	Returns
list(processId, phaseId, options?)	activity.list	Promise<Activity[]>
get(activityId)	activity.get	Promise<Activity | undefined>
create(workflowId, activities, options?)	activity.create	Promise<Activity[]>
update(activities, options?)	activity.update	Promise<number>
remove(activities)	activity.remove	Promise<number>
print(requests)	activity.print	Promise<PrintResponse>

Addressing by key

Wherever a method takes a workflow, phase, or field, it accepts either the generated _id or that item's key — a stable, human-defined name set in the workspace configuration. This lets an app work against a workflow without hard-coding ids. See the Keys guide for the full model and constraints.

• list — processId and phaseId accept an id or a key.
• create — the workflow argument, each activity's phaseId, and the field keys inside fields accept an id or a key.
• update — phaseId and the field keys inside fields accept an id or a key. (Activities are still identified by _id.)

Resolving a workflow key requires a workspaceId, because keys are unique per workspace. Pass it in the options object. Ids never need a workspaceId.

list(processId, phaseId, options?)

// By id
const byId = await hailer.activity.list(workflowId, phaseId, { limit: 50 });

// By key (workspaceId resolves the workflow key)
const byKey = await hailer.activity.list('support_tickets', 'open', {
  limit: 50,
  workspaceId,
});

options is an ActivityListOptions (sort, paging, includes).

get(activityId)

const activity = await hailer.activity.get(activityId);

Takes only the activity id. (Activities have no key; get them from list.)

create(workflowId, activities, options?)

Create one or more activities in a workflow.

// By id
const created = await hailer.activity.create(workflowId, [
  { name: 'Ticket A', fields: { [fieldId]: 'High' }, phaseId, teamId },
]);

// By key — workflow key, phase key, and field keys, with workspaceId
const created2 = await hailer.activity.create('support_tickets', [
  { name: 'Ticket B', fields: { priority: 'High' }, phaseId: 'open' },
], { workspaceId });

Each entry is { name?, fields?, phaseId?, teamId? }. Field values follow ActivityFieldValue. Resolves with the created activities.

update(activities, options?)

const count = await hailer.activity.update([
  { _id: activityId, fields: { priority: 'Closed' } }, // field key or id
]);

Each entry must carry an _id. Field keys inside fields accept a key or id; phaseId accepts a key or id. A field value of null clears the field. Resolves with the number of activities updated.

remove(activities)

const count = await hailer.activity.remove([id1, id2]);

Takes an array of activity ids and resolves with the number removed.

print(requests)

Generate documents (PDF/CSV) from activities using their workflow's document templates.

// Single regular template — may be saved to the activity
const result = await hailer.activity.print([
  { activityId, templateId, savePdf: true },
]);

// Multiple activities / templates — merged output
const merged = await hailer.activity.print([
  { activityId: a, templateId: t1 },
  { activityId: b, templateName: 'Invoice' },
]);

Each request is { activityId, templateId?, templateName?, savePdf? }. Behavior:

• Single regular template (one request with templateId and no templateName) generates one document. savePdf only applies in this case — it saves the generated PDF back to the activity.
• Multiple requests, or any templateName (multi-PDF) produce a single merged document and are never saved. A templateName resolves a multi-PDF template from the activity's field data; the same template can appear more than once when authored in the array format.

See PrintRequest / PrintResponse.

hailer.activity.kanban

Method	Host op	Returns
list(processId, options?)	activity.kanban.list	Promise<KanbanListResponse>
load(activityId)	activity.kanban.load	Promise<KanbanLoadResponse>
updatePriority(activityId, priority)	activity.kanban.updatePriority	Promise<void>

const board = await hailer.activity.kanban.list(workflowId);
await hailer.activity.kanban.updatePriority(activityId, 3);

list options follow ActivityKanbanListOptions.

hailer.activity.ball

The "ball" is Hailer's turn/assignment marker on an activity's discussion.

Method	Host op	Returns
pass(activityId, toUserId)	activity.ball.pass	Promise<void>
take(activityId)	activity.ball.take	Promise<void>
list(discussionIds)	activity.ball.list	Promise<BallHolderEntry[]>

await hailer.activity.ball.pass(activityId, userId);
await hailer.activity.ball.take(activityId);

const all = await hailer.activity.ball.list('*');
const some = await hailer.activity.ball.list([discussionId]);

list accepts an array of discussion ids or '*' for all. It is served from the host's in-memory ball cache (kept current via ball signals), so there is no server round-trip. Passing an empty array resolves to [] without a call. See BallHolderEntry.

Ball changes are also delivered as signals (activity.ball.passed, taken, cleared, autoAssigned).