Chapter 1 - Basics

qRules is the command library built into Qdabra Forms (FormsViewer). Each command does one job that ordinary rules cannot: copy a table, sort rows, submit to SharePoint or DBXL, format a date, call a web service, send an e-mail, and more than eighty others. You run a command from a normal action rule, and its outcome comes back into the form where your next rules can use it. This chapter covers what every command has in common. To look up a command, start at the Command Index. This guide explains every command: what it does, its parameters, what it returns, and the behavior that is easy to miss.

1.1 What you need

• A form template with qRules. In FormsDesigner, the qRules ribbon tab reports "This form already has qRules!" when it does; otherwise inject qRules from that tab. This adds the secondary data source QdabraRules.
• Qdabra Forms (FormsViewer) to run the form.

1.2 Running a command

In FormsDesigner, add the action Run a qRules Command to any action rule (button, field change, form load). Its one setting is the command string. The Insert qRules Command button in its Formula editor opens the Command Builder, which lists every command with its parameters and shows a live preview. See FormsDesigner User Manual, section 3.3.6 for the designer side.

Two timing rules:

• Start-up order. When a form opens, FormsViewer first runs the data connections set to Query during form load, then sets QdabraRules > finishedLoading and runs the rules on it to the end, and only then runs the Form Load rules. qRules commands work in both places. Put start-up commands on finishedLoading: it runs first, and keeping all start-up logic in that one list lets you control the order (for example, re-point a connection before you query it).
• Commands run in order. Each action finishes before the next one starts, so a Set a field value placed after the command can read the command's result.

1.3 Command syntax

CommandName /parameter=value /parameter=value ...

• The command name is case-sensitive: SetValue, not setvalue. An unknown name fails with Unsupported command: name.
• Parameter names are case-sensitive, and almost all are lower case: /xpath=, not /XPath=. The few exceptions (/mappingName and /uniqueName in SubmitToSharePointList, /termId in GetTermPath, /ccEmail in AssignDocument) are pointed out in their sections. Any other spelling fails with Unexpected parameter(s) followed by the command's usage text.
• A value runs until the next /name=. Values may therefore contain spaces and slashes, which is why XPaths need no quoting. A value must not contain a space followed by /word=.
• Required parameters must not be empty. Required parameter unspecified: name lists what is missing.
• Boolean parameters are true for true, yes or 1 (any case); anything else, or leaving the parameter out, is false unless the command says otherwise.
• Data sources: parameters such as /dsname take the data source name exactly as shown in the designer. Leave them out for the main data source.
• In a rule, the command is a text value. A fixed command is written in quotes, for example "GetErrorCount /novalidate=false". To build one from field values, use concat(), or better, use dynamic parameters (next section).

1.4 Dynamic parameter values

Any parameter can take its value from a field at run time. Add -xpath to the parameter name and give the field's XPath; add -dsname too if the field is in a secondary data source:

SetValue /xpath=/my:myFields/my:Status /value-xpath=/my:myFields/my:NewStatus
SetValue /xpath=/my:myFields/my:Status /value-xpath=/dfs:myFields/dfs:dataFields/d:Item/d:Status /value-dsname=Settings

The Command Builder's Dynamic option writes exactly this. Rules:

• Use either /name= or /name-xpath=, not both (name and name-xpath cannot both be specified.).
• /name-dsname= is only valid together with /name-xpath=.
• If the XPath finds no field, the command fails with Could not find valid node for parameter name at XPath ....

Dynamic values avoid the quoting problems of concat(): a value containing quotes, spaces or slashes is passed through as it is.

1.5 Results and errors

When a command finishes, qRules fills these fields of the QdabraRules data source:

A typical pattern is: run the command, then Set a field value with QdabraRules > Result, guarded by a condition on Success if the command can fail.

To send the result straight to a field, add these to any command:

They are applied only when the command succeeds. If the field is not found, Success becomes false and the Result is still available in QdabraRules.

1.6 How this guide is organized

Each command section has the same parts: what the command is for, Syntax, a parameter table, Result, Examples, Notes on behavior and error messages, and Related commands.

1.7 About this guide

This guide is written from the qRules engine itself (package @qdabra/qrules version 1.3.4, October 2026), so parameters, defaults and error messages match what the engine actually does. Where the engine and the built-in command description disagree, the guide describes the engine and says so.

For help, active customers can use the Customer Support Portal. For anything else, use Contact Us or e-mail [email protected].

Next: Chapter 2 - Values and nodes