The Workflow Assistant Configurator uses two small query languages to make panels respond to what the user is doing. Lucene decides whether components are disabled, required, or visible. Regex decides what users can type into a field and what counts as a valid final value. Both languages are powerful, both are widely used outside the Configurator, and both have the same problem: they look intimidating until you have written three of them.
This article is a plain-language primer. By the end you will be able to read any condition in this manual or in an existing panel, and write the simple ones from scratch. The reference appendices (Lucene quick reference, Regex quick reference) cover the full vocabulary; this page is the orientation.
You do not need to memorise either language. The Configurator’s condition fields accept your query and tell you when a component reaches a state — disabled, required, hidden — driven by it. You can always test a query in Assets before pasting it in.
The Disable condition, Required condition, and Display condition input fields in the Configurator’s options panel.
Where conditions appear in the Configurator
Conditions are the connective tissue of the Configurator. The same query language drives several different decisions:
| Where you see a condition | What it controls |
|---|---|
| Disable condition on a Field or button | Whether the field is non-editable or the button is greyed out for the current selection |
| Required condition on a Field | Whether the field must hold a value before the user can publish a change |
| Display condition on a Notification | Whether the notification appears at all |
| Query on a Query button | Which assets the button returns when clicked — written in the same Lucene-flavoured syntax |
| Disable condition on an entire feature (for example a widget) | Whether the feature is available for the current selection |
All of those conditions are written in Lucene. They run against the metadata of the currently selected asset or collection — exactly the same metadata your user can see in Assets. If the query returns true, the action fires (disable, require, display, return). If it returns false, the component behaves as if no condition was set.
A separate, smaller language — regex — is used in two places, both on Fields:
- Keep pattern — what characters the user is allowed to type while editing a field
- Pattern — what counts as a valid final value once the user has finished typing
That is the whole map. Lucene for selection-dependent behaviour, regex for value-dependent input.
Lucene in 60 seconds
Lucene is a query language that pairs well with text-heavy data. It looks like English with two small habits: every term names a field, and operators are written in capitals.
The minimal pattern is field:value — the field name on the left, a colon, the value on the right. Read out loud as “field equals value.” Three short examples:
| Lucene query | Reads as |
|---|---|
status:Final |
The metadata field status has the value Final
|
assetDomain:image |
The metadata field assetDomain has the value image
|
cf_clearanceLevel:approved |
The custom metadata field cf_clearanceLevel has the value approved
|
Combine clauses with AND, OR, and NOT. They must be in capitals.
Note: Hyphen - is not currently supported as an exclusion operator. You must use NOT instead.
| Lucene query | Reads as |
|---|---|
status:Final AND cf_clearanceLevel:approved |
Both conditions are true |
status:Draft OR status:Review |
Either condition is true |
status:Final AND NOT cf_archived:true |
Final, and not archived |
Wrap multi-word values in double quotes, and escape special characters with a backslash.
| Lucene query | Reads as |
|---|---|
status:"Awaiting approval" |
The status is the multi-word value “Awaiting approval” |
creatorName:"O\\'Connor" |
The creator name is O'Connor, with the apostrophe escaped |
Detecting if a field is blank is performed by testing for an empty string.
| Lucene query | Reads as |
|---|---|
description:"" |
The description value is blank |
That is enough Lucene for the majority of conditions you will write. The full syntax — ranges, wildcards, fuzzy matching, multi-value fields — is in 12a — Lucene query quick reference.
Note: A condition is evaluated against the selected asset’s metadata, not against the panel itself. If the user has selected three assets, the condition is evaluated for each one — the disable, required, or display state reflects the combined result. Test conditions with a single asset first; expand to multi-selects once the single-asset case behaves correctly.
Where Lucene meets your panel: substitution
A more powerful pattern uses values from the currently selected asset directly inside the query. The Configurator supports {fieldName} substitution: when the user clicks a button or the condition is evaluated, {fieldName} is replaced with the live value from the selected asset’s metadata.
Two real examples lifted from a working panel:
| Query button query | What it does |
|---|---|
ancestorPaths:"/Project/WIP and Final" AND isbn:{isbn} AND type:"book" |
Returns every book in the WIP folder that shares the same ISBN as the currently selected book |
cf_projectCode:{cf_projectCode} && type:"book" |
Returns every book that shares the same Project code as the current selection |
Substitution is what turns a static query into a useful action: a single button can mean “show all related assets” because it pulls the relating value out of the current selection.
Tip: When a Query button returns the wrong results, the substitution is the first place to look. Open the asset’s metadata in Assets, find the field named in the curly braces, and confirm the value matches what the query expects. The next places to look are the field name (typing or autocompleting a field that does not exist will return an empty result) and the surrounding Lucene clauses.
Multi-value comparison
When using field substitution, there is an additional feature for comparing values. If you use the field substitution as part of a query then this is comparing an exact value. However there are two additional of AND and OR to compare:
| Query button query | What it does |
|---|---|
parentContainerIds:{AND:parentContainerIds} |
Returns assets that are also contained by the same containers as the selected one. |
parentContainerIds:{OR:parentContainerIds} |
Returns assets that are in one or more containers as the selected one. |
This enhanced substitution query helps compares complex multi-value fields and surface related assets based on the current selection.
Regex in 60 seconds
Regular expressions are a way of describing patterns of characters. The Configurator uses them in two related but distinct slots on a Field:
- Keep pattern — what the user is allowed to type. The Configurator drops anything that does not match. Use it for live filtering: only digits, only letters and spaces, only uppercase
- Pattern — what counts as a valid final value. The Configurator does not drop characters; it raises a validation error if the final value does not match. Use it for shape-checking: an ISBN must be 13 digits, a WBS code must be three letters and four digits
Three short examples:
| Slot | Regex | Reads as |
|---|---|---|
| Keep pattern | [0-9] |
Allow only digits while typing |
| Keep pattern | [A-Za-z ] |
Allow only letters and spaces while typing |
| Pattern | [A-Z]{3}[0-9]{4} |
The final value must be three uppercase letters followed by four digits |
The two slots work together. Set the keep pattern to constrain typing, and the pattern to validate the result. Always pair both with a clear Pattern message — the text the user sees when their input does not match — so the validation does not feel arbitrary.
Note: A field whose pattern fails will block publish until the user fixes the value. Without a pattern message the user sees a generic error; with one, they see “ISBN must be 13 digits” and can act on it. Always write the pattern message at the same time as the regex.
Reading conditions in this manual
Throughout this manual you will see condition examples of the same shape:
status:"Awaiting approval" AND assetDomain:image
Read it as “the asset is in the Awaiting approval state and is an image.” That is enough to follow what the surrounding paragraph is doing without writing the condition yourself. When you do write one, the same reading-out-loud approach is your best debugging tool — if you cannot read your own condition aloud as plain English, it almost always has an error.
Testing a query before pasting it in
The fastest way to verify a Lucene query is to test it in Assets directly. Assets ships with the same query language; anywhere you can search, you can paste your condition and see what comes back.
Step 1. Open Assets in a separate browser tab and sign in as a user who has access to the assets you want to test against.
Step 2. Navigate to a folder that contains representative assets — both ones that should match and ones that should not.
Step 3. In the search bar, paste your Lucene query. Press Enter.
Step 4. Confirm the results: if your query is status:Final AND assetDomain:image, you should see only Final-status images. If you see the wrong assets, adjust the query and try again.
Step 5. Once the query returns the right set in Assets, paste it into the Disable condition, Required condition, or Display condition slot in the Configurator.
Tip: This Assets-first habit catches most mistakes before they become support tickets. The other ninety per cent of mistakes are field-name typos — the technical name in the query must match the technical name in Assets exactly, including case.
What about Lucene versus Liqe
You may see references in WoodWing engineering material to Liqe, the parser that the Workflow Assistant uses internally to interpret these queries. Liqe is a Lucene-compatible parser; everything in this manual works in both. If you are reading this manual you can write Lucene with confidence and ignore the underlying parser name. The reference appendix flags the very small number of cases where Liqe and full Lucene differ.
Where to go from here
- 06b — Disabling components and writing disable conditions — the practical application of Lucene to disable conditions, with worked examples
- 06c — Requiring values and validating input — required conditions, regex keep-pattern, regex pattern, and pattern messages
- 05c — Notifications reference — display conditions are the most-used Lucene slot in the manual; the reference page has a library of patterns
- 12a — Lucene query quick reference — the full Lucene vocabulary
- 12b — Regex quick reference for field validation — the full regex vocabulary
Revisions
- 8 May 2026: First publication of the manual
Comments
0 comments
Please sign in to leave a comment.