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.