Labels

This story shows how you can use labels to better categorise and organize tasks. A task can have an unlimited number of labels attached to it, but use of labels is optional. To make this test possible, we have created one project:

Response: HTTP 200, application/json (Hide)

GET /projects/1

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
    "single": {
        "id": 1,
        "class": "Project",
        "url_path": "\/projects\/1",
        "name": "Test Project",
        "completed_on": null,
        "completed_by_id": null,
        "is_completed": false,
        "members": [
            1
        ],
        "category_id": 0,
        "label_id": 0,
        "is_trashed": false,
        "trashed_on": null,
        "trashed_by_id": 0,
        "created_on": 1430164324,
        "created_by_id": 1,
        "updated_on": 1430164324,
        "updated_by_id": 1,
        "body": null,
        "body_formatted": "",
        "company_id": 1,
        "leader_id": 1,
        "currency_id": 2,
        "template_id": 0,
        "based_on_type": null,
        "based_on_id": null,
        "email": "notifications+m2p-fdBFHgE@mail.manageprojects.com",
        "is_tracking_enabled": true,
        "is_client_reporting_enabled": false,
        "budget": null,
        "count_tasks": 0,
        "count_discussions": 0,
        "count_files": 0,
        "count_notes": 0
    },
    "category": null,
    "hourly_rates": {
        "1": 100
    },
    "label_ids": [],
    "task_lists": null
}

Before we create a new task, lets see which labels ship with ActiveCollab by default:

Response: HTTP 200, application/json (Hide)

GET /labels/task-labels

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
[
    {
        "id": 5,
        "class": "TaskLabel",
        "url_path": "\/labels\/5",
        "name": "NEW",
        "updated_on": null,
        "color": "#00B25C",
        "is_default": false,
        "position": 1,
        "is_global": true
    },
    {
        "id": 6,
        "class": "TaskLabel",
        "url_path": "\/labels\/6",
        "name": "CONFIRMED",
        "updated_on": null,
        "color": "#F26522",
        "is_default": false,
        "position": 2,
        "is_global": true
    },
    {
        "id": 7,
        "class": "TaskLabel",
        "url_path": "\/labels\/7",
        "name": "WORKS FOR ME",
        "updated_on": null,
        "color": "#00B25C",
        "is_default": false,
        "position": 3,
        "is_global": true
    },
    {
        "id": 8,
        "class": "TaskLabel",
        "url_path": "\/labels\/8",
        "name": "DUPLICATE",
        "updated_on": null,
        "color": "#00B25C",
        "is_default": false,
        "position": 4,
        "is_global": true
    },
    {
        "id": 9,
        "class": "TaskLabel",
        "url_path": "\/labels\/9",
        "name": "WONT FIX",
        "updated_on": null,
        "color": "#00B25C",
        "is_default": false,
        "position": 5,
        "is_global": true
    },
    {
        "id": 10,
        "class": "TaskLabel",
        "url_path": "\/labels\/10",
        "name": "ASSIGNED",
        "updated_on": null,
        "color": "#FF0000",
        "is_default": false,
        "position": 6,
        "is_global": true
    },
    {
        "id": 11,
        "class": "TaskLabel",
        "url_path": "\/labels\/11",
        "name": "BLOCKED",
        "updated_on": null,
        "color": "#ACACAC",
        "is_default": false,
        "position": 7,
        "is_global": true
    },
    {
        "id": 12,
        "class": "TaskLabel",
        "url_path": "\/labels\/12",
        "name": "IN PROGRESS",
        "updated_on": null,
        "color": "#00B25C",
        "is_default": false,
        "position": 8,
        "is_global": true
    },
    {
        "id": 13,
        "class": "TaskLabel",
        "url_path": "\/labels\/13",
        "name": "FIXED",
        "updated_on": null,
        "color": "#0000FF",
        "is_default": false,
        "position": 9,
        "is_global": true
    },
    {
        "id": 14,
        "class": "TaskLabel",
        "url_path": "\/labels\/14",
        "name": "REOPENED",
        "updated_on": null,
        "color": "#FF0000",
        "is_default": false,
        "position": 10,
        "is_global": true
    },
    {
        "id": 15,
        "class": "TaskLabel",
        "url_path": "\/labels\/15",
        "name": "VERIFIED",
        "updated_on": null,
        "color": "#00B25C",
        "is_default": false,
        "position": 11,
        "is_global": true
    }
]

Now we'll add a task with two labels, one that is already defined and one that is new:

Response: HTTP 200, application/json (Hide)

POST /projects/1/tasks

Payload:

