Conditions

Overview

Conditions allow you to specify additional prerequisite requirements for Triggers and some Transitions.

They are a set of optional parameters which can be added to the macros (listed below) to impose additional limits on when the macro will be active.

In addition, due to support for Value References, you can even create your own custom conditions by comparing metadata values.

Basic example

{workflow:name=Conditions}
   {state:Editing|approved=Done|rejected=Editing}
      {approval:Review|permission=administer|assignable=true}
   {state}
   {state:Done|final=true|updated=Editing}
   {state}
{workflow}

In the example above, only an administrator can review the content.

One or more conditions can be added to an approval using workflow builder.

You can also add conditions to the state-selection macro in workflow builder.

choose the Select transition option when editing the transitions for a state

The dialog boxes to add a condition will be displayed once the Select transition and at least one destination state is added.

Ensure you choose the + to add the condition and then Add to update the state.

In our example, this would create the following markup for the Done state.

{state:Done|final=true|updated=Editing}
      {state-selection:states=Done|permission=ADMINISTER}
{state}

A trigger and any trigger conditions is added as markup either using the markup editor or the Triggers dialog box in the Edit Workflow panel in workflow builder.

Compatible Macros

Note: If a macro has a parameter of the same name as a condition, the parameter – and documentation for that parameter on the macro page – takes precedence.

Conditions

Condition	Value	Notes	Ver
Value Reference	A specific value, of valid type for the value reference. Supports Value References	Does the value of a value reference match the specified value? Page: Communardo Metadata for Confluence app Page: Make tasks disable a review
		If used in a trigger macro that's listening to the `pageupdated` event, the trigger will not be activated if the referenced value is still being updated.
		One invalid parameter in a list of users in a condition WILL disable the transition for the other listed users. The non-existent parameter is a blocker for an approval or a state-selection transition.
`group^†`	A comma-separated list of group names Supports Value References	Is the current user a member of one or more of the specified groups?
`group^†`		When applied to the approval macro it is an approval macro parameter - it is not used as a condition. For example, you can prefix the list (not items in the list) with `&` (ampersand) to mandate that all users in the groups defined by the list must take part in the content review.
`hasapproval`	Name of an `approval`	Has an approval of the specified name been approved for this content? Page: Adding Multiple Reviews
`hasapproval`	Name of an `approval`	When applied to an approval macro in a state with multiple approval macros, this enables you to create nested approvals. Just make sure the approval you are referring to is defined prior to where the condition is used.
`haslabel`	A comma-separated list of content labels.	Does the content have one or more of the labels specified?
`ischildof`	Title of required ancestor page. Supports Value References	Does the current page have a parent or ancestor page of the specified page title?
`ishomepage`	`true` – Yes, it's the home page `false` – No, some other page	Is this page set as the space home page? Content by label There is no content with the specified labels See also: How to set space home page
`isminorchange`	`true` – Yes, the change was minor `false` – No, watchers were notified	Did the content editor uncheck the "Notify watchers" checkbox (indicating a "minor change") before updating the content? Page: StiltSoft Talk app The `isminorchange` parameter can be used with the StiltSoft Talk app for changes in inline comments on a page or blog post.
`isminorchange`		This condition can only be used in the trigger macro. It is used when listening to the `pageupdated` or `newsupdated` events.
`initial`	`true` – Yes, this listens ONLY for the first occurrence of a transition to a specified state for the content `false` – No, the filter listens for all occurrences of transitions to the specified state	Is this action in a trigger for only the initial occurrence of the named state for the content? `initial` is unique to the `statechanged` event used in a trigger macro `initial=true` acts as a filter to make the trigger act only on the first occasion that a state is entered for a given piece of content `initial=false` listens to every time the workflow transitions to the state specified by the `state` parameter.
`initial`		Note that the use of `initial` is as a parameter of the trigger macro. The primary use of the `initial` parameter is to perform one-time initialisation actions for a given piece of content. For example, on the first review of a piece of content you might want to send out additional emails, or set some metadata.
`isorphan`	`true` – Yes, the page is an orphan `false` – No, the page has a parent page	Is the page an orphan (no parent page)? Content by label There is no content with the specified labels
`parenthaslabel`	A comma-separated list of content labels.	Does the parent (or any ancestor pages) have one or more of the labels specified? Content by label There is no content with the specified labels
`partial`	`true` – Yes, an individual Approve/Reject decision has been completed for a content review `false` – No, all approval decisions (approve/reject) must be completed	Has an individual reviewer undertaken an Approve/Reject decision? `partial` is unique to content review events in a trigger macro This condition acts as a filter to tell the trigger to act on each individual Approve or Reject decision, rather than waiting all reviewers to agree for the named content review.
`partial`		Note that the use of `partial` is as a parameter of the trigger macro
`permission`	`edit` – user can edit the content `view` – user can view content^† `administer` – user can administrate content^‡	Does the user have the specified permission for the content? Content by label There is no content with the specified labels See also: Roles and Permissions
`permission`		† Irrespective of additional view restrictions resulting from Publishing ‡ Additional administrators can be defined via the `adminusers` parameter on the `workflow` macro.
`space` or `spacekey`	A space key. Supports Value References	Is the page or blog post in the space defined by the space key? Content by label There is no content with the specified labels Note: The space key is usually shown in URLs, or on the Space Tools → Space Overview screen.
`state`	A state name.	Is the workflow for this content currently in the named state? Page: StiltSoft Talk app
`stateindraft`	A state name.	Is there an unpublished version of this content in the corresponding Draft Space? Content by label There is no content with the specified labels
`stateindraft`	A state name.	Note: This condition requires the Comala Publishing app to be installed.
`success`	`true` – no errors encountered for a trigger action `false` – error encountered for a trigger action	Has an error occurred in the action(s )of a workflow trigger? `success` is unique to custom events created using the trigger macro. This condition acts a filter for the trigger and looks at whether the actions of the parent trigger for the custom event encountered any errors (see Triggers - Error handling)
`success`		Note that the use of `success` is as a parameter of the trigger macro.
`title`	Content title. Supports Value References	Does the content (page or blog post) have the specified title? Content by label There is no content with the specified labels
`user^†`	Comma-separated list defining one or more users via their username or user groups. Supports Value References	Is the current user one of the users listed? Note: You can include `anonymous` if you want to check for users who are not currently logged in to Confluence. Page: Adding Multiple Reviews
`user^†`		When applied to the approval macro it is an approval macro parameter - it is not used as a condition. You can prefix the list (not items in the list) with `&` (ampersand) to mandate that all users in the groups defined by the list must take part in the content review.
`usersdefined`	Comma-separated list of Value References	Does the value reference define users? This is useful when using workflowparameter macro to create editable value references – you can check to see if the entered values are valid user accounts. Content by label There is no content with the specified labels	4.1
metadata reference	Reference to a specific metadata value (or a workflow parameter reference)	When comparing metadata (value references) it can only be compared against one specific value or a value reference. Multiple values can be compared only when metadata is used with a `user`, group or `haslabel` condition. When comparing the metadata value against multiple values in a `user`, group or `haslabel` condition you should use the following format `@MetaOne@=!1\|@MetaOne@=!2\|@MetaOne@=!3`
– Denotes conditions which can only be used on pages, not blog posts. † - Conditions are evaluated as AND conditions, with the exception of user and group. When both conditions are used, it's applied an OR clause i.e., (user or group) either one of those parameters is required for the condition to be true.
- Denotes a parameter in a trigger macro that act as a filter. The use of these are unique to specific events.

