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 admin:changeme 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 admin:changeme 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 admin:changeme 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": "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", "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): 5.1.0, 5.2.1, 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5, 5.3.6, 5.4.0, 5.5.0
Feedback submitted, thanks!