Skip to main content

Reference

User Methods​

claimUserTask​

Claims a task for the authenticated user.

await client.claimUserTask({
  id: 'task-123',
  wfRunId: 'workflow-456'
}): Promise<void>;

Arguments:

type ClaimUserTaskRequest = {
  id: string;
  wfRunId: string;
};

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks permission
  • TaskStateError: If task is completed/cancelled
  • AssignmentError: If task cannot be claimed

cancelUserTask​

Cancels a task, preventing completion.

await client.cancelUserTask({
  id: "task-123",
  wfRunId: "workflow-456",
});

Arguments:

type CancelUserTaskRequest = {
  id: string;
  wfRunId: string;
};

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks permission
  • TaskStateError: If task is completed/cancelled
  • NotFoundError: If task doesn't exist

completeUserTask​

Completes a task by submitting results.

await client.completeUserTask(
  { id: 'task-123', wfRunId: 'wf-456' },
  {
    approved: { type: 'BOOLEAN', value: true },
    comment: { type: 'STR', value: 'Looks good!' }
  }
): Promise<void>;

Arguments:

type CompleteUserTaskRequest = {
  id: string;
  wfRunId: string;
};

type UserTaskResult = {
  [key: string]: {
    type: FieldType;
    value: FieldValue;
  };
};

Throws:

  • UnauthorizedError: If user lacks permission
  • NotFoundError: If task doesn't exist
  • PreconditionFailedError: If task cannot be completed

getUserTask​

Retrieves detailed information about a specific task.

const taskDetails = await client.getUserTask({
  id: "task-123",
  wfRunId: "workflow-456",
});

Returns: Detailed task information including status and field definitions

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks permission
  • NotFoundError: If task doesn't exist

listUserTasks​

Lists tasks based on search criteria.

const result = await client.listUserTasks({
  limit: 10,
  status: "ASSIGNED",
  user_id: "user-123",
  earliest_start_date: "2024-01-01T00:00:00Z",
  latest_start_date: "2024-12-31T23:59:59Z",
  user_group_id: "group-456",
  bookmark: "pagination-token",
});

Arguments:

type ListUserTasksRequest = {
  limit?: number;
  status?: Status;
  user_id?: string;
  earliest_start_date?: string;
  latest_start_date?: string;
  user_group_id?: string;
  bookmark?: string;
};

Returns: Paginated list of tasks matching criteria

Throws:

  • UnauthorizedError: If user is not authenticated
  • ValidationError: If search parameters are invalid

listUserGroups​

Retrieves all available user groups.

const groups = await client.listUserGroups();

Returns: List of user groups

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks permission

Admin Methods​

adminCancelUserTask​

Cancels any task regardless of state or assignment.

await client.adminCancelUserTask({
  id: "task-123",
  wfRunId: "workflow-456",
});

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks admin permissions
  • NotFoundError: If task doesn't exist

adminAssignUserTask​

Assigns a task to a specific user or group.

await client.adminAssignUserTask(
  { id: "task-123", wfRunId: "wf-456" },
  { userId: "user-789", userGroupId: "group-123" },
);

Arguments:

type AdminAssignUserTaskRequest = {
  id: string;
  wfRunId: string;
};

type AssignmentOptions = {
  userId?: string;
  userGroupId?: string;
};

Throws:

  • UnauthorizedError: If caller lacks admin privileges
  • NotFoundError: If task doesn't exist
  • AssignmentError: If assignment fails

adminListUsers​

Lists all users in the system.

const users = await client.adminListUsers();

Returns: List of all users

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks admin permissions

adminListUserGroups​

Lists all user groups in the system.

const groups = await client.adminListUserGroups();

Returns: List of all user groups

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks admin permissions

adminListUserTaskDefNames​

Lists all available task definition names.

const taskDefs = await client.adminListUserTaskDefNames({
  limit: 20,
  bookmark: "next-page-token",
});

Returns: List of task definition names

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks admin permissions

adminGetUserTask​

Gets detailed task information including events history.

const taskDetails = await client.adminGetUserTask({
  id: "task-123",
  wfRunId: "workflow-456",
});

Returns: Detailed task information including events history

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks admin permissions
  • NotFoundError: If task doesn't exist

adminListUserTasks​

Lists all tasks with comprehensive filtering options.

const tasks = await client.adminListUserTasks({
  limit: 50,
  type: "approval",
  status: "DONE",
  earliest_start_date: "2024-01-01T00:00:00Z",
  latest_start_date: "2024-12-31T23:59:59Z",
  user_id: "user-123",
  user_group_id: "group-456",
  bookmark: "pagination-token",
});

Returns: Paginated list of tasks

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks admin permissions
  • ValidationError: If search parameters are invalid

adminCompleteUserTask​

Completes any task regardless of state or assignment.

await client.adminCompleteUserTask(
  { id: "task-123", wfRunId: "workflow-456" },
  {
    approved: { type: "BOOLEAN", value: true },
    reason: { type: "STRING", value: "Administrative override" },
  },
);

Throws:

  • UnauthorizedError: If user is not authenticated
  • ForbiddenError: If user lacks admin permissions
  • ValidationError: If values don't match field definitions
  • NotFoundError: If task doesn't exist

Types Reference​

Status​

export type Status = "UNASSIGNED" | "ASSIGNED" | "DONE" | "CANCELLED";

FieldType​

export type FieldType =
  | "DOUBLE"
  | "BOOLEAN"
  | "STRING"
  | "INTEGER"
  | "UNRECOGNIZED";

FieldValue​

export type FieldValue = number | boolean | string;

UserGroup​

export type UserGroup = {
  id: string;
  name: string;
  valid: boolean;
};

User​

export type User = {
  id: string;
  email: string | null;
  username: string | null;
  firstName: string | null;
  lastName: string | null;
  valid: boolean;
};

UserTaskEvent​

export type UserTaskEvent =
  | UserTaskExecutedEvent
  | UserTaskAssignedEvent
  | UserTaskCancelledEvent;

UserTaskExecutedEvent​

export type UserTaskExecutedEvent = {
  wfRunId: string;
  userTaskGuid: string;
};

UserTaskAssignedEvent​

export type UserTaskAssignedEvent = {
  oldUserId?: string;
  oldUserGroup?: string;
  newUserId?: string;
  newUserGroup?: string;
};

UserTaskCancelledEvent​

export type UserTaskCancelledEvent = {
  message: string;
};

UserTaskResult​

export type UserTaskResult = {
  [key: string]: {
    type: FieldType;
    value: FieldValue;
  };
};