Negation

Conditions are compared to values. Values can optionally be negated with a ! (pling / exclamation mark) symbol.

{...|condition=value|...} -- value must match
{...|condition=a,b,c|...} -- one or more of the values must match
{...|condition=!value|...} -- value must not match
{...|condition=!a,b,c|...} -- none of the values must match

This is not applicable to the parameters used as filters in triggers - partial, initial, success

Invalid workflow parameter for a user

One invalid parameter in a list of users in a condition WILL disable the transition for the other listed users. The non-existent parameter will act as a blocker for other users.

Invalid workflow parameter for a user in a condition for a select transition

If a workflow parameter is used to specify a user for a state-select transition the transition will be disabled If the user set in the parameter is invalid (deleted or non-existent).

The transition will become active if the parameter becomes valid by adding a valid value or is deleted.

For example if the workflow parameter @myParam@ has an invalid user value, the transition button in the workflow popup will be disabled.

{state:In Progress|taskable=true}
        {state-selection:states=Approved|user=@MyParam@}
{state}

If the invalid workflow parameter is one of a list of users for the state-select transition, the transition will be disabled for the other users listed in the condition. The non-existent parameter is a blocker for the transition.

{state:In Progress|taskable=true}
        {state-selection:states=Approved|user=@MyParam@, admin, elle}
{state}

An error is shown indicating that there is an error in the workflow definition regarding the list of users who can undertake the transition.

Invalid workflow parameter in a condition for an approval

If a workflow parameter is used to specify a single user for an approval, the Approve and Reject buttons in the workflow popup will be disabled if the user set in the parameter is invalid (deleted or non-existent).

{state:Review|approved=Approved|rejected=Rejected}
        {approval:Review the page|user=@MyParam@}
{state}

The transition will become active if the parameter becomes valid by adding a valid value or is deleted.

If the invalid parameter is one of a list of users for the approval then the approval is disabled for all users.

{state:Review|approved=Approved|rejected=Rejected}
        {approval:Review the page|assignable=true|user=@MyParam@, admin, elle}
{state}

The non-existent user defined in the parameter blocks the approval.

An error is shown indicating that there is an error in the workflow definition regarding the list of users who can approve.

The approval will become active for each defined user if the parameter becomes valid by adding a valid value or is deleted.

Examples

Page:

Adding Multiple Reviews — Add multiple reviews to a content review, set assignee requirements and review dependencies
Page:

Advanced different-space publishing
Page:

Advanced remote-space publishing
Page:

Communardo Metadata for Confluence app — Using the Communardo metadata as value references in a workflow - including use in a custom condition for a trigger macro
Page:

Make tasks disable a review — Two ways to use tasks to disable a review. The first way uses a precursor task state where the tasks can be set and completed. The second example uses a Value Reference as a condition to check that all tasks are complete. For the value reference method, you will need the Reporting for Confluence app in addition to Comala Document Management.
Page:

StiltSoft Talk app

Content

Space Tools

Breadcrumbs

Conditions

Overview

Basic example

Compatible Macros

Conditions

Negation

Invalid workflow parameter for a user

Invalid workflow parameter for a user in a condition for a select transition

Invalid workflow parameter in a condition for an approval

Examples

See also