API Custom Scripts

Custom Scripts Resource

• Methods
• Payload model
• List scripts
• Get a script
• Create a script
• Update a script
• Delete a script
• See also

Methods

The resource wraps the /api/v1/library/custom-scripts endpoint and exposes five methods:

Method	Description	Returns
list()	All custom scripts	PayloadList[CustomScriptPayload]
get(id)	A single script by ID	CustomScriptPayload
create(...)	Create a script	CustomScriptPayload
update(id, ...)	Update an existing script	CustomScriptPayload
delete(id)	Delete a script	None

Payload model

Methods return a CustomScriptPayload with these key attributes:

Attribute	Type	Description
id	str	The library item ID (UUID)
name	str	Display name
active	bool	Whether the script is active
execution_frequency	str	How often the script runs (see below)
script	str	The script content
remediation_script	str	The remediation script content (may be empty)
restart	bool	Whether to restart after running
show_in_self_service	bool	Whether the script appears in Self Service
self_service_category_id	str | None	Self Service category ID, when shown

Execution frequency

execution_frequency accepts the ExecutionFrequency enum:

ExecutionFrequency.ONCE            # "once"
ExecutionFrequency.EVERY_15_MIN    # "every_15_min"
ExecutionFrequency.EVERY_DAY       # "every_day"
ExecutionFrequency.NO_ENFORCEMENT  # "no_enforcement"

List scripts

Listed scripts are returned in a PayloadList with count and results properties.

with CustomScriptsResource(config) as scripts:
    for script in scripts.list().results:
        print(f"{script.id}  {script.name}  ({script.execution_frequency})")

Get a script

# Gets a single script and prints the audit script content
with CustomScriptsResource(config) as scripts:
    script = scripts.get("ae492437-c35f-46a3-bd0b-21188a69dfb1")
    print(script.script)

Create a script

At minimum, provide a name and the script content. Add a remediation_script to pair an audit script with its fix, and set execution_frequency to control how often it runs.

The create method returns the created script, including the id.

audit = """\
#!/bin/sh
[ -f /Library/Example/flag ] || exit 1
"""

remediation = """\
#!/bin/sh
touch /Library/Example/flag
"""

with CustomScriptsResource(config) as scripts:
    created = scripts.create(
        name="Ensure example flag",
        script=audit,
        remediation_script=remediation,
        active=True,
        execution_frequency=ExecutionFrequency.EVERY_DAY,
    )
    print(f"Created {created.name} ({created.id})")

Showing a script in Self Service

To surface a script in Self Service, set show_in_self_service=True and supply a self_service_category_id. Look up category IDs with Self Service Categories.

with CustomScriptsResource(config) as scripts:
    scripts.create(
        name="Reset printers",
        script="#!/bin/sh\n/usr/bin/lpadmin -x ...\n",
        execution_frequency=ExecutionFrequency.NO_ENFORCEMENT,
        show_in_self_service=True,
        self_service_category_id="ae492437-c35f-46a3-bd0b-21188a69dfb1",
        self_service_recommended=True,
    )

Important

create() and update() raise ValueError if:

• execution_frequency is NO_ENFORCEMENT but show_in_self_service is not set
• show_in_self_service is True but no self_service_category_id is provided

Update a script

Pass only the id and the fields you want to change. update returns the full updated script object.

with CustomScriptsResource(config) as scripts:
    updated = scripts.update(
        "ae492437-c35f-46a3-bd0b-21188a69dfb1",
        active=False,
    )
    print(f"Updated {updated.name} ({updated.id})")
    print(f"active={updated.active}")

Delete a script

Deleting a script only requires the id and does not return anything.

with CustomScriptsResource(config) as scripts:
    scripts.delete("ae492437-c35f-46a3-bd0b-21188a69dfb1")

See also

• Custom Scripts — the on-disk repository format for scripts.
• Self Service Categories — find category IDs.