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

NameTypeDescription

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

NameTypeDescription

id*

string

Task id

Task

Create Task

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

Request Body

NameTypeDescription

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

NameTypeDescription

id*

string

Task id

Request Body

NameTypeDescription

assignees

string[]

Assignee id list

followers

string[]

Follower id list

customer

string

Client id

deadline

number

Deadline

desc

string

Description

group

string

Project id

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

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

NameTypeDescription

id*

string

Task id

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

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 ValueTranslation 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.

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

Last updated