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 requiredstringA unique name per repository that identifies the custom function.
scm_id requiredstringThe ID for an existing repository on the system.
description optionalstringDescriptive text for the custom function. This field displays when selecting custom functions inside the playbook editor.
commit_message Dependency of a Python fieldstringThis 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 optionalstringPython 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 optionalBooleantrueA 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 optionalstringtruePython code that executes for the custom function when it is included in a playbook.
description optionalstringtrueDescriptive text for the custom function. This field displays when selecting custom functions inside the playbook editor.
commit_message Dependency of a Python fieldstringtrueThis 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 optionalJSON object{}Inputs are used for configuring the custom function in the playbook editor.

Example value: 

 [ { "description":
"fgh",
"contains_type"
:  ["ip"] ,
"name":  "fgh"
} ]
outputs optionalJSON 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 optionalstringThe most recent GIT commit identifier for the custom function.
disabled optionalBooleanDescribes whether the custom function is active or inactive.
draft_mode optionalBooleanIf 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 optionalintegerA foreign key to a PhUser model. This field reflects the last user that edited the custom function.
name optionalstringThe name of the custom function. This name is the same as the name on the custom function listing page.
scm optionalintegerA 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 optionalBooleantrueA 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 optionalstringtruePython code that runs for the custom function when it is included in a playbook.
description optionalstringtrueDescriptive text for the custom function. This field is shown when selecting custom functions inside the playbook editor.
commit_message Dependency of a Python fieldstringtrueThis 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 optionalJSON object{}Inputs are used for configuring the custom function in the playbook editor.

Example value: 

 [ { "description:
"fgh",
"contains_type"
:  ["ip"] ,
"name":  "fgh"
} ]
outputs optionalJSON 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 optionalstringThe most recent GIT commit identifier for the custom function.
disabled optionalBooleanDescribes whether the custom function is active or inactive.
draft_mode optionalBooleanIf 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 optionalintegerA foreign key to a PhUser model. This foreign key reflects the last user that edited the custom function.
name optionalstringThe name of the custom function. This name is the same as the name in the custom function listing page.
scm optionalintegerA 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_functionRequiredStringThe base64-encoded, gzipped custom function TAR file that you want to import.
scm/scm_idRequiredName or ID of the repositoryThe repository where the custom function is saved.
forceOptionalbooleanSet 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.