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

Task[]

{ code: 4 }

Get Task By Id

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

Path Parameters

Task

{ code: 4 }

Create Task

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

Request Body

Task

// Empty response
// Potential causes:
// - Invalid project
// - Invalid parent task

{ code: 4 }

{ code: 503 }

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

Request Body

{
    activity: TaskActivity,
    task: Task
}

{
    // 4: No permission to update task details
    // 804: No permission to move the task out of the project
    // 805: No permission to move the task into the project
    code: number
}

// Following object or empty response for unknown error
{
    // 403: This update changes the Gantt Chart and you have no permission for that
    // 406: Task in the Gantt Chart must have dates.
    // 503: Task state does not exist
    // 604: Archived tasks cannot be updated
    code: number
}

Delete Task

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

Deletes the task with given id.

Path Parameters

{ code: 4 }

// Following object or empty response for unknown error
{
    // 4: This operation requires to delete subtasks but you have no permission for that
    // 403: This update changes the Gantt Chart and you have no permission for that
    code: number
}

Add Subtask to Task

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

Path Parameters

Request Body

{ code: 4 }

{ code: 802 }

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

Request Body

TaskStateActivity

{ code: 4 }

{ code: 503 }

// Error message
// Potential causes:
// - Archived tasks cannot have their state updated.
// - The task is already in the desired state.

Create Task Comment

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

Creates a comment on a task.

Path Parameters

Request Body

TaskActivity

{ code: 4 }

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

Request Body

{ code: 4 }

// Error message
// Potential causes:
// - Only activities of type "post" can have their visibility changed.
// - Visibility can only be changed for support requests, tasks shared with customers, or email tasks.
// - The visibility of comments created by portal or email users cannot be changed.
// - The visibility of comments made visible in email tasks cannot be removed.

Get Task Activities

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

Path Parameters

TaskActivity[]

{ code: 4 }

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:

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

PreviousProjects NextFiles

Last updated 4 months ago