A pipelet script is the script a pipeline's Script node runs. Its header comment declares the dictionary keys it reads and writes, and the pipeline calls its execute function, which returns PIPELET_NEXT or PIPELET_ERROR
Sandbox 01
version2
Calculate.ds
Global scopepdict. completes its keys first with their type and description, Go to Declaration lands on the key in the header, and execute must return PIPELET_NEXT or PIPELET_ERRORThe header
/**
* Totals the basket for the checkout pipeline
*
* @input Basket : dw.order.Basket The current basket
* @output Total : Number
*/
importPackage(dw.system);
function execute(pdict : PipelineDictionary) : Number {
pdict.Total = pdict.Basket.productLineItems.size();
return PIPELET_NEXT;
}- The header is a
/* */comment before the first statement.//comments and'use strict'may come before it - Each line reads
@input Name : Type description. The tag ignores case, the colon is required, and the description is optional - A type is a qualified name such as
dw.order.Basket, a simple name the file imports, or a primitive, with optional<...>and[] - A line that starts with
*-is turned off - A name declared twice counts with its later line
executeis a top-level function, orexports.executein a file with a header
pdict
In execute(pdict), the first parameter is the pipeline dictionary: the header keys first, then the members of dw.system.PipelineDictionary such as CurrentRequest and CurrentForms
| Feature | In a pipelet |
|---|---|
Completion after pdict. | The header keys first, in header order, with input or output, the description and the type |
Go to Declaration on pdict.Basket | The key in the header |
| Quick documentation | Basket: dw.order.Basket, the description, "An input of the pipelet: the pipeline sets pdict.Basket before execute runs." and the header line |
| Types | String, Number and Boolean as primitives, simple names through the file's import calls, an unknown type as any |
| Colors | Pipelet › Header tag and Dictionary key in Settings › Editor › Color Scheme › Digital Script |
| Folding | The header folds to /** @input Basket, @output Total */ |
| File Structure | A Pipelet node with each key and its type |
PIPELET_NEXT and PIPELET_ERROR complete in every server script, as in VS Code, because a helper a pipelet calls can return them too
The pipeline contract
Pipelet script that breaks the pipeline contract checks the header against the code:
| Message | Fix |
|---|---|
A pipelet script needs an execute function: the pipeline calls it, shown as an error | Create the execute function |
'Dup' is declared again below, and the later declaration counts | None |
The script never assigns @output 'Total' | None |
'dw.order.Bskt' is not a B2C Commerce API class | None |
The script does not import 'Product': write dw.catalog.Product | None |
execute returns nothing: the pipeline expects PIPELET_NEXT or PIPELET_ERROR | Return PIPELET_NEXT |
execute returns true: the pipeline expects PIPELET_NEXT or PIPELET_ERROR | Return PIPELET_NEXT |
execute ends without a return: the pipeline expects PIPELET_NEXT or PIPELET_ERROR | Add 'return PIPELET_NEXT' |
The pipelet header does not declare 'Undeclared', a weak warning | Add '@input Undeclared : Object' to the header |
- Only literals and
undefinedare judged as return values, not names or calls - An
executethat ends withthrowneeds no return - The header key fix writes
@outputwhen the script assigns the key, otherwise@input - Type checks skip primitives, names in lower case and built-ins such as
Array,Object,Date,XMLandMap
Script nodes
Cart.xml.ds header, so a new @output key shows up as a row with its type once the script is savedA Script node runs the script its Script File names. Select the node and the Details panel shows its configuration and dictionary
Script File
- Suggestions list the
.jsand.dsfiles undercartridge/scriptsof the linked cartridges. Type a prefix such asapp_custom:to see one cartridge's files - The value starts after
cartridge/scripts, and.ds.jsis written as.ds - Go To opens the script: first from the site's cartridge path, then from the pipeline's own cartridge, then in linked order, with a chooser when it can't decide
- A value that names no script shows
No script found for "cart/Missing.ds".
Dictionary rows
Dictionary Input and Dictionary Output list the keys of the script's header. Each row's value is the pipeline key bound to it, and the header type shows as its placeholder. Number, Integer and Double keys get a number field
- Rows come from
.dsand.ds.jsscripts. A.jspipelet gets no rows - Saving the script refreshes the open pipeline editors
- A binding stays when the header no longer declares its key
- Header descriptions aren't shown
In the pipeline XML
The ScriptFile value in the pipeline XML is a link too:
<pipelet-node pipelet-name="Script" pipelet-set-identifier="bc_api">
<config-property key="ScriptFile" value="checkout/Calculate.ds"/>
</pipelet-node>Cmd+Click(Ctrl+Click) opens the script. With acartridge:prefix it looks only in that cartridge, without one in the pipeline's own cartridge, then in the other linked cartridges- Find Usages on the script lists the pipelines that run it next to the scripts that import it
- Renaming or moving the script updates the value, and adds the prefix when the script moves to another cartridge
These links need a license. An importScript path without a prefix looks only in the calling cartridge, unlike ScriptFile
Templates the pipeline renders
A template that the pipeline renders with an Interaction node or the SendMail pipelet gets in pdict the keys bound to the outputs a Script node's script declares with @output, with their type. Assign, Eval, system pipelet and Loop nodes put keys too, and so do the pipelines it calls. Cmd+Click on such a key in the template opens the pipeline at the node that puts it, see Pipelines
New pipelet scripts
New › Digital Script File › Pipelet script writes a pipelet named after the file:
/**
* Calculate
*
* @input Input : Object
* @output Output : Object
*/
importPackage(dw.system);
function execute(pdict) {
pdict.Output = pdict.Input;
return PIPELET_NEXT;
}In an open file, the pipelet live template writes the same header with execute and return PIPELET_NEXT, see Editing Digital Script
Debugging
Line breakpoints work in .ds files, and Evaluate Expression parses Digital Script, so for each and type annotations work there. Pipeline breakpoints stop on the Script node itself, see Pipeline debugging