Tasks

Get all tasks of a project

This endpoint returns a list of Task resources associated with the project having id "project_id".

GET /api/v2/projects/{project_id}/tasks/

GET /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "facets": {},
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": "Insecure forgotten password and password reset...",
        "priority": 8,
        "problem": "P526",
        "phase": "X1",
        "manually_added_from_library": false,
        "project_specific": false,
        "relevant": true,
        "accepted": true,
        "assigned_to": [],
        "became_relevant": "2016-02-16T16:47:02.997851-05:00",
        "updated": "2020-03-26T22:41:17.922809-04:00",
        "updater": 7,
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": "none",
        "status": "TS2",
        "status_updated": "2020-03-26T22:41:17.922809-04:00",
        "note_count": 0,
        "artifact_proxy": null
    }]
}

Expand Parameters

See the Expand Parameters section for more details.

Parameter Description
text Description field is expanded into content and amendments sub-fields.
status Status field is expanded into id, meaning, icon, name and slug sub-fields.
phase Phase field is expanded into id, name, slug, description and tip sub-fields.
problem Problem field is expanded into id, title, text, cwe, and risk rating sub-fields.
updater Updater field is expanded into id, first name, last name, email, role, and active status sub-fields.
tags Tags field is expanded into library-level & project-level tags. (Requires tags to be included) 
GET /api/v2/projects/1/tasks/?include=tags&expand=text,status,phase,problem,updater,tags HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "facets": {},
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "tags": {
            "library_tags": ["foo", "bar"],
            "project_tags": ["baz"]
        },
        "title": "Secure forgotten password",
        "text": {
            "description": "Insecure forgotten password and password reset...",
            "amendments": []
        },
        "priority": 8,
        "problem": {
            "id": "P526",
            "title": "P526: Weak Password Recovery Mechanism...",
            "text": "It is common for an application...",
            "cwe": [
                {
                    "url": "http://example.com/640",
                    "id": 640,
                    "title": "Weak Password Recovery..."
                }
            ],
            "risk_rating": 7
        },
        "phase": {
            "id": "X1",
            "name": "Requirements",
            "slug": "requirements",
            "description": "Application security requirements...",
            "tip": "One-time tasks that you can verify...",
            "ordinal": 2,
            "active": true,
            "is_custom": false,
            "retain": false,
            "db_id": 1
        },
        "manually_added_from_library": false,
        "project_specific": false,
        "relevant": true,
        "accepted": true,
        "assigned_to": [],
        "became_relevant": "2016-02-16T16:47:02.997851-05:00",
        "updated": "2020-03-26T22:41:17.922809-04:00",
        "updater": {
            "first_name": "Hamish",
            "last_name": "Stout",
            "is_active": true,
            "email": "hamish.stout@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 7
        },
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": "none",
        "status": {
            "id": "TS2",
            "meaning": "TODO",
            "icon": "clock-o",
            "name": "Incomplete",
            "requires_comment": false,
            "slug": "TODO"
        },
        "status_updated": "2020-03-26T22:41:17.922809-04:00",
        "note_count": 0,
        "artifact_proxy": null
    }]
}

Include Parameters

See the Include Parameters section for more details.

