Splunk® Phantom

REST API Reference for Splunk Phantom

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Phantom. Click here for the latest version.
Acrobat logo Download topic as PDF

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
}
Last modified on 31 March, 2021
PREVIOUS
REST Warm standby
  NEXT
RESTDeprecated

This documentation applies to the following versions of Splunk® Phantom: 4.8, 4.9, 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters