diff --git a/.vitepress/sidebars/reference.ts b/.vitepress/sidebars/reference.ts index 020f466c..faa99afc 100644 --- a/.vitepress/sidebars/reference.ts +++ b/.vitepress/sidebars/reference.ts @@ -45,6 +45,10 @@ export const referenceSidebar: DefaultTheme.SidebarItem[] = [ text: "Node Data Types", link: "/reference/workflow_data_types", }, + { + text: "Interpolation", + link: "/reference/workflow_interpolation", + }, { text: "SDK", link: "https://developer.caido.io/reference/sdks/workflow/", diff --git a/src/reference/workflow_interpolation.md b/src/reference/workflow_interpolation.md new file mode 100644 index 00000000..0d66accf --- /dev/null +++ b/src/reference/workflow_interpolation.md @@ -0,0 +1,89 @@ +--- +description: "Find detailed reference information on Caido Interpolation within workflow nodes allowing rich and dynamic reporting." +--- + +# Interpolation + +Interpolation enables dynamic content generation within workflow nodes by +embedding [JavaScript](#javascript-engine) expressions in text. Those +expressions can take the following shapes: + +1. [Inline](#inline-evaluation) +2. [Code Blocks](#tagged-code-blocks) + +## Inline Evaluation + +Inline interpolation uses `<% %>` delimiters to execute JavaScript expressions +and output results in-place within text. For example: + +```md +# Found <% issue_count %> issues +``` +::: warning NOTE +The example above assumes a `issue_count` variable was previously declared. +::: + +### Escaping + +Use `\<% %>` to display literal interpolation syntax without execution (shows as `<% %>`). + +### Comments + +| Syntax | Description | +|--------|-------------| +| `<% value // comment %>` | Line comments - `%>` closes the interpolation block. | +| `<% /* comment with %> */ value %>` | Block comments allow including `%>` in comments. | + +## Tagged Code Blocks + +Markdown-style code blocks with the `exec` tag are evaluated by the JavaScript engine. For example: + +````md +```exec +const issue_count = 5; +println("# Found " + issue_count + " issues"); +``` +```` + +### Output Functions + +| Function | Description | +|----------|-------------| +| `print(...values)` | Outputs values without newline. | +| `println(...values)` | Outputs values with newline. | + +::: warning NOTE +Only explicitly printed content appears in final output. The `exec` code block +itself is not visible. +::: + +::: tip +As [all fields share the same context](#shared-context), pre-compute complex +values in `exec` blocks without print statements, then reference variables in +simple `<% variable %>` interpolations for improved readability. +::: + +## Javascript Engine + +Interpolation uses Caido's JavaScript runtime environment. See [JavaScript in +Workflows](/concepts/workflows_js) for understanding JavaScript concepts in +workflows and refer to the [Runtime +documentation](https://developer.caido.io/concepts/runtime.html) for detailed +technical specifications. + +### Accessing previous nodes + +All previous node outputs within a workflow are accessible using their +[alias](/concepts/workflows_nodes.html#aliases), allowing interpolation to use +values from earlier nodes in the workflow chain. + +### Shared context + +All Interpolable fields within a workflow node share the same execution context +which entails the following: + +- **Execution Order**: Interpolations execute sequentially in the order they + appear within the node, allowing building upon previous computations. +- **Shared Context**: All interpolations in a single node share the same + JavaScript environment, meaning variables, functions, and state are accessible + across all expressions within that node.