Parameter Description
how_tos Includes a list of applicable how-tos.
last_note Includes the last task note.
last_verification Includes the last verification note.
problem Includes the problem that the task is related to.
related Includes a list of related tasks.
tags Includes a list of tags associated to the task (both library & project).
regulation_sections Includes a list of regulation sections to which this task belongs.
references Includes a list of task references linked to this task.
training Includes a list of training courses/modules linked to this task.
reason_for_inclusion Includes the reason for a task's inclusion within a project. 
GET /api/v2/projects/1/tasks/?include=last_note,last_verification,tags,related,problem,how_tos,references,training,reason_for_inclusion HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "facets": {},
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": "Insecure forgotten password and password reset...",
        "priority": 8,
        "phase": "Requirements",
        "last_note": {
          "automatic": false,
          "text": "Task Note",
          "id": 2,
          "created": "2018-02-21T15:09:26.321072-05:00",
          "updater": "admin@example.com",
          "updated": "2018-02-21T15:09:26.321072-05:00"
        },
        "last_verification": {
          "id": 2,
          "automatic": false,
          "created": "2018-02-21T15:09:38.748141-05:00",
          "status": "pass",
          "finding_ref": "Verification Reference",
          "updated": "2018-02-21T15:09:38.748141-05:00",
          "updater": "admin@example.com"
        },
        "manually_added_from_library": false,
        "project_specific": false,
        "relevant": true,
        "accepted": true,
        "assigned_to": [],
        "became_relevant": "2016-02-16T16:47:02.997851-05:00",
        "updated": "2015-06-16T19:37:44.710100Z",
        "updater": 7,
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": "pass",
        "status": "TS2",
        "status_updated": null,
        "note_count": 2,
        "artifact_proxy": null,
        "tags": ["tag1", "tag2"],
        "related": [
            {
                "id": "T227",
                "phase": "Testing",
                "title": "Verify that application's access to database is restricted",
                "url": "http://example.com/bunits/test-bu/codebot/bug-fix-81028-rc3/tasks/phase/testing/2-T227"
            },
            {
                "id": "T14",
                "phase": "Architecture & Design",
                "title": "Enforce the Principle of Least Privilege",
                "url": "http://example.com/bunits/test-bu/codebot/bug-fix-81028-rc3/tasks/phase/architecture-design/2-T14"
            }
        ],
        "problem": {
            "id": "P526",
            "title": "P526: Weak Password Recovery Mechanism...",
            "text": "It is common for an application...",
            "cwe": [
                {
                    "url": "http://example.com/640",
                    "id": 640,
                    "title": "Weak Password Recovery..."
                }
            ],
            "risk_rating": 7
        },
        "how_tos": [
            {
                "id": "I131",
                "title": "Manually with browser",
                "slug": "test-account-lockout-manually-browser",
                "url": "http://a7069ccda519b00c4/....",
                "text": "1. Open your web browser ..."
            }
        ],
        "regulation_sections": [
            {
                "description": "Denial of service (DoS) protection and working in a degraded mode during DoS attacks.",
                "id": "RS1026",
                "name": "CR2.7 (L3 and higher)",
                "regulation_id": "CR45",
                "regulation_name": "ANSI/ISA 62443-4-2"
            },
            {
                "description": "Denial of service (DoS) protection and working in a degraded mode during DoS attacks.",
                "id": "RS642",
                "name": "SR2.7 (L3 and higher)",
                "regulation_id": "CR39",
                "regulation_name": "ANSI/ISA 62443-3-3"
            }
        ],
        "references": [
            {
              "id": 10,
              "issue_tracker_connection": 1,
              "reference": "47300",
              "name": "US451",
              "link": "https://sdetest.atlassian.net/rest/api/2/issue/47300"
            }
        ],
        "training": [
            {
              "title": "OWASP Top 10 2013",
              "id": "TR1",
              "modules": [
                  {
                     "title": "Cross-site request forgery (CSRF)",
                     "id": "M5",
                     "link": "/training/module/05_CSRF/",
                     "completed": false
                  },
                  {
                     "title": "Broken authentication and session management",
                     "id": "M7",
                     "link": "/training/module/07_Broken_Auth/",
                     "completed": true
                  }
              ]
            },
            {
              "title": "Development",
              "id": "TR6",
              "modules": [
                  {
                     "title": "Software Development, Operation, Maintenance & Disposal",
                     "id": "M8",
                     "link": "/training/module/08_Software_dev/",
                     "completed": true
                  }
              ]
            }
        ],
        "reason_for_inclusion": {
            "reason": "problem_match_and_task_match",
            "explanation": "This task's rules are satisfied by any of the following block(s) of survey answers",
            "relevant_rules": [
                [
                    {
                    "id": "A734",
                    "display_text": "Changes to authentication",
                    "negated": false,
                    "hidden": true,
                    "section_slug": null,
                    "subsection_id": null,
                    "question_id": null,
                    "url": null
                    },
                    {
                    "id": "A758",
                    "display_text": "Features and Functions > Authentication > Authentication Features > Has direct or third party authentication for end users, devices or nodes",
                    "negated": false,
                    "hidden": false,
                    "section_slug": "app-features",
                    "subsection_id": "Q199",
                    "question_id": "Q120",
                    "url": "http://example.com/bunits/test-bu/gigasrc/version-8844-rc2/tasks/survey/questions/app-features/Q199/"
                    }
                ]
            ]
        }
    }]
}

Filter Parameters

Tasks can be filtered by their relevance and whether or not they have been accepted into a project by a project lead. If no filters are passed, we default to returning accepted tasks to match with the list shown in the web application.

Parameter Expected values Description Custom Field Lookup support
accepted true, false Filter by task's accepted state supports __in only
assigned_to email Filter tasks by assigned user's email/username Yes
category string Filter by category name (internal machine tag names) Yes
library_task_id standard item id (T21) Filter by library task id Yes
phase phase slug (development, architecture-design) Filter by phase Yes
priority priority value (1-10) Filter by task priority Yes
relevant true, false Filter by task relevance No
regulation regulation item ID (REG53) Filter tasks by regulation they beyond to Yes
risk_relevant true, false Filter by task risk policy relevance No
source default, custom, manual, project Filter by task source (builtin task, custom task, manually added library task, project specific task) supports __in only
status status item id (TS1) Filter by task status Yes
tag tag name Filter by tags on task (standard and task level tags). No
verification no_dynamic, no_static, pass, partial, fail, none Filter by task verification status No

The follow table defines how the accepted and relevant fields affect project tasks.

accepted relevant Result
false false Task is no longer part of the project.
true false Task is part of the project, but not relevant. Will be flagged for removal by the 'new content updates' widget.
false true Task is not part of the project, but is relevant. Will be flagged for addition by the 'new content updates' widget.
true true Task is part of the project and relevant, the usual case. 
GET /api/v2/projects/1/tasks/?accepted=true&relevant=false HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "facets": {},
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": "Insecure forgotten password and password reset...",
        "priority": 8,
        "problem": "P526",
        "phase": "Requirements",
        "manually_added_from_library": false,
        "project_specific": false,
        "relevant": false,
        "accepted": true,
        "assigned_to": [],
        "became_relevant": "2016-02-16T16:47:02.997851-05:00",
        "updated": "2020-03-26T22:41:17.922809-04:00",
        "updater": 7,
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": "none",
        "status": "TS2",
        "status_updated": "2020-03-26T22:41:17.922809-04:00",
        "note_count": 0,
        "artifact_proxy": null
    }]
}

Facets Parameter

Tasks can return facets that correspond to properties of tasks being queried. Currently, the Tasks endpoint performs basic faceting: it shows relevant phases and the number of tasks within them based on current query filters. The parameter accepts either include or only as its acceptable values. If no facets parameter is provided, an empty facets object is returned. Facets respect all filters applied to the query, including search.

Facets Param Value Description
include Facets object is computed
only Facets object is computed, results are not returned 
GET /api/v2/projects/1/tasks/?facets=only&accepted=true&relevant=false HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "facets": {
        "phases": {
            "development": 15,
            "requirements": 22,
            "architecture-design": 10,
            "testing": 42,
            "deployment": 1
        }
    },
    "results": []
}

Get a Specific Task

This endpoint retrieves a single Task resource, as specified by the id parameter.

GET /api/v2/projects/{project_id}/tasks/{task_id}/

GET /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "accepted": true,
    "manually_added_from_library": false,
    "project_specific": false,
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": [
        {
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "email": "admin@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 1
        }
    ],
    "became_relevant": "2016-02-16T16:47:02.997851-05:00",
    "text": "Insecure forgotten password.",
    "id": "1-T2",
    "library_task_created": "2010-10-20T17:46:50Z",
    "library_task_updated": "2015-05-07T18:58:26.732000Z",
    "note_count": 0,
    "phase": "Requirements",
    "priority": "8",
    "problem": "P526",
    "relevant": true,
    "status": "TS2",
    "status_updated": "2020-03-26T22:41:17.922809-04:00",
    "task_id": "T2",
    "title": "Secure forgotten password",
    "updated": "2020-03-26T22:41:17.922809-04:00",
    "updater": 7,
    "url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
    "verification_status": "none"
}

Create a New Project Specific Task

Creates a new Task resource that is project-specific.

POST /api/v2/projects/{project_id}/tasks/

URL Parameters

Parameter Description
project_id The id of the project the new task belongs to

Payload

Fields Required Description
artifact_proxy No Arbitrary string which identifies a synchronized Issue Tracker issue.
assigned_to No A list of emails for users that belong to the project.
phase Yes The id of a phase.
priority Yes The priority value from 0-10.
problem No The id of a problem applicable to the project. Defaults to the Always Applicable problem if unspecified.
status No The id of a status.
text Yes The description of the new task.
title Yes The title of the new task.
tags No A list of tags for the task. 
POST /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": ["admin@example.com"],
    "phase": "X1",
    "priority": 9,
    "problem": "P526",
    "status": "TS1",
    "tags": ["tag1", "tag2"],
    "text": "Task Description",
    "title": "Project Specific Task"
}

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "accepted": true,
    "manually_added_from_library": false,
    "project_specific": true,
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": [
        {
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "email": "admin@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 1
        }
    ],
    "became_relevant": "2016-02-16T16:47:02.997851-05:00",
    "text": "Task Description",
    "id": "1-PT1",
    "library_task_created": "2015-05-07T18:58:26.732000Z",
    "library_task_updated": "2015-05-07T18:58:26.732000Z",
    "note_count": 0,
    "phase": "X1",
    "priority": "9",
    "problem": "P526",
    "relevant": true,
    "status": "TS1",
    "status_updated": null,
    "tags": ["tag1", "tag2"],
    "task_id": "PT1",
    "title": "Project Specific Task",
    "updater": 7,
    "updated": "2015-05-07T18:58:26.732000Z",
    "url": "http://example.com/.../1-PT1",
    "verification_status": "none"
}