1
2
3
4
5
6
7
{
    "name": "Task #1",
    "labels": [
        "New",
        "Deferred"
    ]
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
    "single": {
        "id": 1,
        "class": "Task",
        "url_path": "\/projects\/1\/tasks\/1",
        "name": "Task #1",
        "assignee_id": 0,
        "delegated_by_id": 0,
        "completed_on": null,
        "completed_by_id": null,
        "is_completed": false,
        "comments_count": 0,
        "attachments": [],
        "labels": [
            {
                "id": 16,
                "name": "Deferred",
                "color": null,
                "is_default": false,
                "is_global": false,
                "position": "12"
            },
            {
                "id": 5,
                "name": "NEW",
                "color": "#00B25C",
                "is_default": false,
                "is_global": true,
                "position": "1"
            }
        ],
        "is_trashed": false,
        "trashed_on": null,
        "trashed_by_id": 0,
        "project_id": 1,
        "is_hidden_from_clients": false,
        "body": "",
        "body_formatted": "",
        "created_on": 1430164324,
        "created_by_id": 1,
        "updated_on": 1430164324,
        "updated_by_id": 1,
        "task_number": 1,
        "task_list_id": 0,
        "position": 1,
        "is_important": false,
        "due_on": null,
        "estimate": 0,
        "job_type_id": 0,
        "total_subtasks": 0,
        "completed_subtasks": 0,
        "open_subtasks": 0
    },
    "subscribers": [
        1
    ],
    "comments": [],
    "reminders": [],
    "subtasks": [],
    "task_list": null,
    "tracked_time": 0,
    "tracked_expenses": 0
}

Labels can have colors. We want to make sure that Deffered tasks are clearly visible in the list of tasks. Lets make it stand out by coloring it to red:

Response: HTTP 200, application/json (Hide)

PUT /labels/16

Payload:

1
2
3
{
    "color": "#FF0000"
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "single": {
        "id": 16,
        "class": "TaskLabel",
        "url_path": "\/labels\/16",
        "name": "Deferred",
        "updated_on": 1430164324,
        "color": "#FF0000",
        "is_default": false,
        "position": 12,
        "is_global": false
    }
}

Task labels are easily updated:

Response: HTTP 200, application/json (Hide)

PUT /projects/1/tasks/1

Payload:

1
2
3
{
    "labels": []
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    "single": {
        "id": 1,
        "class": "Task",
        "url_path": "\/projects\/1\/tasks\/1",
        "name": "Task #1",
        "assignee_id": 0,
        "delegated_by_id": 0,
        "completed_on": null,
        "completed_by_id": null,
        "is_completed": false,
        "comments_count": 0,
        "attachments": [],
        "labels": [],
        "is_trashed": false,
        "trashed_on": null,
        "trashed_by_id": 0,
        "project_id": 1,
        "is_hidden_from_clients": false,
        "body": "",
        "body_formatted": "",
        "created_on": 1430164324,
        "created_by_id": 1,
        "updated_on": 1430164325,
        "updated_by_id": 1,
        "task_number": 1,
        "task_list_id": 0,
        "position": 1,
        "is_important": false,
        "due_on": null,
        "estimate": 0,
        "job_type_id": 0,
        "total_subtasks": 0,
        "completed_subtasks": 0,
        "open_subtasks": 0
    },
    "subscribers": [
        1
    ],
    "comments": [],
    "reminders": [],
    "subtasks": [],
    "task_list": null,
    "tracked_time": 0,
    "tracked_expenses": 0
}

and:

Response: HTTP 200, application/json (Hide)

PUT /projects/1/tasks/1

Payload:

1
2
3
4
5
6
{
    "labels": [
        "Canceled",
        "Wont Fix"
    ]
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
    "single": {
        "id": 1,
        "class": "Task",
        "url_path": "\/projects\/1\/tasks\/1",
        "name": "Task #1",
        "assignee_id": 0,
        "delegated_by_id": 0,
        "completed_on": null,
        "completed_by_id": null,
        "is_completed": false,
        "comments_count": 0,
        "attachments": [],
        "labels": [
            {
                "id": 17,
                "name": "Canceled",
                "color": null,
                "is_default": false,
                "is_global": false,
                "position": "13"
            },
            {
                "id": 9,
                "name": "WONT FIX",
                "color": "#00B25C",
                "is_default": false,
                "is_global": true,
                "position": "5"
            }
        ],
        "is_trashed": false,
        "trashed_on": null,
        "trashed_by_id": 0,
        "project_id": 1,
        "is_hidden_from_clients": false,
        "body": "",
        "body_formatted": "",
        "created_on": 1430164324,
        "created_by_id": 1,
        "updated_on": 1430164325,
        "updated_by_id": 1,
        "task_number": 1,
        "task_list_id": 0,
        "position": 1,
        "is_important": false,
        "due_on": null,
        "estimate": 0,
        "job_type_id": 0,
        "total_subtasks": 0,
        "completed_subtasks": 0,
        "open_subtasks": 0
    },
    "subscribers": [
        1
    ],
    "comments": [],
    "reminders": [],
    "subtasks": [],
    "task_list": null,
    "tracked_time": 0,
    "tracked_expenses": 0
}

