REST Workbook
Manage workbooks or workflows.
A workbook is a response plan that has been added to a container, while a workbook template is the base object used to create workbooks. When a workbook template is added to a container, a copy of the template is added, which then becomes a workbook.
For information on adding a workbook template to a container, see REST Containers.
In Splunk Phantom 4.5, an alias 'workbook' was added for each 'workflow' REST API. For example /rest/workbook_template
can be used interchangeably with /rest/workflow_template
.
/rest/workbook_template
Create a workbook using /rest/workflow_template
or /rest/workbook_template
.
Syntax
https://<username>:<password>@<host>/rest/workbook_template
Usage details
The "Edit Container" permission is required to add or modify workbooks.
POST
Add a workbook template.
Request parameters
Workbook templates are modified with the following parameters.
Field | Required | Type | Description |
---|---|---|---|
is_default | required | Boolean | Sets the created workbook to be the default case workbook. Removes the default flag from any other workbook. |
name | required | string | The name of the new workbook. |
phases | optional | Array of JSON Objects | Contains an array of phase objects that describe the workflow. See /rest/workbook_phase_template for phase object parameters and /rest/workbook_task_template for task object parameters. |
Example request
Create a workbook with the name "My Workbook" that includes a phase named "My Phase" and a task named "My Task."
curl -k -u admin:changeme https://localhost/rest/workbook_template \ -d '{ "name": "My Workbook", "is_default": false, "phases": [{ "name": "My Phase", "order": 1, "tasks": [{ "name": "My Task", "order": 1, "description": "Investigate the event", "playbooks": [{ "scm": "local", "playbook": "investigate" }, { "scm": "community", "playbook": "04_07_2017 - PhishMe" } ], "actions": ["geolocate ip", "block_ip"] }...] }...] }'
Example response
A successful request will result in a 200 response returning the new workbook Id and success as JSON.
{ "id": 10, "success": true }
/rest/workbook_phase_template
Add a phase to a workbook using /rest/workbook_phase_template
or /rest/workflow_phase_template
.
Syntax
https://<username>:<password>@<host>/rest/workbook_phase_template
Usage details
Be sure to include the template_id
attribute.
POST
Add a phase to an existing workbook template.
Request parameters
A Phase Object describes the stages of life of a case and are composed of multiple tasks.
Field | Required | Type | Description |
---|---|---|---|
name | required | string | The name of the phase. |
order | optional | integer | Specifies where the order the phase is expected to be executed in relative to other phases in the workbook. |
tasks | optional | Array of JSON Objects | Contains an array of task objects that describe the phase. See /rest/workbook_task_template for the task object parameters. |
template_id | optional | integer | May only be passed when adding a phase to an existing template. |
Example request
Add a phase named "My Phase" and a task named "My Task" to template Id 10.
curl -k -u admin:changeme https://localhost/rest/rest/workbook_phase_template \ -d '{ "name": "My Phase", "order": 1, "template_id": 10, "tasks": [ { "name": "My Task", "order": 1, "description": "Investigate the event", "playbooks": [ { "scm": "local", "playbook": "investigate" }, { "scm": "community", "playbook": "04_07_2017 - PhishMe" } ], "actions": [ "geolocate ip", "block_ip" ] }... ] }'
Example response
{ "id": 20, "success": true }
/rest/workbook_task_template
Add a task to an existing phase using /rest/workbook_task_template
or /rest/workflow_task_template
.
Syntax
https://<username>:<password>@<host>/rest/workbook_task_template
Usage details
Be sure to include the phase_id
attribute.
POST
Add a task to an existing phase.
Request parameters
A Task Object indicates what activities should be taken on a case and may include playbooks, Splunk Phantom actions, or manual activities taken by a person.
Field | Required | Type | Description |
---|---|---|---|
actions | required | Array of strings | Array of action names that are expected to be carried out. |
description | required | string | A textual description of the task to be performed. |
playbooks | required | Array of JSON Objects | An array describing what playbook should be run. Each JSON object should contain 2 key-value pairs. They should have an "scm" key where the value is the name of the Source Control repository and a "playbook" key where the value is the name of the playbook within that repository. |
phase_id | optional | integer | May only be passed when adding a task to an existing phase. |
name | required | string | A human friendly name for the task. |
order | optional | integer | Order in which the task is expected to be carried out relative to other tasks in the phase. |
owner | optional | integer or string | Phantom account name or numeric ID of the user or role who is the current owner of the container. |
Example request
Add a task named "My Task" to existing phase Id 20.
curl -k -u admin:changeme https://localhost/rest/workbook_task_template \ -d '{ "name": "My Task", "order": 1, "owner": 2, "phase_id": 20, "description": "Investigate the event", "playbooks": [{ "scm": "local", "playbook": "investigate" }, { "scm": "community", "playbook": "04_07_2017 - PhishMe" } ], "actions": ["geolocate ip", "block_ip"] }'
Example response
A successful request will result in a 200 response returning the new task id and success as JSON.
{ "id": 30, "success": true }
Optional /rest/workbook_phase/ filters
Get the phases of a workbook.
/rest/workflow_phase?_filter_container_id
Syntax
https://<username>:<password>@<host>/rest/workbook_phase?_filter_container_id=<arguments>
GET
Get the phases of a workbook.
Example request
Get the phases of workbook Id 259.
curl -k -u admin:changeme https://localhost/rest/workflow_phase?_filter_container_id=259 -G -X GET
Example response
A successful request returns a 200 response and a JSON object containing the phases for the workbook.
{ "count": 5, "data": [ { "status": 0, "tasks": [ { "status": 0, "files": [], "owner_name": null, "container": 259, "name": "Determine if an incident has occurred", "notified": false, "start_time": null, "suggestions": {}, "modified_time": "2019-05-30T19:06:24.687501Z", "id": 5, "phase": 1, "create_time": "2019-05-30T19:06:24.687190Z", "role": null, "sla_type": "minutes", "sla": null, "owner": null, "end_time": null, "notes": [], "order": 1, "is_note_required": true, "description": "" }, ... ], "container": 259, "name": "Detection", "start_time": null, "modified_time": "2019-05-30T19:06:24.658201Z", "id": 1, "create_time": "2019-05-30T19:06:24.657855Z", "sla_type": "minutes", "sla": null, "order": 1, "end_time": null }, ... { "status": 0, "tasks": [ ... ], "container": 259, "name": "Post Incident Activity", "start_time": "2019-05-30T19:06:25.670935Z", "modified_time": "2019-05-30T19:06:25.672107Z", "id": 5, "create_time": "2019-05-30T19:06:24.745617Z", "sla_type": "minutes", "sla": null, "order": 5, "end_time": null } ], "num_pages": 1 }
REST Vault | RESTDeprecated |
This documentation applies to the following versions of Splunk® Phantom (Legacy): 4.8, 4.9, 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7
Feedback submitted, thanks!