After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
REST Custom Function
/rest/custom_function
https://<username>:<password>@<host>/rest/custom_function
Create or view a list of all custom functions.
POST
Create a custom function.
Request parameters
Field | Required | Type | Description |
---|---|---|---|
name | required | string | A unique name per repository that identifies the custom function. |
scm_id | required | string | The ID for an existing repository on the system. |
description | optional | string | Descriptive text for the custom function. This field displays when selecting custom functions inside the playbook editor. |
commit_message | Dependency of a Python field | string | This field is required if the Python field is passed. This message is used for the commit of the changed Python and metadata files to the connected repository. |
python | optional | string | Python code that executes for the custom function when it is included in a playbook. |
<Returned values>
None.
Fields for both creating and updating a custom function
Field | Required | Type | Default | Description |
---|---|---|---|---|
draft_mode | optional | Boolean | true | A flag to mark a custom function as a draft version. This flag allows you to save invalid Python code while draft_mode is set to true .
|
python | optional | string | true | Python code that executes for the custom function when it is included in a playbook. |
description | optional | string | true | Descriptive text for the custom function. This field displays when selecting custom functions inside the playbook editor. |
commit_message | Dependency of a Python field | string | true | This field is required if the Python field is passed. This message is used for the commit of the changed Python and metadata files to the connected repository. |
inputs | optional | JSON object | {} | Inputs are used for configuring the custom function in the playbook editor.
Example value: [ { "description": "fgh", "contains_type" : ["ip"] , "name": "fgh" } ] |
outputs | optional | JSON object | {} | Outputs are used for configuring downstream blocks from the custom function in the playbook editor.
Example value: [ { "data_path": "ip", "description": "This is an ip", "contains_type" : ["ip"], } ] |
Example request and response
This example JSON request shows creating the draft version of a non-draft custom function, and giving that draft version a different description. This request doesn't disable the current custom function, so it doesn't affect any playbooks using this custom function.
JSON request
curl -k -u admin:changeme https://localhost/rest/custom_function \ -d '{ "name": "new_custom_function", "scm_id": 1, "description": "Example description. Can be any text.", "commit_message": "this custom function prints hello world", "python": "print(\"hello world\")" }'
JSON response
{ "warnings": [ ] , "errors": [ ] , '"id": 2, "success": true, "commit_sha": "1ded5f50ac2e2790b3e2869f6e1487ffc4236856" }
The ID passed back in the response is the newly created custom function. commit_sha
is the commit for the new files.
GET
View a list of custom functions.
<Returned values>
None.
Notable parameters
Field | Required | Type | Description |
---|---|---|---|
commit_sha | optional | string | The most recent GIT commit identifier for the custom function. |
disabled | optional | Boolean | Describes whether the custom function is active or inactive. |
draft_mode | optional | Boolean | If you set the draft_mode field to true , you can see your draft mode versions of custom functions. If you set the draft_mode field to false , you can see your non-draft mode custom functions.
|
latest_editor | optional | integer | A foreign key to a PhUser model. This field reflects the last user that edited the custom function. |
name | optional | string | The name of the custom function. This name is the same as the name on the custom function listing page. |
scm | optional | integer | A foreign key to the SCM model. This field is the current repository where the custom function is saved. |
Example request and response
Request to view the list of custom functions.
curl -k -u username:password https://localhost/rest/custom_function/<id> -G -X GET
JSON response
{ "count": 1, "data": [ { "scm": 1, "platform_version": "4.8", "description": "This is a description", "latest_editor": 1, "json_blob_sha": "c7299d2825c823d24d2570bed7f2321bee7113ef", "draft_mode": false, "forked_from": null, "commit_sha": "7e08d23bd11bc3043e0872a58e8ead0722edc3b3", "python_blob_sha": "37422d6dc6e7fee1b05b2a9fc58edceb0a0d069f", "scm_user_name": "", "last_updated_time": "2020-01-01T01:00:00Z", "version": 1, "passed_validation": true, "date_created": "2020-01-01T01:00:00Z", "disabled": false, "id": 1, "custom_function_id": "930b704e669274d0fb9293d1db5bdc5f0c457304", "name": "example_custom_function" } ], "num_pages": 1 }
/rest/custom_function/<id>
https://<username>:<password>@<host>/rest/custom_function/<id>
Update a custom function, or view a list of all custom functions.
POST
Update a custom function.
You can't update the name
or scm_id
fields of an existing custom function. Because you can't update the fields, when you make a POST request, make sure to either match the name
and scm_id
fields in the request body, or don't include the name
and scm_id
fields in the request body in order for it to pass. If you want to change the name
and scm_id
fields of the custom function, you need to create a copy.
<Returned values>
None.
Fields for both creating and updating a custom function
Field | Required | Type | Default | Description |
---|---|---|---|---|
draft_mode | optional | Boolean | true | A flag to mark a custom function as a draft version. This flag allows you to save invalid Python code while draft_mode is set to true .
|
python | optional | string | true | Python code that runs for the custom function when it is included in a playbook. |
description | optional | string | true | Descriptive text for the custom function. This field is shown when selecting custom functions inside the playbook editor. |
commit_message | Dependency of a Python field | string | true | This field is required if the Python field is passed. This message is used for the commit of the changed Python and metadata files to the connected repository. |
inputs | optional | JSON object | {} | Inputs are used for configuring the custom function in the playbook editor.
Example value: [ { "description: "fgh", "contains_type" : ["ip"] , "name": "fgh" } ] |
outputs | optional | JSON object | {} | Outputs are used for configuring downstream blocks from the custom function in the playbook editor.
Example value: [ { "data_path": "ip", "description": "This is an ip", "contains_type" : ["ip"], } ] |
Example request and response
This example JSON request shows creating the draft version of a non-draft custom function, and giving that draft version a different description. This request doesn't disable the current custom function, so it doesn't affect any playbooks using this custom function.
JSON request
curl -k -u username:password https://localhost/rest/custom_function/1 \ -d '{ "description": "Example description. Can be any text.", "draft_mode": true }'
JSON response
{ "warnings": [ ] , "errors": [ ] , '"id": 2, "success": true, "commit_sha": "1ded5f50ac2e2790b3e2869f6e1487ffc4236856" }
The ID passed back in the response is the newly created custom function. commit_sha
is the commit for the new files.
GET
View a single custom function or a list of custom functions.
<Returned values>
None.
Notable parameters
Field | Required | Type | Description |
---|---|---|---|
commit_sha | optional | string | The most recent GIT commit identifier for the custom function. |
disabled | optional | Boolean | Describes whether the custom function is active or inactive. |
draft_mode | optional | Boolean | If you set the draft_mode field to true , you can see your draft mode versions of custom functions. If you set the draft_mode field to false , you can see your non-draft mode custom functions.
|
latest_editor | optional | integer | A foreign key to a PhUser model. This foreign key reflects the last user that edited the custom function. |
name | optional | string | The name of the custom function. This name is the same as the name in the custom function listing page. |
scm | optional | integer | A foreign key to the SCM model. This foreign key is the current repository where the custom function is saved. |
Example request and response
JSON request
curl -k -u username:password https://localhost/rest/custom_function/<id> -G -X GET
Request to view a single custom function.
JSON response
{ "playbooks": [ { "active": true, "draft_mode": false, "name": "toggle_playbook_active", "id": 1 } ], "disabled": false, "scm_user_name": "", "create_time": "2020-01-01T01:00:00Z", "id": 1, "scm_id": 1, "latest_editor": 1, "warnings": [], "commit_sha": "7e08d23bd11bc3043e0872a58e8ead0722edc3b3", "platform_version": "4.8", "version": 10, "passed_validation": true, "inputs": [ { "custom_function": 10, "description": "", "contains_type": [ "*" ], "id": 10, "name": "input_1" } ], "description": "This is a description", "draft_mode": false, "python": "def example_custom_function(input_1=None, **kwargs): return {} ", "outputs": [], "errors": [], "custom_function_id": "930b704e669274d0fb9293d1db5bdc5f0c457304", "name": "example_custom_function", "json_blob_sha": "c7299d2825c823d24d2570bed7f2321bee7113ef", "forked_from": null, "python_blob_sha": "37422d6dc6e7fee1b05b2a9fc58edceb0a0d069f", "date_created": "2020-01-01T01:00:00Z" }
/rest/import_custom_function
POST
Imports a custom function.
Request parameters
Field | Required | Type | Description |
---|---|---|---|
custom_function | Required | String | The base64-encoded, gzipped custom function TAR file that you want to import. |
scm/scm_id | Required | Name or ID of the repository | The repository where the custom function is saved. |
force | Optional | boolean | Set to true to override an existing custom function in the same repository with the same name. |
Example request
Imports a custom function.
curl -k -u username:password https://localhost/rest/import_custom_function \ -d '{ "custom_function": "H4sIAAILU2UC/+2X3U/bMBDA+8xfcSovwEZwnKYhlZCmMWnTNG3TxrSHaarc5EINSRzFDqVD/O87Jyl0TLCXwTTw76FO7Dvfhz9y9fa8vRcfxfkbFCnWg3uBddzWMhaMrp9tv8+4zwdwPngAGm1ETeYHTxO+D4WRBR744ziMQh7FzItC5u9HfGPgePSUSlVetbxXG/ZQj0ftGfdpb623Fp9H/o3zzwMWDIA95Pmv5qI0qrhV7k/j/ykpZmD3wNbOzulC1Md6e7IBxHA4bNtXiobNXJbHIMoUajRNXa66PPiiEehRg8xgqRpYUJLAKEgVaFVgpyhLEJBQolUBWVMmRqoSNM1U0W/3pmrIUZwhCVa5SHCucvocwSxXyWmnT93LmVKnHhxZe6lCbd0AnSNWVn8hpGl9XMg8XzkqNPmh2rZSWstZjl4bV/vzqRXSNPvbzx/e72qspcjlD0FSoGYn5BsFJwzIosqxwNJoekdIVJnJ46bGFFJhyDVh5rpL29XUq/xt3gEcdjk5VCnCaxvQS8zVogvwnSzxTu2W1ga5p2oDJ1qV6+/9jvXqJqepbQa6juv4VWOqhoI6gIvLX93f7HNzR2paOaFppDPtpU1R6a1+zm07x9d2JYSkTSJKwPMEq3a1abPYPE562ckq2bJb0t8stqb6Fe113Mfp7+C5+s/Vf67+e9r1n72+/139x2jb3az/xjxy9d9DcNFVK0mNwuDU3gTDCQw5XcC7bLTL94/8eBIGE+57fhhHbPSMsQljw+e9WlvATFdF3VSmVjsc+wl9TTLOuYg5m81iP+HBOBljjLNozEZZGETBOF7NkqJOatmWBlb9EZacV5HWIjPTguo9CjQTucZ+QJa2qKHOb9/7nr7OWe8if0ym6mJ6hrXukzXyfOYFXkh/maKVlWpp5rQYa1LBcOPS3XUOh8PhcDgcDofD4XA4HA6Hw/GU+AlQtUisACgAAA==", "scm": "local", "force": true }'
Example response
A successful POST returns a success indicator and an import message.
{ "success": true, "message": [ true, "Custom function \"custom_function\" imported" ] }
/rest/custom_function/<id>/export
GET
Exports a custom function.
Example request
Export a custom function.
curl -k -u username:password --output <FILE> https://localhost/rest/custom_function/1/export
Example response
A successful GET returns an x-gzip file to the location set in the --output
flag.
REST Containers | REST Evidence |
This documentation applies to the following versions of Splunk® SOAR (On-premises): 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.2.1, 6.2.2, 6.3.0
Feedback submitted, thanks!