Create a new Task from an existing Library Task

Add a Library Task to a project. Only library tasks that aren't applicable to a project can be added.

POST /api/v2/projects/{project_id}/tasks/

URL Parameters

Parameter Description
project_id The id of the project the new task belongs to

Payload

Fields Required Description
artifact_proxy No Arbitrary string which identifies a synchronized Issue Tracker issue
assigned_to No A list of emails for users that belong to the project
status No The id of a status
task_id Yes The id of the library task to add to the project.
tags No A list of tags that will be added to this task for this project only. 
POST /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "task_id": "T21"
}

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "accepted": true,
    "manually_added_from_library": true,
    "project_specific": false,
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": [
        {
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "email": "admin@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 1
        }
    ],
    "became_relevant": "2016-02-16T16:47:02.997851-05:00",
    "text": "Task Description",
    "id": "1-T21",
    "library_task_created": "2015-05-07T18:58:26.732000Z",
    "library_task_updated": "2015-05-07T18:58:26.732000Z",
    "note_count": 0,
    "phase": "X1",
    "priority": "8",
    "problem": "P712",
    "relevant": false,
    "status": "TS1",
    "status_updated": null,
    "task_id": "T21",
    "title": "Ensure Confidential Data Is Sent Over an Encrypted Channel",
    "updater": 7,
    "updated": "2015-05-07T18:58:26.732000Z",
    "url": "http://example.com/.../1-T21",
    "verification_status": "none"
}

Update a Specific Task

Updates a single Task resource, as specified by the project and task id parameters.

PATCH /api/v2/projects/{project_id}/tasks/{id}/

URL Parameters

Parameter Description
project_id The id of the project this task belongs to
id The id of the task to modify

Payload

Fields Required Description
artifact_proxy No Arbitrary string which identifies a synchronized Issue Tracker issue.
assigned_to No A list of emails for users that belong to the project.
phase No The id of a phase. Available only if the updated task is a project specific task.
priority No The priority value from 0-10. Available only if the updated task is a project specific task.
problem No The id of a problem applicable to the project. Available only if the updated task is a project specific task.
status No The id of a status.
status_note No Create a note related to the status change.
tags No A list of tags that will be set for this task for this project only.
text No The description of the task. Available only if the updated task is a project specific task.
title No The title of the task. Available only if the updated task is a project specific task. 
PATCH /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": ["user1@example.com", "user2@example.com"],
    "problem": "P526",
    "status": "TS1",
    "tags": ["tag1", "tag2"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "accepted": true,
    "manually_added_from_library": false,
    "project_specific": false,
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": [
        {
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "email": "admin@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 1
        }
    ],
    "became_relevant": "2016-02-16T16:47:02.997851-05:00",
    "text": "Insecure forgotten password.",
    "id": "1-T2",
    "library_task_created": "2010-10-20T17:46:50Z",
    "library_task_updated": "2015-05-07T18:58:26.732000Z",
    "note_count": 0,
    "phase": "X1",
    "priority": "8",
    "problem": "P526",
    "relevant": true,
    "status": "TS1",
    "status_updated": "2020-03-26T22:41:17.922809-04:00",
    "task_id": "T2",
    "tags": ["tag1", "tag2"],
    "title": "Secure forgotten password",
    "updated": "2020-03-26T22:41:17.922809-04:00",
    "updater": 7,
    "url": "http://example.com/.../1-T2",
    "verification_status": "none"
}

Delete a Task

Delete a single Task resource, as specified by the project and task id parameters.

Only manually added library tasks and project specific tasks may be deleted.

DELETE /api/v2/projects/{project_id}/tasks/{id}/

URL Parameters

Parameter Description
project_id The id of the project this task belongs to
id The id of the task to delete 
DELETE /api/v2/projects/2/tasks/2-T21/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 204 NO CONTENT

results matching ""

    No results matching ""