# 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

<mark style="color:blue;">`GET`</mark> `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 | <p>'true' to get archived tasks</p><p>'false' to get unarchived tasks</p><p>'all' to get all tasks</p><p>Default is 'false'</p>  |
| recursive  | string | <p>'true' to get tasks in descended projects too</p><p>Leave empty to get tasks only in given project</p><p>Default is empty</p> |
| 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.                         |

{% tabs %}
{% tab title="200: OK List of tasks" %}

<pre class="language-typescript"><code class="lang-typescript"><strong>Task[]
</strong></code></pre>

{% endtab %}

{% tab title="403: Forbidden You don't have the permission to get tasks." %}

```javascript
{ code: 4 }
```

{% endtab %}
{% endtabs %}

## Get Task By Id

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/tasks/:id`

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Task id     |

{% tabs %}
{% tab title="200: OK Task details" %}

```javascript
Task
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission to get the task." %}

```javascript
{ code: 4 }
```

{% endtab %}
{% endtabs %}

## Create Task

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/tasks`

#### Request Body

| Name                                    | Type                     | Description                                                                                                                                                                                                                                        |
| --------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| group<mark style="color:red;">\*</mark> | 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 | <p>If 'stepType' is 'steps', provide steps in CheckList format. Id field is not required. It will be set in the server.</p><p>If 'stepType' is 'progress', provide steps in ProgressBar format.</p><p>If 'stepType' is 'none', don't set this.</p> |
| stepType                                | string                   | <p>'none' for no task steps</p><p>'steps' for checklist</p><p>'progress' for progress bar</p><p>Default is 'none'</p>                                                                                                                              |
| 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<mark style="color:red;">\*</mark>  | 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.                                                                                                                                                                     |

{% tabs %}
{% tab title="200: OK New task details" %}

```javascript
Task
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid operation" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>// Empty response
</strong><strong>// Potential causes:
</strong><strong>// - Invalid project
</strong><strong>// - Invalid parent task
</strong></code></pre>

{% endtab %}

{% tab title="403: Forbidden You don't have the permission" %}

```javascript
{ code: 4 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Task state does not exists" %}

```javascript
{ code: 503 }
```

{% endtab %}
{% endtabs %}

## Update Task

<mark style="color:orange;">`PUT`</mark> `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<mark style="color:red;">\*</mark> | 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. |

{% tabs %}
{% tab title="200: OK Updated task details and task update activity" %}

```javascript
{
    activity: TaskActivity,
    task: Task
}
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission" %}

```javascript
{
    // 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
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid operation" %}

```javascript
// 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
}
```

{% endtab %}
{% endtabs %}

## Delete Task

<mark style="color:red;">`DELETE`</mark> `https://cubicl.io/api/v1/tasks/:id`

Deletes the task with given id.

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Task id     |

{% tabs %}
{% tab title="200: OK Empty response" %}

```javascript
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code: 4 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid operation" %}

```javascript
// 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
}
```

{% endtab %}
{% endtabs %}

## Add Subtask to Task

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/tasks/:id/subtasks`

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Task ID     |

#### Request Body

| Name                                      | Type   | Description                                  |
| ----------------------------------------- | ------ | -------------------------------------------- |
| subtask<mark style="color:red;">\*</mark> | string | The ID of the task to be added as a subtask. |

{% tabs %}
{% tab title="200: OK Empty response" %}

```javascript
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code: 4 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity A task higher in the hierarchy cannot be added as a subtask." %}

```javascript
{ code: 802 }
```

{% endtab %}
{% endtabs %}

## Update Task State

<mark style="color:orange;">`PUT`</mark> `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<mark style="color:red;">\*</mark> | string | Task id     |

#### Request Body

| Name                                    | Type   | Description          |
| --------------------------------------- | ------ | -------------------- |
| value<mark style="color:red;">\*</mark> | string | New task state name. |

{% tabs %}
{% tab title="200: OK Task State Activity" %}

```javascript
TaskStateActivity
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission" %}

```javascript
{ code: 4 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Task state does not exists" %}

```javascript
{ code: 503 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid operation" %}

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

{% endtab %}
{% endtabs %}

## Create Task Comment

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/tasks/:id/activities`

Creates a comment on a task.

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | 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.                                                                                                                                                 |

{% tabs %}
{% tab title="200: OK Task Activity" %}

```javascript
TaskActivity
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code: 4 }
```

{% endtab %}
{% endtabs %}

## Change Task Comment Visibility

<mark style="color:orange;">`PUT`</mark> `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<mark style="color:red;">\*</mark>     | string | Task ID                                                   |
| activityId<mark style="color:red;">\*</mark> | string | The ID of the activity whose visibility is to be changed. |

#### Request Body

| Name                                    | Type    | Description                                                                                        |
| --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| value<mark style="color:red;">\*</mark> | boolean | Determines the visibility of the comment. `true` makes it visible, `false` removes the visibility. |

{% tabs %}
{% tab title="200: OK Empty response" %}

```javascript
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code: 4 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid operation" %}

```javascript
// 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.
```

{% endtab %}
{% endtabs %}

## Get Task Activities

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/tasks/:id/activities`

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Task id     |

{% tabs %}
{% tab title="200: OK Task Activities" %}

```javascript
TaskActivity[]
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission" %}

```javascript
{ code: 4 }
```

{% endtab %}
{% endtabs %}

## Data

#### Task

Details of a task.

```typescript
{
    _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.

```typescript
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

```typescript
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.

```typescript
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

```typescript
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.