Scripts

Extend the platform with Kotlin scripts — event triggers, API endpoints, and AI agent tools.

What Are Scripts?

Scripts are blocks of Kotlin code that run within the Bosca platform's sandboxed execution environment. They let administrators and platform engineers extend the platform's behavior without deploying separate services or modifying the core codebase. Scripts can respond to platform events, expose custom REST endpoints, implement tools for AI agents, or perform utility tasks on demand.

Every script is managed through the platform's administration interface. You write the code, define its inputs and outputs, connect it to triggers or API routes, and the platform handles compilation, execution, and lifecycle management.

Script Types

Each script has a type that determines how and when it executes. Choosing the right type ensures your script integrates properly with the rest of the platform.

Type	Purpose	How It Runs
General	Utility scripts for administrative tasks, data transformations, or batch operations.	Executed on demand by administrators or invoked by other scripts.
Trigger	React to platform events such as content state changes, user actions, or system events.	Automatically executed when the bound event fires. Can filter by event attributes and control execution order.
Tool	Implement tools that AI agents can invoke during processing. Provide agents with custom capabilities specific to your platform.	Called by the agent runtime when an agent selects the tool based on its description and input schema.
API	Expose custom REST endpoints for external systems, webhooks, or custom integrations.	Accessible via HTTP at a designated URL path. Receives request data and returns a response.
Ephemeral	Temporary scripts for one-time tasks, debugging, or experimentation.	Executed immediately and automatically cleaned up after completion. Useful for ad-hoc administrative tasks.

Script Lifecycle

Scripts move through a straightforward lifecycle from creation to execution:

Create. Define the script with a name, description, type, and the Kotlin source code. Specify input and output schemas if the script accepts parameters or returns structured data.
Compile. Pre-compile the script to validate the code and prepare it for faster execution. Compilation errors are reported immediately so you can fix issues before enabling the script.
Enable. Activate the script so it can be triggered, called via API, or selected by agents. Disabled scripts remain in the system but do not execute.
Execute. The platform runs the script in its sandboxed environment when the appropriate condition is met — an event fires, an API request arrives, or an agent invokes the tool.
Disable or delete. Deactivate a script to stop it from running without removing it, or delete it entirely when it is no longer needed.

Scripts track version information. Each time you edit and save a script, the platform records the change, allowing you to understand the evolution of a script over time.

Trigger Bindings

Trigger scripts are connected to named platform events through trigger bindings. A binding specifies which event the script should respond to, and can include optional filters and execution ordering.

Event names. Each trigger binding targets a specific named event in the platform, such as a content state transition, a user action, or a system lifecycle event.
Filters. Optionally narrow when the trigger fires by specifying filter criteria. For example, a trigger might only fire for content items of a specific type or in a specific collection.
Execution order. When multiple triggers are bound to the same event, the execution order determines which scripts run first. This is important when one trigger depends on the side effects of another.

Trigger bindings are managed separately from the script itself. A single trigger script can be bound to multiple events, and a single event can have multiple trigger scripts bound to it.

Input and Output Schemas

Scripts can define JSON Schema definitions for their input parameters and return values. These schemas serve multiple purposes:

Validation. The platform validates input data against the schema before passing it to the script, preventing runtime errors from malformed data.
Documentation. Schemas describe what data the script expects and what it returns, making it easier for other administrators and integrators to use the script correctly.
Agent integration. For tool-type scripts, the input schema tells AI agents what parameters the tool accepts, enabling agents to construct valid invocations automatically.

API Scripts

API-type scripts are exposed as REST endpoints at /api/v1/s/{key}, where the key is a unique identifier you assign to the script. This makes it possible to:

Receive webhooks from external services and process them with custom logic.
Build lightweight integrations without deploying separate microservices.
Expose custom data transformations or queries as HTTP endpoints.
Create callback URLs for OAuth flows or third-party notifications.

API scripts receive the full HTTP request context — headers, query parameters, and request body — and return a response with a status code, headers, and body. They follow the same sandboxing and permission rules as all other scripts.

API scripts are publicly accessible at their endpoint URL. Use the script's own logic to validate authentication tokens, API keys, or other credentials if the endpoint should not be open to anonymous callers.

Sandboxed Execution

All scripts run in a restricted execution environment that prevents them from accessing unauthorized system resources. The sandbox enforces several constraints:

Restricted class loading. Scripts can only access a curated set of classes and libraries. They cannot load arbitrary Java or Kotlin classes, access the filesystem directly, or open network connections outside of approved APIs.
Platform API access. Scripts interact with the platform through a provided API context that gives them controlled access to content, configuration, storage, and other platform services.
Resource limits. Scripts are subject to execution time limits and memory constraints to prevent a single script from consuming excessive platform resources.

The sandboxing model ensures that scripts can extend the platform's capabilities without compromising its security or stability. Even if a script contains a bug, the sandbox prevents it from causing damage beyond its own execution context.

Script Compilation

Scripts can be pre-compiled to improve execution performance. Compilation translates the Kotlin source code into an optimized form that the platform can execute more quickly. This is especially important for trigger scripts and API scripts that may be invoked frequently.

Compilation also serves as a validation step. If the script contains syntax errors, type mismatches, or references to unavailable classes, the compilation process will report these errors so you can fix them before enabling the script.

Permission Controls

Access to script management is controlled through the platform's group-based permission system. Creating, editing, enabling, and deleting scripts requires appropriate administrative permissions. This ensures that only authorized personnel can modify the executable code that runs within the platform.

Individual scripts can also have their own permission settings, controlling which groups can view, edit, or execute them. This is useful for delegating script management responsibilities to specific teams while maintaining overall security governance.

When building a new script, start with the Ephemeral type to experiment and test your logic. Once the script works as expected, recreate it as the appropriate permanent type (Trigger, Tool, or API) with proper input/output schemas.