Expression Directive
Embed a live Multi-Query result anywhere you use a BizFirst expression — workflow nodes, form fields, templates, or notifications — using the {{multi-query:}} token.
Syntax
Three variants are supported. All begin with the directive name multi-query, followed by a colon, the engine identifier, a dot, and the template catalogue code. Pipe-separated options control output format.
{{multi-query:sqlserver.TEMPLATE_CODE}}
{{multi-query:sqlserver.TEMPLATE_CODE|outputFormat=html}}
{{multi-query:sqlserver.TEMPLATE_CODE|outputFormat=html|outputFormatTemplate=standalone}}| Variant | Output | Typical Use |
|---|---|---|
{{multi-query:sqlserver.CODE}} |
Compact nested JSON array string | Workflow data binding, API pass-through, downstream expression logic |
{{multi-query:sqlserver.CODE|outputFormat=html}} |
HTML fragment (expandable cascaded table) | Embed inside an existing page, form widget, or email body |
{{multi-query:sqlserver.CODE|outputFormat=html|outputFormatTemplate=standalone}} |
Full self-contained HTML document | Print view, PDF generation, iframe source |
Token Anatomy
Each part of the token has a distinct role. Understanding the anatomy helps you author directives correctly and diagnose parse errors.
| Segment | Example Value | Notes |
|---|---|---|
| Directive name | multi-query |
Fixed. Routes the token to MultiQueryExpressionDirectiveService |
| Engine | sqlserver |
Matches SqlServerDeriveEngine.EngineName. Future engines use their own identifier. |
| Template code | PAYROLL_SUMMARY |
Must exactly match the Code column in dbo.Shared_Configurations (case-sensitive) |
| outputFormat | html or omitted |
Optional pipe option. Defaults to JSON when omitted. |
| outputFormatTemplate | standalone or omitted |
Only meaningful when outputFormat=html. Wraps output in a full HTML document shell. |
How It Works
When the BizFirst expression evaluator encounters a {{multi-query:...}} token, it delegates to the directive pipeline. The following steps occur synchronously within the expression evaluation lifecycle:
The expression evaluator identifies the {{multi-query:...}} pattern and hands the raw token string to the registered directive handler.
The platform locates the handler registered for the multi-query directive name and invokes it with the full token payload and the current EvaluationContext.
MultiQueryDirectiveKeyParser splits the key segment on the first . character: the left portion is the engine name (sqlserver), and the right portion is the template catalogue code.
The service enumerates all registered ISqlDeriveEngine implementations and selects the one whose EngineName matches the parsed engine name. If no match is found, the directive returns an empty string and logs a warning.
The TenantID is extracted from the EvaluationContext — which is populated from the caller's JWT claim CurrentTenantIDWithCheck_Int. It is never taken from the token itself.
The engine loads the template from dbo.Shared_Configurations, runs the full query tree, and returns either a compact JSON string or an HTML string depending on the outputFormat pipe option. The result replaces the token in the evaluated expression.
Required Parameters
Template parameters referenced in SQL via @paramName syntax must be present in the EvaluationContext before the directive is evaluated. Missing parameters cause the child query to receive a null value, which may produce empty results or a SQL error depending on the query.
In a workflow node, set context parameters using the Set Expression Context action before any node that evaluates a Multi-Query directive:
// Workflow node: Set context parameters before evaluation
EvaluationContext.Set("PayPeriodID", currentPayPeriod.ID);
EvaluationContext.Set("DepartmentID", selectedDepartment.ID);
// Then in the next node, the directive resolves correctly:
// {{multi-query:sqlserver.PAYROLL_DEPT_SUMMARY}}Parameters are matched by name (case-insensitive) between the EvaluationContext and the @paramName placeholders in the template SQL.
Where You Can Use It
The {{multi-query:}} directive is supported in any BizFirst surface that processes expressions:
Workflow Node
Use in a Compute Expression node to fetch hierarchical data mid-flow. The result can be stored in a workflow variable for downstream processing or displayed in a notification.
Atlas Form Display
Bind a read-only panel or rich-text field to a Multi-Query directive. The HTML fragment variant renders the expandable cascaded table directly inside the form at runtime.
AppStudio Widget
Embed live multi-level data in a custom dashboard widget. The standalone HTML variant is ideal for iframe-based widgets that need self-contained rendering.
Email Template
Insert an HTML fragment of hierarchical data directly into a transactional email. The cascaded table renders correctly in most email clients when inline styles are present.
SMS / Push Template
Use the default JSON output variant to embed a compact data summary in a short message or push notification payload, then format it with a secondary expression.
Returning Empty vs Error
If the template code does not exist in
dbo.Shared_Configurations, the IsActive flag is 0, the template is soft-deleted, or a required parameter is absent from the EvaluationContext, the directive evaluates to an empty string. A warning is written to the platform log. No exception propagates to the caller, so the surrounding expression or template continues to render. This design prevents a single bad token from breaking an entire page or workflow. Always check platform logs if a token renders blank unexpectedly.
The
TenantID is always sourced from the EvaluationContext (which comes from the caller's JWT). Template parameters never include TenantID — it is injected automatically into every level of the query tree. You cannot override it from the token or from context parameters.