Tasks

Definitions of the types and formats of the data used in the endpoints can be found at the bottom of the page.

Endpoints

Get Tasks

GET https://cubicl.io/api/v1/tasks

Gets tasks matching the given search criteria. Some details won't be returned in the response. Use Get Task By Id request to get all details.

Query Parameters

Name
Type
Description

group

string

Project id

assignee

string

Task assignee id

limit

number

skip

number

tag

string

Tag name

customer

string

Client id

assignedBy

string

Task owner id

startDate

number

Start of time interval the task's start date or deadline falls into. Must be used with "endDate" parameter.

endDate

number

Read "startDate"

archived

string

'true' to get archived tasks

'false' to get unarchived tasks

'all' to get all tasks

Default is 'false'

recursive

string

'true' to get tasks in descended projects too

Leave empty to get tasks only in given project

Default is empty

search

string

Text to search in task name

include

string

Comma separated list of properties to be included in the response

exclude

string

Comma separated list of properties to be excluded in the response. Cannot be used together with include.

Task[]

Get Task By Id

GET https://cubicl.io/api/v1/tasks/:id

Path Parameters

Name
Type
Description

id*

string

Task id

Task

Create Task

POST https://cubicl.io/api/v1/tasks

Request Body

Name
Type
Description

group*

string

Project id

workFlowId

string

Set when task is being created with a workflow.

parent

string

Parent task id. Set when task is being created a subtask of another task.

private

boolean

Default is false

recurrence

Recurrence

If 'recurrent' is true, this should be set. Check below for recurrence details.

recurrent

boolean

Default is false.

steps

CheckList | ProgressBar

If 'stepType' is 'steps', provide steps in CheckList format. Id field is not required. It will be set in the server.

If 'stepType' is 'progress', provide steps in ProgressBar format.

If 'stepType' is 'none', don't set this.

stepType

string

'none' for no task steps

'steps' for checklist

'progress' for progress bar

Default is 'none'

files

string[]

List of file ids. In order to create a file with files, you need to upload files before creating the task and set their ids here.

customer

string

Client id

tags

string[]

Tag ids

priority

number

1 to 5. 5 is highest. Default is 3.

assignees

string[]

List of assignee ids

deadline

number

start

number

Start date

desc

string

Task description

name*

string

Task name

state

string

State name. If not given, default state set in the project details will be used.

estimatedTime

number

Estimated time of the task in seconds. Shown in the UI only when enabled in the project settings.

customFields

object

An object where keys are the custom field names and values are the values of those fields.

followers

string[]

Ids of task followers. If not set, task owner and assignees will be followers.

Task

Update Task

PUT https://cubicl.io/api/v1/tasks/:id

Updates a task with given details. All details are optional. Only given fields are updated. If you need to unset a field, set its values to null or appropriate falsy value. For example, an empty string for strings.

Path Parameters

Name
Type
Description

id*

string

Task id

Request Body

Name
Type
Description

assignees

string[]

Assignee id list

followers

string[]

Follower id list

customer

string

Client id

deadline

number

Deadline

desc

string

Description

group

string

The project id to which the task is to be moved

files

string[]

File id list

recurrent

boolean

Boolean

recurrence

Recurrence

Task recurrence details

name

string

Task name

workflowId

string

Workflow id

start

number

Start date

steps

Checklist | ProgressBar

Required when 'stepType' is 'steps' or 'progress'

stepType

string

'none', 'steps' or 'progress'

private

boolean

state

string

Task state name. Required when moving the task to a different project and changing to a different state within that project.

subtasks

string[]

Subtask id list

estimatedTime

number

Estimated task duration in seconds

customFields

object

An object where keys are field names and values are field values.

updateTemplate

boolean

If task is recurrent this field will determine whether to update the details only on the task itself or including the future copies of the task.

{
    activity: TaskActivity,
    task: Task
}

Delete Task

DELETE https://cubicl.io/api/v1/tasks/:id

Deletes the task with given id.

Path Parameters

Name
Type
Description

id*

string

Task id

Add Subtask to Task

