.md

Scripts in the Console

The Console's file editor knows dcupl script files: it gives them the script typings for autocomplete and a Run panel that executes the file against the application loaded in your browser, in the mode you pick, with a mock input. You see the result, the console output and the duration — without deploying anything.

Which files count as scripts

Every .js file in the project except workflow scripts (*.dcupl-workflow-script.js) — the loader's script, operator and transformer resources all point at .js files. Such a file opens as JavaScript with the SDK's script context (script_type, dcupl, request, options, query, item, items, …) loaded as an extra typings lib, so the editor completes the facade and flags unknown names. Whether a loader resource actually references the file is what the Run panel finds out and tells you.

The Run panel

Open a script file and click the Run (play) button in the editor toolbar. The panel docks to the right of the editor.

Instance

The panel runs against the application the Explorer has loaded in this tab. When nothing is loaded yet, pick an application from dcupl.lc.json and click Load; the panel reports Runs against the loaded application · N models once it is ready. An application loaded on the v1 SDK (chosen in its run settings) cannot run scripts — load one on v2.

Loader resource

The panel looks the open file up in dcupl.lc.json:

  • a script or operator resource references it — the panel shows the kind and the key the loader registers it under
  • no resource references it — the panel runs the file under the key you type and offers Add resource, which appends { url, type: 'script', scriptKey, tags: [] } to dcupl.lc.json so the loader (and a deployed instance) registers it too, unless the application selects resources by tags (below)
  • a transformer resource — transformers run inside the loader while data loads; they have no run mode here

The key field proposes a key from the file name: orders-summary.js → orders_summary (dcupl generate script keeps the hyphen: orders-summary). Change it before Add resource if a template already names the key.

The new entry has no tags. If the application has resourceTags, the loader skips it (no-tags), an endpoint that names the key reports EndpointScriptMissing on a deployed instance, and this panel still shows the resource as declared: it matches on the file, not on tags. Give the entry one of the application's tags in the loader form.

Mode and mock input

Choose the mode and fill the input it needs. The fields are JSON; Load buttons pull real rows from the loaded application.

Mode Input Runs through
endpoint request (an EndpointScriptRequest: method, path, params, query, body, headers) and options dcupl.scripts.executeEndpoint — the script sees the SDK's read-only facade, exactly as on a runner
script options, what dcupl.scripts.execute(key, options) passes dcupl.scripts.execute
operator query (the condition) and item — pick a model and an item key, or paste JSON The script controller, with the query and item the query engine would pass
sort options (sort.script.options) and items — load the first N items of a model, or paste JSON The script controller, with the options and items the sort pipeline would pass

The mock input is kept per file in your browser's local storage; Reset input restores the defaults of the current mode.

Starters

Insert starter puts a template for the chosen mode into the file — a script_type branch with the mode's parameters in scope and a throw for every other mode. An empty file suggests it. A file declared as an operator resource gets the operator-file starter instead (such a file returns the operator function itself). From the command line, dcupl generate script --mode <endpoint|script|operator|sort> writes the same starters and registers the file in dcupl.lc.json (see Scaffolding).

Run and result

Run executes the file. The panel shows:

  • Result — the return value as JSON in a read-only editor (for endpoint, this is the response body a runner would send)
  • Error — the error's name and message, with the line in your file when it can be mapped
  • Console — every console.log/info/warn/error/debug line the script wrote
  • the duration

A run in the browser uses the plain SDK compiler, not the runner's sandbox: fetch, timers and browser globals work here but not on a deployed instance. Keep endpoint scripts to the facade and the request so the panel and the runner agree — the limits are listed in Scripts and script modes.

From a script to an endpoint

  1. Write the script and run it here in endpoint mode with a representative request.
  2. Make sure the loader registers it: Add resource (or a type: 'script' entry of your own), plus one of the application's tags on the entry when the application has resourceTags (the loader form's Tags field). dcupl generate script and dcupl generate api also write the entry with tags: [].
  3. Declare it in an API template's Endpoints section and deploy — see Scripted endpoints. dcupl generate api --name orders-api --endpoint "GET orders/:id=order-detail" writes such a template from the command line.
  4. Call it from the instance tester or with cURL.