Usage with Confluence modules

At the moment, only the following Confluence modules support display conditions:

• Confluence content action
• Confluence content byline item
• Confluence context menu
• Confluence global page
• Confluence global settings
• Confluence space settings

Property conditions

In addition to common properties, Confluence supports conditions that are based on the properties of an entity being viewed (for example, a page or blog post) or its container (for example, a space).

The following property conditions are supported:

• entityPropertyExists
• entityPropertyEqualTo
• entityPropertyContainsAny
• entityPropertyContainsAll

These property conditions allow comparisons to be made against data (properties) stored by the app in the host product. See Confluence entity properties for more details. Usually, properties are set by a REST call against an entity type. See the Confluence Cloud REST API documentation for details on how to manage properties for different types of entities.

Property conditions are defined in the displayConditions section of a module in the manifest.yml file, as shown below:

1
2
modules:
  confluence:contentBylineItem:
    - key: example-app-key
      function: main
      title: Example App
      displayConditions:
        entityPropertyEqualTo:
          entity: content
          propertyKey: myPropertyKey
          value: myValue
          objectName: myNestedField.subField

You can use the operators and, or, and not to build more complex display rules that involve multiple common properties and conditions. See Usage of complex display rules for more details.

Parameters

The following parameters define all four property conditions.

As an example, if the value of objectName is defined as myField.mySubField, then the condition is evaluated against a string myValue for the JSON property shown below:

1
2
{
  "theirField": "theirValue",
  "myField": {
    "mySubField": "myValue",
    "otherSubField": "otherValue"
  }
}

Evaluation of property conditions

The evaluation of property conditions depends on the property condition type itself and how the parameters for the property conditions are defined.

entityPropertyExists

entityPropertyExists evaluates to true if an entity property with a key defined by the propertyKey parameter exists for an entity. If objectName is specified, the condition evaluates to true if property value is a JSON object and has a nested field that corresponds to a specified path, as described in the Parameters section.

Example 1

The property condition shown below evaluates to true if the page or blog post the user is viewing has a property with the key myPropertyKey:

1
2
entityPropertyExists:
  entity: content
  propertyKey: myPropertyKey

Example 2

1
2
entityPropertyExists:
  entity: content
  propertyKey: myPropertyKey
  objectName: completed

The property condition evaluates to true for the property value shown below:

1
2
{
  "completed": "2021-08-01",
  "otherField": true
}

entityPropertyEqualTo

entityPropertyEqualto evaluates to true if a value of an entity property with a key defined by the propertyKey parameter is equal to the value specified in the value parameter of a condition. If objectName is specified, the comparison is done against a field inside a JSON property value, as described in the Parameters section.

The referred property value or field value is converted to a string before the comparison. See Comparison of non-string values for more details.

Example

1
2
entityPropertyExists:
  entity: space
  propertyKey: myAppSpaceSettings
  objectName: isEnabled
  value: true

The property condition evaluates to true for the property value shown below:

1
2
{
  "isEnabled": true,
  "otherFields": "..."
}

entityPropertyContainsAny

entityPropertyContainsAny evaluates to true if a value of an entity property with a key defined by the propertyKey parameter is an array and contains at least one of the values specified in the value condition parameter. If objectName is specified, the comparison is done against a field inside a JSON property value, as described in the Parameters section.

By default, both the property value and the condition value parameter are expected to be arrays. If you define these values as regular strings, the values are treated as arrays containing one element.

The Forge manifest schema enforces all elements in the value parameter array to be strings. As for the entity property value, all elements in the array are converted to strings before the comparison. See Comparison of non-string values for more details.

Example 1

The property condition shown below evaluates to true for the property value ["otherValue1", "myValue2", "otherValue2"] because "myValue2" is in both arrays:

1
2
entityPropertyContainsAny:
  entity: space
  propertyKey: myPropertyKey
  value:
    - myValue1
    - myValue2

Example 2

The property condition shown below evaluates to true for the property value ["otherValue1", "myValue2", "otherValue2"] because "myValue2" is a value of the condition and is contained in the property value array:

1
2
entityPropertyContainsAny:
  entity: space
  propertyKey: myPropertyKey
  value: myValue2

entityPropertyContainsAll

entityPropertyContainsAll evaluates to true if a value of an entity property with a key defined by the propertyKey parameter is an array and it contains all of the values specified in the value condition parameter. If objectName is specified, the comparison is done against a field inside a JSON property value, as described in the Parameters section.

Allowed values and limitations for property values and the condition value parameter are the same as for the entityPropertyContainsAny condition type.

Example

The property condition shown below evaluates to true for the property value ["otherValue1", "myValue2", "otherValue2", "myValue1"] because both "myValue1" and "myValue2" are in the property value array:

1
2
entityPropertyContainsAll:
  entity: space
  propertyKey: myPropertyKey
  value:
    - myValue1
    - myValue2

Comparison of non-string values

Since the Forge manifest schema only allows a string or an array of strings as a property condition value, entity property values are converted to strings before the comparison.

• If the referenced value is a primitive other than a string, the value is converted to a string.
• If the referenced value is an object, the value is converted to a string by applying the JSON.stringify function.
• If the referenced value is an array, the value remains as an array, but its elements are converted to strings.

This includes elements that are objects or arrays themselves. They are converted to a string by applying the JSON.stringify function.

Example 1

1
2
{
  "myField": {
    "mySubField": 42
  }
}

If a condition has objectName equals to myField, the matching property value is "{\"mySubField\":42}".

If objectName equals to myField.mySubField, the matching property value is "42" (string).

Example 2

1
2
{
  "myField": ["value1", "value2", { "mySubField": 42 }]
}

If a condition has objectName equals to myField, the matching property value is ["value1", "value2", "{\"mySubField\":42}"].

Example 3

1
2
["value1", "value2", ["subValue1", "subValue2"]]

The matching property value is ["value1", "value2", "[\"subValue1\",\"subValue2\"]"].

Usage of complex display rules

You can use the operators and, or, and not to build complex rules that involve multiple common properties and property conditions. This is allowed with some limitations.

Only one property condition per level

Only one property condition is allowed on the same level of a display conditions tree. For example, the following structure is not allowed:

1
2
displayConditions:
  or:
    entityPropertyExists:
      ...
    entityPropertyEqualTo:
      ...

You can use an array if you need to use multiple property conditions on the same level, as shown below:

1
2
displayConditions:
  or:
    - entityPropertyExists:
        ...
    - entityPropertyEqualTo:
        ...

Alternatively, the same condition can be defined like this:

1
2
displayConditions:
  or:
    entityPropertyExists:
      ...
    or:
      entityPropertyEqualTo:
        ...

Property conditions and common properties on the same level

Property conditions may be used together with common properties on the same level of a display conditions tree:

1
2
displayConditions:
  or:
    isAdmin: true
    entityPropertyExists:
      ...

While multiple common properties are allowed on the same level of a conditions tree, only one property condition is allowed on that level.

Validation of complex conditions

Complex condition trees are validated using the depth-first search method. If one of the individual conditions from an and group is evaluated as false, the whole condition tree then evaluates as false. Similarly, if one of the conditions from an or group is evaluated as true, the whole condition tree evaluates as true. Validation for the rest of the condition tree no longer happens.

If common properties are on the same level as property conditions, they're always validated first. As such, it's preferred to put common properties as high as possible in the condition tree since they don't require any fetching of data from the product. On the contrary, to validate property conditions, Forge requests from Confluence all the property values that appear in the condition tree.