POST https://cubicl.io/api/v1/tasks/:id/subtasks

Path Parameters

Name
Type
Description

id*

string

Task ID

Request Body

Name
Type
Description

subtask*

string

The ID of the task to be added as a subtask.

Update Task State

PUT https://cubicl.io/api/v1/tasks/:id/state

Changes the state of a task to the given state. The default states for a project are Pending, Active, Completed, and Suspended. These states are recorded in the system as cb_waiting, cb_active, cb_completed, and cb_suspended, respectively. When using default states, the recorded values must be sent.

Path Parameters

Name
Type
Description

id*

string

Task id

Request Body

Name
Type
Description

value*

string

New task state name.

TaskStateActivity

Create Task Comment

POST https://cubicl.io/api/v1/tasks/:id/activities

Creates a comment on a task.

Path Parameters

Name
Type
Description

id*

string

Task ID

Request Body

Name
Type
Description

content

string

The content of the comment. Either 'content' or 'fileIds' must be provided.

fileIds

string[]

List of file IDs. In order to create a comment with files, you need to upload the files before creating the comment and set their IDs here. Either 'fileIds' or 'content' must be provided.

mentions

Mention[]

List of users mentioned in the comment.

replyToId

string

The ID of the comment you want to reply to.

TaskActivity

Change Task Comment Visibility

PUT https://cubicl.io/api/v1/tasks/:taskId/activities/:activityId

In support requests and tasks shared with your client, you can change the visibility of your comment for your portal client. When comments in email tasks are made visible, the comment is sent as an email.

Path Parameters

Name
Type
Description

taskId*

string

Task ID

activityId*

string

The ID of the activity whose visibility is to be changed.

Request Body

Name
Type
Description

value*

boolean

Determines the visibility of the comment. true makes it visible, false removes the visibility.

Get Task Activities

GET https://cubicl.io/api/v1/tasks/:id/activities

Path Parameters

Name
Type
Description

id*

string

Task id

TaskActivity[]

Data

Task

Details of a task.

{
    _id: string;
    name: string;
    desc: string;
    state: string;
    start: number | null; // Start date
    deadline: number | null;
    assignees: string[]; // Assignee ids
    assignedBy: string; // Owner id
    followers: string[];
    // Ids of the portal users who follow this task if task is shared in
    // the client portal
    portalFollowers?: string[];
    // From 1 to 5. 5 is the highest.
    priority: number;
    // A score to sort same-priority tasks among themselves. 
    // Lowest score is shown at the top.
    priorityScore: number;
    // Project id
    group: string;
    completedAt: number;
    archivedAt?: number | null;
    /* none: Task has no steps
     * steps: Task has a checklist
     * progress: Task has a progress bar
     */
    stepType: 'none' | 'steps' | 'progress';
    // Check below for definitions of these types
    steps?: CheckList | ProgressBar;
    customer: {
        _id: string,
        name: string,
    } | null,
    createdAt: number;
    files: { _id: string }[];
    tags: string[];
    subtasks: string[];
    parent: string | null;
    // This property exists if task is created for an incoming mail
    // An id is created for the email sender
    email?: {
        emailUserId: string,
    };
    // This property exists if task is created for a support request
    // through the Client Portal feature
    support?: {
        portalUser: string, // Id of the client portal user
    };
    private: boolean;
    sharedWithCustomer?: boolean;
    // Exists if task belongs to a workflow
    workflow?: {
        id: string,
        templateId: string,
        isCompleted: boolean,
        taskflowId: string
    };
    estimatedTime?: number; // Duration in seconds
    // If task has custom fields, holds the name and value for each field
    customFields?: {[fieldName: string]: string};
    // If task is recurrent, shows if this is the newest copy
    lastCopy?: boolean;
}

Task Steps

Tasks can have a checklist or a progress bar to indicate the steps / overall progress.

type ProgressBar = {
    completed: number;
    total: number;
}

type CheckList = TaskStep[];

type TaskStep = {
    id: string;
    name: string;
    desc?: string;
    assignees: string[]; // Ids of the step assignees
    /* Task steps are recursive. They can have sub-steps too.
     * If not set, the step has no sub-steps.
     * If 'steps', a property named 'steps' holds sub-steps.
     * If 'progress', this step object has a property named 'total'.
     */
    stepType?: 'steps' | 'progress';
    steps?: CheckList;
    // If 'stepType' is 'progress', this is a number and indicates the total number
    // of steps in the bar. Otherwise, a boolean to indicate completion.
    completed: boolean | number;
    // Set when 'stepType' is 'progress'
    total?: number;
}
    

Recurrence

type Recurrence = {
    type: 'daily' | 'weekly' | 'monthly';
    // Example: Set 3 for task to be copied every 3 days/weeks/months.
    period: number;
    // New copy is created after task deadline or when task is completed
    createWhen: 'after-deadline' | 'completed';
    // If true, recurrence continues. Otherwise, it will pause.
    active: boolean;
    /* 'none': Continues indefinitely
     * 'date': Continues until given date in the 'end' parameter.
     * 'count': Continues until amount of copies set in 'maxCount' parameter
     * are created. The task itself is the first copy. So if, maxCount is 1,
     * no copies will be created.
     */
    stopCondition: 'none' | 'date' | 'count';
    end?: number;
    maxCount?: number;
    // If 'type' is 'weekly' you can set in which days of the week a copy should
    // be created. The list is the days of the week indicating whether that day
    // a copy should be created. Starts with Monday.
    days?: boolean[];
}

Task Activity

Update and progress actions and messages on tasks create task activities.

type TaskActivity = {
    _id: string;
    // Id of the user who did the activity
    user: string;
    // Id of the portal user who created the activity. Exists only when
    // activity is created in the Client Portal by a portal user.
    portalUser?: string;
    // Id of the email sender. Exists when the activity is created due to
    // an incoming mail.
    emailUser?: string;
    type:
        | 'post' // A post (comment) on the task
        | 'update' // Task is updated
        | 'progress' // Task step completed/uncompleted, progress changed
        | 'archive' // Task is archived
        | 'restore' // Task is restored from the archive
        | 'state-change' // Task state is changed
        | 'delete'; // Task is deleted
    // Holds the info about the update. The shape depends on the 'type'
    data?: object;
    // If 'type' is 'post', holds the comment content
    content?: string;
    // If 'type' is 'post', holds the file details
    files?: File[] = [];
    createdAt: number;
    // If activity is a reply to a previous post, keeps the referenced activity id
    replyToId?: string;
    // Whether the activity (post) is shared with a Client Portal user.
    customerCanSee: boolean;
    // List of users mentioned in the post
    mentions: Mention[];
    customFields?: {
        fieldName: string;
        value: string;
    }[];
    // If a task is created from an incoming email
    emailDetails?: EmailDetails;
    // If task is created for an incoming email, posts on the task can be sent
    // as email. This holds the state of the mail.
    mailStatus?: 'not-sent' | 'sending' | 'sent' | 'mail-box-error' | 'error';
}

type Mention = {
    id: string;  // User id
    name: string; // Text used to mention user in the post
}

type EmailDetails = {
    to: EmailPerson[];
    cc: EmailPerson[];
    from: EmailPerson;
}

type EmailPerson = {
    name: string;
    emailAddress: string;
}

Task State

type TaskState = {
    name: string;
    type: 'waiting' | 'active' | 'completed' | 'suspended' | 'cancelled';
    color: string;
    textColor: string;
    isDefault?: boolean;
}

type TaskStateActivity = {
    _id: string;
    // Id of the user who did the activity
    user: string;
    task: string;
    type: 'state-change';
    data: {
        oldState: TaskState;
        newState: TaskState;
    };
}  

Default Task States

If task states are not customized for the project, default states are used. These values are translated into the user's language when shown in the UI. These values are:

State Value
Translation in UI

cb_waiting

Pending

cb_active

Active

cb_completed

Completed

cb_suspended

Suspended

You can check the project object to see whether task states are customized or defaults are being used.

Last updated