Developer Documentation

PSScript

PSScript is the small, sandboxed scripting language built into the ParadicShift platform. You write it inside workflow steps to create and persist data, branch on inputs, call other processes, talk to AI models, send mail, and route the workflow onward — all without leaving the designer.

What is PSScript?

Every automation step in a ParadicShift process can run a PSScript program. The script is compiled once to a compact bytecode and then executed by an in-memory virtual machine each time the step fires. Scripts never touch the host machine directly: all side effects — database writes, mail, HTTP, AI calls — go through a controlled host API, which keeps execution safe and portable across the platform's cloud instances.

Tiny surface

A handful of keywords and twelve system objects — learnable in an afternoon.

Data-first

First-class entities, GIS geometry, multilingual text and a fluent query builder.

Sandboxed

No file or network access of its own — every effect is mediated by the host.

Reversible

An optional rollback block lets a step undo itself if the workflow fails.

A first script

The smallest valid program is a single main block:

minimal.pss

main {
    context$.log("Hello from PSScript.");
}

A more representative step creates an entity, persists it, exposes a value to later steps, and routes the workflow forward:

main {
    var order = PSEntity("com.domain.commerce.Order");
    order.identifier("ORD-2024-001");
    order.val("customerId", param$["customerId"]);
    order.val("total", 149.99);
    order.text("status", "en", "Pending");
    data$.persist(order);

    output$["orderId"] = "ORD-2024-001";
    router$.allow("payment_connector");
}

rollback {
    context$.log("Order creation rolled back.");
}

How a script runs

Source text passes through four stages before producing side effects. Each stage reports precise line:col errors, so authoring mistakes are caught at compile time rather than mid-run.

Lexer Tokens

Parser AST

Compiler Bytecode

VM Side effects

Compilation happens once. The resulting bytecode can be re-run many times without re-parsing, which keeps high-volume steps fast.

Program structure

A script has one required and one optional top-level block:

Block	Required	Runs when
`main { … }`	Yes	The workflow step executes normally.
`rollback { … }`	Optional	The workflow compensates / unwinds a previously completed step.

Shorthand If a file contains no main or rollback keyword, the whole file is treated as the body of an implicit main block.

Where to go next

The reference is split into four focused chapters:

Language reference	Comments, literals, variables, operators, control flow and error handling.
System objects	The twelve $ objects: context$, data$, workflow$, ai$ and more.
Entities & queries	PSEntity, multilingual text, GIS geometry and the PSEntityQuery builder.
Examples	Complete, runnable scripts for common workflow patterns.