Page Comparison

Table of Contents

maxLevel	2
minLevel	2
absoluteUrl	true
exclude	See also
type	flat
separator	pipe

Overview

Excerpt

hidden	true

Define pre-requisite conditions for approvals, select transitions and triggers

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

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

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

Basic example

Code Block

language	text

{workflow:name=Conditions}
   {state:Editing|approved=Done|rejected=Editing}
      {approval:Review|group=confluence-administrators|assignable=true}
   {state}
   {state:Done|final=true|updated=Editing}
   {state}
{workflow}

In the example above, only a user who is a member of the confluence-administrators group can review the content.

Compatible Macros

If a macro has a parameter with the same name as a condition, the parameter defined in the macro takes precedence.

Filter by label (Content by label)

showLabels	false
max	500
showSpace	false
sort	title
cql	label = "supports-conditions" and label = "macro" and space = currentSpace ( )

If a macro has a parameter with the same name as a condition, the parameter as defined in the macro takes precedence.

For example, user and group are parameters defined in the approval macro, and the approval macro defines how to use these parameters.

Conditions

label = "example" and label = "concept-conditions" and label = "condition-user" and space = currentSpace ( )

One invalid parameter in a list of users in a condition disables the transition for the other listed users. The invalid user parameter value is a blocker for an approval or a state-selection transition.

Condition

Value

Notes

Ver

Value Reference

A specific value of . This must be a valid data type datatype for the value reference.

supports Value References

Does the value of a value reference match the specified value?

For example, @title@=<pagename> where <pagename> <pagename> is the page title.

You Conditions using value references can also create and use value reference conditions using some be set when using a third-party appsapp:

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "example" and label = "concept-conditions" and label = "condition-value-reference" and space = currentSpace ( )

If used in a trigger macro that's listening to for the pageupdated event, the trigger is not activated if the referenced value is still being updated.

One invalid parameter in a list of users in a conditionWILL disable disables the transition for the other listed users. The non-existent parameter value 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?

When applied to the approval macro, it is an a parameter of the 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 approved for this content?

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "example" and label = "concept-conditions" and label in ( "parameter-hasapproval" , "condition-hasapproval" ) and space = currentSpace ( )

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?

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 only 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.

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 initialization actions for a given piece of contentdocument. For example, on the first review of a piece of content document, you might want to send out an additional emails, email or set some metadata.

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?

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "example" and label = "concept-conditions" and label in ( "parameter-ishomepage" , "condition-ishomepage" ) and space = currentSpace ( )

See also: Roles and Permissions

† Irrespective of additional view restrictions resulting from Publishing.

‡ Additional administrators administrator that are is 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?

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "example" and label = "concept-conditions" and label in ( "parameter-space" , "parameter-spacekey" , "condition-space" , "condition-spacekey" ) and space = currentSpace ( )

Info

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?

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "example" and label = "concept-conditions" and label in ( "parameter-state" , "condition-state" ) and space = currentSpace ( )

stateindraft

A state name.

Is there an unpublished version of this content in the corresponding Draft Space?

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "example" and label = "concept-conditions" and label in ( "parameter-stateindraft" , "condition-stateindraft" ) and space = currentSpace ( )

This condition requires the installation of the Comala Publishing app.

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 as a filter for the trigger and looks at whether the actions of the parent trigger for the custom event encountered any errors.

The use of partial is only as a parameter of the trigger macroof the trigger macro.

title

Name of the page

Does the current page have the page name?

This condition does not support the use of value references for its value.

You can use the @title@ value reference as a condition with a value reference as its value, for example, @title@=@ThisisaPageName@.

user†

CommaA comma-separated list defining defines one or more users via their username usernames or user groups.

supports Value References

Is the current user one of the users listed?

Info

Note:

You can include anonymous if you want to check for users who are not currently logged in to Confluence.

Filter by label (Content by label)

showLabels false

max 6

showSpace false

sort title

cql

When applied to the approval macro, it is an a parameter of the approval macro parameter - it is not used as a condition.

You can prefix the whole list (but not items an item 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 workflow parameter macro to create editable value references – use this parameter to check that the entered values are valid user accounts.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "example" and label = "concept-conditions" and label in ( "parameter-usersdefined" , "condition-usersdefined" ) and space = currentSpace ( )

4.1

metadata reference

Reference to a metadata value (including a workflow parameter reference)

When comparing metadata (value references), a metadata reference can only be compared against one specific value or a value reference.

Multiple values can ONLY be compared when metadata is used with a user, group, or haslabel condition.

Denotes conditions that 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, an OR clause is applied, i.e., (user or group), and either one of those parameters is required for the condition to be true.

Denotes a parameter in a trigger macro that acts as a filter. The use of these is unique to specific events.

Negation

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

Code Block

language	erl

{...|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

Comparing metadata values

A metadata reference can only be compared against one specific value or a value reference.

An exception is that multiple values can be compared when using a metadata reference with the following conditions

user
group
haslabel

When comparing the metadata value against multiple values, you should also use the following format

Code Block
@MetaOne@=!1\|@MetaOne@=!2\|@MetaOne@=!3

For example

Code Block
{state-selection:states=Approved\|user=@MetaOne@=!1\|@MetaOne@=!2\|@MetaOne@=!3}

The condition is evaluated as an OR condition.

If a metadata condition is included in a pageupdated trigger, the trigger does not fire if the referred metadata value is being updated.

Invalid workflow parameter for a user

One invalid parameter in a list of users in a condition disables the transition for the other listed users. The non-existent parameter acts as a blocker for other users.

Table of Contents

maxLevel	3
minLevel	3

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 is disabled If the user set in the parameter is invalid (deleted or non-existent).

The transition becomes 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 is disabled.

Code Block

language	text

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

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

Code Block

language	text

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

A message displays 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 are disabled if the user set in the parameter is invalid (deleted or non-existent).

Code Block

language	text

{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.

Code Block

language	text

{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.

A message displays an error in the workflow definition regarding the list of users who can approve.

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

Examples

Filter by label (Content by label)

showLabels	false
max	100
showSpace	false
sort	title
excerptType	simple
cql	label in ( "concept-conditions" , "condition-group" , "condition-hasapproval" , "condition-haslabel" , "condition-ischildof" , "condition-ishomepage" , "condition-isminorchange" , "condition-isorphan" , "condition-parenthaslabel" , "condition-permission" , "condition-space" , "condition-spacekey" , "condition-state" , "condition-stateindraft" , "condition-title" , "condition-user" , "condition-usersdefined" , "condition-value-reference" ) and label = "example" and space = currentSpace ( )

Versions Compared

Old Version 5

New Version Current

Key

Overview

Basic example

Compatible Macros

Conditions

Negation

Comparing metadata values

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