Skip to main content

API Client Reference

The LittleHorse User Tasks API client provides methods for managing user tasks, including task operations, listing, and administrative functions.

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;
  };
};