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
}