In the /projects/:project_id/tasks command, ActiveCollab provides the label_ids property. It is an array of all task labels used in active project tasks, so you don't need to iterate through tasks to see which labels are used:

Response: HTTP 200, application/json (Hide)

GET /projects/1/tasks

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
{
    "tasks": [
        {
            "id": 1,
            "class": "Task",
            "url_path": "\/projects\/1\/tasks\/1",
            "name": "Task #1",
            "assignee_id": 0,
            "delegated_by_id": 0,
            "completed_on": null,
            "completed_by_id": null,
            "is_completed": false,
            "comments_count": 0,
            "attachments": [],
            "labels": [
                {
                    "id": 17,
                    "name": "Canceled",
                    "color": null,
                    "is_default": false,
                    "is_global": false,
                    "position": "13"
                },
                {
                    "id": 9,
                    "name": "WONT FIX",
                    "color": "#00B25C",
                    "is_default": false,
                    "is_global": true,
                    "position": "5"
                }
            ],
            "is_trashed": false,
            "trashed_on": null,
            "trashed_by_id": 0,
            "project_id": 1,
            "is_hidden_from_clients": false,
            "body": "",
            "body_formatted": "",
            "created_on": 1430164324,
            "created_by_id": 1,
            "updated_on": 1430164325,
            "updated_by_id": 1,
            "task_number": 1,
            "task_list_id": 0,
            "position": 1,
            "is_important": false,
            "due_on": null,
            "estimate": 0,
            "job_type_id": 0,
            "total_subtasks": 0,
            "completed_subtasks": 0,
            "open_subtasks": 0
        }
    ],
    "task_lists": [],
    "label_ids": [
        9,
        17
    ],
    "project": {
        "id": 1,
        "class": "Project",
        "url_path": "\/projects\/1",
        "name": "Test Project",
        "completed_on": null,
        "completed_by_id": null,
        "is_completed": false,
        "members": [
            1
        ],
        "category_id": 0,
        "label_id": 0,
        "is_trashed": false,
        "trashed_on": null,
        "trashed_by_id": 0,
        "created_on": 1430164324,
        "created_by_id": 1,
        "updated_on": 1430164324,
        "updated_by_id": 1,
        "body": null,
        "body_formatted": "",
        "company_id": 1,
        "leader_id": 1,
        "currency_id": 2,
        "template_id": 0,
        "based_on_type": null,
        "based_on_id": null,
        "email": "notifications+m2p-fdBFHgE@mail.manageprojects.com",
        "is_tracking_enabled": true,
        "is_client_reporting_enabled": false,
        "budget": null,
        "count_tasks": 1,
        "count_discussions": 0,
        "count_files": 0,
        "count_notes": 0
    },
    "completed_tasks_count": 0
}

When label is deleted:

Response: HTTP 200, application/json (Hide)

GET /labels/17

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "single": {
        "id": 17,
        "class": "TaskLabel",
        "url_path": "\/labels\/17",
        "name": "Canceled",
        "updated_on": 1430164325,
        "color": null,
        "is_default": false,
        "position": 13,
        "is_global": false
    }
}

Response: HTTP 200, text/html

DELETE /labels/17

task details are automatically updated:

Response: HTTP 200, application/json (Hide)

GET /projects/1/tasks/1

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
    "single": {
        "id": 1,
        "class": "Task",
        "url_path": "\/projects\/1\/tasks\/1",
        "name": "Task #1",
        "assignee_id": 0,
        "delegated_by_id": 0,
        "completed_on": null,
        "completed_by_id": null,
        "is_completed": false,
        "comments_count": 0,
        "attachments": [],
        "labels": [
            {
                "id": 9,
                "name": "WONT FIX",
                "color": "#00B25C",
                "is_default": false,
                "is_global": true,
                "position": "5"
            }
        ],
        "is_trashed": false,
        "trashed_on": null,
        "trashed_by_id": 0,
        "project_id": 1,
        "is_hidden_from_clients": false,
        "body": "",
        "body_formatted": "",
        "created_on": 1430164324,
        "created_by_id": 1,
        "updated_on": 1430164325,
        "updated_by_id": 1,
        "task_number": 1,
        "task_list_id": 0,
        "position": 1,
        "is_important": false,
        "due_on": null,
        "estimate": 0,
        "job_type_id": 0,
        "total_subtasks": 0,
        "completed_subtasks": 0,
        "open_subtasks": 0
    },
    "subscribers": [
        1
    ],
    "comments": [],
    "reminders": [],
    "subtasks": [],
    "task_list": null,
    "tracked_time": 0,
    "tracked_expenses": 0
}