Index

This method returns a list of user tasks for the organization.

Method URL
GET /api/v2/user_tasks.json
GET /api/v2/user_tasks.json?page=1&per_page=2

Parameters

Param Type Required Notes
page integer No Displays results based on specified page number (default 1, 1-indexed).
per_page integer No Number of results per page (defaults to 20 results).

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "id": 397,
        "status": 1,
        "source_type": 2,
        "updated_at": "2016-04-02T16:02:11-07:00",
        "task_status_name": "error",
        "description": "Node-0123: Node scan failure",
        "nodes": [
          {
            "id": 62,
            "impacted_date": "2016-04-02 23:02:11.46888",
            "job_id": "1623",
            "meta": false,
            "name": "Z-CSTAR03"
          } //, ...
        ]
    }
]

Show

This method returns details of the user task specified by the user task ID in the URL.

Method URL
GET /api/v2/user_tasks/[user_task_id].json

Example Response

Code Status
200 OK

Example Response JSON

{
    [
        {
            "id": 338,
            "status": 2,
            "source_type": 3,
            "updated_at": "2016-03-17T04:07:15-07:00",
            "task_status_name": "success",
            "description": "Drift detected - Certstore (50 modified) ",
            "nodes": [
              {
                "id": 62,
                "impacted_date": "2016-03-17 11:07:15.214582",
                "job_id": "914",
                "meta": {
                  "node_id": 62,
                  "node_name": "Node-1203",
                  "date_previous": "2016-03-16T11:05:44Z",
                  "date_latest": "2016-03-17T11:06:04Z",
                  "previous_scan_id": 4780,
                  "latest_scan_id": 4826,
                  "diff_hash": "c565518756398587f05a72594b63775f",
                  "stats": {
                    "packages": {
                      "total": 18,
                      "added": 0,
                      "deleted": 0,
                      "updated": 0
                    },
                    "summary": {
                      "total": 1280,
                      "added": 0,
                      "deleted": 0,
                      "updated": 50
                    }
                  }
                },
                "name": "Node-1203"
              }
            ],
            "occurrences": 1,
            "user_id": null,
            "meta": {
              "node_id": 62,
              "node_name": "Node-1203",
              "date_previous": "2016-03-16T11:05:44Z",
              "date_latest": "2016-03-17T11:06:04Z",
              "previous_scan_id": 718,
              "latest_scan_id": 12315,
              "diff_hash": "c565518745678987f05a72594b63775f"
            }
        }
    ]
}

A user task’s status can be one of the following values:

Code Status Description
1 Unassigned The user task is open but has not been assigned to a user.
2 Closed The user task has been closed.
3 Assigned The user task is open and has been assigned to a user.

A user task’s source_type shows which type of object a user task is based on. The source_type field can be one of the following values:

ID Type Description
1 Policy Task Failure The user task was created due to a failing policy.
2 Scan Task Failure The user task was created due to a failure during a scan.
3 Node Difference The user task was created due to a difference in the node (drift).
4 Offline The user task was created because the target node was offline.

Constructing a link to the scan

A link to the scan identified by drift user tasks can be constructed by parsing the YAML in the meta property of the scan and creating a URL with the following format:

https://app.upguard.com/nodes/[meta.node_id]?scan_id=[meta.latest_scan_id]&diff_id=[meta.previous_scan_id]

Closed Tasks

This method allows you to list closed user tasks. Pagination can be applied here in the same manner as on the Index endpoint.

Method URL
GET /api/v2/user_tasks/closed_tasks
GET /api/v2/user_tasks/closed_tasks?page=1&per_page=20

Parameters

Param Type Required Notes
page integer No Displays results based on specified page number (default 1, 1-indexed).
per_page integer No Number of results per page (defaults to 20 results).

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "created_at": "2015-08-19T03:33:33-07:00",
        "description": "Drift detected - Schedtasks (1 modified) Services (5 modified) Files (5 added) Hardware (2 removed) ",
        "grouping_key": "80f9567890ca8856789f647429f8",
        "id": 1,
        "meta": "---\n:node_id: .....",
        "organisation_id": 3,
        "source_type": 3,
        "status": 2,
        "step_id": null,
        "task_status": 2,
        "updated_at": "2015-08-19T03:33:33-07:00",
        "user_id": null
    },
    {
        "created_at": "2015-08-19T03:33:33-07:00",
        "description": "Drift detected - Hotfixes (5 added) Schedtasks (1 removed) Services (2 modified) Files (8 added) ",
        "grouping_key": "65bda09e4965678901636c693722",
        "id": 2,
        "meta": "---\n:node_id: .....",
        "organisation_id": 3,
        "source_type": 3,
        "status": 2,
        "step_id": null,
        "task_status": 2,
        "updated_at": "2015-08-19T03:33:33-07:00",
        "user_id": null
    }
]

Assign

This allows you to assign a user task to a user.

Method URL
POST /api/v2/user_tasks/1/assign?user_id=[user_id]

Parameters

Param Type Required Notes
user_id integer Yes The id of the user to be assigned the user task.

Example Response

Code Status
200 OK

Close

This allows you to close a user task. It optionally allows you to provide a comment when closing the user task.

Method URL
POST /api/v2/user_tasks/1/close

Parameters

Param Type Required Notes
comment_user_id integer No The id of the user making the closing comment.
comment string No The closing comment.

Example Response

Code Status
200 OK

To generate a link to the diff in the UpGuard website, use the following method:

  • Acquire the task in question from the API
  • Parse the meta attribute, which itself contains node_id, latest_scan_id and previous_scan_id attributes.
  • Create a link using those attributes as follows:

https://app.upguard.com/node_groups/nodes/[node_id]?scan_id=[latest_scan_id]&compare_to_scan_id=[previous_scan_id]

Generating Diff JSON

To acquire the diff as JSON from the API, use the same details at the Nodes/Diff endpoint:

https://app.upguard.com/api/v2/nodes/[node_id]diff?scan_id=[previous_scan_id]&compare_scan_id=[latest_scan_id]

Example Response JSON

[
    {
        "created_at": "2015-02-09T16:43:06-08:00",
        "description": "macbook-pro is offline",
        "grouping_key": null,
        "id": 4,
        "meta": null,
        "organisation_id": 2,
        "source_type": 4,
        "status": 1,
        "step_id": 13,
        "task_status": 10,
        "updated_at": "2015-02-11T16:48:36-08:00",
        "user_id": null
    },
    {
        "created_at": "2015-02-16T16:15:50-08:00",
        "description": "The file C:\\Windows\\explorer.exe should exist",
        "grouping_key": null,
        "id": 6,
        "meta": null,
        "organisation_id": 2,
        "source_type": 1,
        "status": 3,
        "step_id": 22,
        "task_status": 9,
        "updated_at": "2015-02-19T22:00:13-08:00",
        "user_id": 4
    }
]
Tags: user tasks