Documentation

Conditions

A condition specifies requirements that must be met for a user interface element exposed by an add-on to be displayed to a user. Typical use cases include requiring a user to be logged in or to have specific permissions.

Various types of modules accept conditions, including Pages, Web Panels and Web Items. To see whether a certain module accepts conditions, see its specific module documentation page.

Conditions may also be used in context parameters.

There are different classes of conditions. Most commonly used are the predefined conditions provided by each host product. When further customization is needed, conditions can be specified in terms of properties stored by the add-on in the host product.

These conditions operate on properties of the user at the browser, the entity being viewed (e.g. an issue or a blog post) or its container (e.g. a project or a space), or the entire system.

Add-ons can also use conditions as building blocks of boolean expressions containing the logical operations conjunction (AND), disjunction (OR), or negation.

Table of contents

Predefined conditions

A predefined condition is a condition which is exposed from the host Atlassian application. See the list of predefined conditions.

For example, a condition that will evaluate when only logged-in users view the page is specified by the following module declaration.

{
    "modules": {
        "generalPages": [
            {
                "conditions": [
                    {
                        "condition": "user_is_logged_in"
                    }
                ]
            }
        ]
    }
}

Condition parameters

Certain predefined conditions accept parameters.

For example, the has_issue_permission condition passes only for users who have the permission specified in the ondition. The issue for which permissions are checked is the issue being viewed by the user at the browser.

{
    "modules": {
        "generalPages": [
            {
                "conditions": [
                    {
                        "condition": "has_issue_permission",
                        "params": {
                            "permission": "RESOLVE_ISSUE"
                        }
                    }
                ]
            }
        ]
    }
}

Property conditions

Add-ons that need to impose custom requirements on when user interface elements are displayed can use a property condition.

The following property conditions exist:

  • entity_property_exists
  • entity_property_equal_to
  • entity_property_equal_to_context
  • entity_property_contains_any
  • entity_property_contains_all
  • entity_property_contains_context
  • entity_property_contains_any_user_group
  • entity_property_contains_any_user_role (JIRA only)

These allow fast comparisons to be made against data (properties) stored by the add-on in the host product. See the Hosted Data Storage page for more details. Usually, properties are set by a REST call against an entity type. See the documentation of the product REST API's for information about how to manage properties for each entity.

Property conditions are defined in the atlassian-connect.json file in a similar way to built in conditions. An example is below.

{
    "modules": {
        "webItems": [
            {
                "key": "conditional-web-item",
                "name": {
                    "value": "Conditional Web Item"
                },
                "url": "/conditional-web-item",
                "location": "page.metadata.banner",
                "conditions": [
                    {
                        "condition": "entity_property_equal_to",
                        "params": {
                            "entity": "content",
                            "propertyKey": "workflow",
                            "value": "In-Progress",
                            "objectName": "state"
                        }
                    }
                ]
            }
        ]
    }
}

Here is an example of checking that the browser user is in at least one required group:

{
    "modules": {
        "webItems": [
            {
                "key": "conditional-web-item",
                "name": {
                    "value": "Conditional Web Item"
                },
                "url": "/conditional-web-item",
                "location": "page.metadata.banner",
                "conditions": [
                    {
                        "condition": "entity_property_contains_any_user_group",
                        "params": {
                            "entity": "project",
                            "propertyKey": "myListOfGroups",
                            "objectName": "optional"
                        }
                    }
                ]
            }
        ]
    }
}

The condition requires three parameters and can contain (as in the above example) an optional fourth parameter.

Required Parameters
  • entity - the entity on which the property has been stored. If an entity of the expected type is not present in the rendering context of the user interface element, the condition evaluates to false.
    • Common: addon
    • Confluence: content, space
    • JIRA: project, issue, user, issuetype, comment, dashboarditem
  • propertyKey - the key of the property to check. If the property is not present, the condition evaluates to false.
  • value - the value to compare the property value against. This is required for equal_to and contains conditions.
  • contextParameter - the context parameter value to read from the current page request to use for comparison. This is required for all context conditions except for those that check the group memberships of the browser user.
Optional Parameters

The optional parameter objectName lets you select which part of the entity property JSON value you wish to compare against. For example, if an entity property had the following value:

{
    "one": {
        "ignored": "value",
        "two": true
    },
    "also", "ignored"
}

Then you could set the value parameter to true and the objectName parameter to "one.two" and the condition would evaluate to true. Specifying an objectName string which cannot be used to traverse the property value results in false.

Property exists example

You can write a condition that asserts whether on not a property exists against a particular entity. For example, if you only set the property specialUrls on the issues that have your special details then you could write the following condition to ensure that your web fragment only shows up in the locations that your property does:

{
    "condition": "entity_property_exists",
    "params": {
        "entity": "issue",
        "propertyKey": "specialUrls"
    }
}

If you want to check if a particular field exists within an entity property then you can use the standard objectName syntax:

{
    "condition": "entity_property_exists",
    "params": {
        "entity": "issue",
        "propertyKey": "specialUrls",
        "objectName": "path.to.my.field"
    }
}

Property equal to example

An add-on could let administrators activate functionality per JIRA project. This could be achieved by storing an entity property with the key mySettings and the value {"isEnabled" : true} on each project using the product's REST API. Then use the entity_property_equal_to to test for it with the following module definition:

{
    "modules": {
        "webPanels": [
            {
                "location": "atl.jira.view.issue.right.context",
                "conditions": [
                    {
                        "condition": "entity_property_equal_to",
                        "params": {
                            "entity": "project",
                            "propertyKey": "mySettings",
                            "objectName": "isEnabled",
                            "value": "true"
                        }
                    }
                ]
            }
        ]
    }
}

Property contains any example

It is also possible to write conditions where you can check if one or all of the values in the condition are present in the hosted data.

For example, imagine that you stored the following data against a JIRA project under the property key consumingTeams:

{
    "teamCount": 4,
    "teams": ["Legal", "Human Resources", "Accounting", "Taxation"]
}

You could then write a condition to only apply to projects that are for the 'Accounting' and 'Development' teams, like so:

{
    "condition": "entity_property_contains_any",
    "params": {
        "entity": "project",
        "propertyKey": "consumingTeams",
        "objectName": "teams",
        "value": "[\"Accounting\", \"Development\"]"
    }
}

You will note that the value parameter needs to be a string escaped JSON element.

Property context parameter example

The entity_property_equal_to_context and entity_property_contains_context conditions let you specify a context parameter, from the current HTTP request, to use for comparison against an entity property. For example, to write a condition that only evaluates to true when a pre-defined project "Scrum Master" is the one making the HTTP request you would write something like this:

{
    "condition": "entity_property_equal_to_context",
    "params": {
        "entity": "project",
        "propertyKey": "teamRoles",
        "objectName": "scrumMaster",
        "contextParameter": "user.key"
    }
}

As you can see, the primary difference between the usual entity property conditions (other than the name of the condition), is that there is no value field and instead that has been replaced with the contextParameter field. In other conditions, the value field must be a JSON literal value; it will be the same value for every HTTP request across all of production and across every tenant. Instead, for this condition, you must provide a valid JIRA or Confluence context parameter inside the contextParameter field and that is the value that will be used for comparison in the condition at runtime. It is important to note that the "Standard parameters" from the context parameters cannot be used here. Only the JIRA or Confluence specific parameters are allowed.

If a given contextParameter cannot be found in the current HTTP request context then the condition will evaluate to false. For example, a condition that asks for the 'user.key' when there is no logged in user will result in the condition evaluating to false.

This condition allows you to have per instance configuration that will let you dictate which modules appear to different users based on contextual information for that request.

Aliases

The following aliases can be used which make writing property conditions more convenient.

Confluence

  • content_property_equal_to
  • content_property_equal_to_context
  • content_property_contains_any
  • content_property_contains_all
  • content_property_contains_context
  • content_property_contains_any_user_group
  • space_property_equal_to
  • space_property_equal_to_context
  • space_property_contains_any
  • space_property_contains_all
  • space_property_contains_context
  • space_property_contains_any_user_group

Common

  • addon_property_equal_to
  • addon_property_equal_to_context
  • addon_property_contains_any
  • addon_property_contains_all
  • addon_property_contains_context
  • addon_property_contains_any_user_group

When using these aliases, the entity param is not used. This would mean the following two condition definitions are identical.

{
    "condition": "entity_property_equal_to",
    "params": {
        "entity": "content"
        "propertyKey": "flagged",
        "value": "true"
    }
}
{
    "condition": "content_property_equal_to",
    "params": {
        "propertyKey": "flagged",
        "value": "true"
    }
}

addon_is_licensed condition

The addon_is_licensed condition will evaluate to true if and only if your add-on is a paid add-on and it is licensed. This condition can be placed on any Atlassian Connect module that supports conditions; it is not context sensitive. Here is an example of the new condition in use:

"jiraIssueTabPanels": [{
    "conditions": [
        {
            "condition": "addon_is_licensed"
        },
        {
            "condition": "user_is_logged_in"
        }
    ], 
    "key": "your-module-key", 
    "name": {
        "value": "Your module name"
    }, 
    "url": "/panel/issue?issue_id={issue.id}&issue_key={issue.key}", 
    "weight": 100
}]

In this example the JIRA Issue Tab Panel will only be shown if the add-on is licensed and the user is logged in.

If you give away your add-on for free then you must not use the addon_is_licensed condition. This is important because all free add-ons are considered unlicensed and will thus the condition will return false. Only use this condition with paid add-ons that are licensed via the Atlassian Marketplace.

can_use_application condition

can_use_application condition checks whether the current user is allowed to use a specific application (like JIRA Software or JIRA Service Desk).

The condition is true if and only if both of the the following statements are true:

  • the application is installed and enabled on the JIRA instance
  • the user is permitted to use the application according to the installed licence

The condition requires an applicationKey parameter, for example:

 {
     "modules": {
         "generalPages": [
             {
                 "conditions": [
                     {
                         "condition": "can_use_application",
                         "params": { 
                            "applicationKey": "jira-software"
                         }
                     }
                 ]
             }
         ]
     }
 }

Supported application keys are:

  • jira-core
  • jira-servicedesk
  • jira-software

If an unrecognized application key is provided then the condition will simply evaluate to false.

project_type condition

project_type condition checks whether the current project matches a specific project key.

The condition is true if and only if both of the the following statements are true:

  • the user is viewing a page that has a contextual project (e.g. the view issue page)
  • the project key of the contextual project matches the project key specified

The condition requires a projectTypeKey parameter, for example:

 {
     "modules": {
         "generalPages": [
             {
                 "conditions": [
                     {
                         "condition": "project_type",
                         "params": { 
                            "projectTypeKey": "business"
                         }
                     }
                 ]
             }
         ]
     }
 }

Supported project type keys are:

  • business
  • service_desk
  • software

Time tracking conditions

There are three time tracking conditions available:

  • time_tracking_enabled is true if time tracking is enabled, regardless of which time tracking provider is selected
  • jira_tracking_provider_enabled is true if the currently selected time tracking provider is JIRA's native time tracking implementation
  • addon_time_tracking_provider_enabled is true if the currently selected time tracking provider matches the one defined in the condition parameters

This addon_time_tracking_provider_enabled condition can be used with the Time Tracking Provider module to check if the add-ons time tracking implementation is currently selected in JIRA.

For example, if your add-on has the key add-on-key and has declared a jiraTimeTrackingProviders module with the key module-key, such as:

{
  "key": "add-on-key",
  "modules": {
    "jiraTimeTrackingProviders" : [
      {
        "key": "module-key",
        "name": "My time tracking module"
      }
    ]    
  }
}

Then you can add a condition to the other modules in your add-on that comprise your time tracking implementation, like this:

{
  "condition": "addon_time_tracking_provider_enabled",
  "params": { 
    "addonKey": "add-on-key",
    "moduleKey": "module-key"
  }
}

If an unrecognized addonKey or moduleKey is provided then the condition will simply evaluate to false.

has_attachment condition

The has_attachment condition can be used to check whether the currently displayed issue has any attachments. Additionally, an optional extension param may be provided to check if it has an attachment with a specified file extension (case insensitive).

For example, to check if the issue has any PDF files attached, the condition should be specified thus:

    {
      "condition": "has_attachment",
      "params": { 
        "extension": "pdf"
      }
    }

entity_property_contains_any_user_role condition

The entity_property_contains_any_user_role condition checks whether or not the browser user is in any JIRA project role that is also in a list of roles stored in an entity property. It is aliased by the addon_property_contains_any_user_role condition, for which the entity parameter is omitted.

This is very similar to the entity_property_contains_any_user_group condition.

For example, if you wish to show a web panel on the JIRA view issue page only to users who have at least one of that project's roles then you could use the following condition.

    {
      "condition": "entity_property_contains_any_user_role",
      "params": {
        "entity": "project",
        "propertyKey": "keyOfPropertyContainingMyListOfRoles",
        "objectName": "someObject"
      }
    }

This references an entity property with the key keyOfPropertyContainingMyListOfRoles stored on the issue's project. To evaluate to true it should contain data like the following and the page should be viewed by a user who has the developers role.

 {
   "someObject": [ "developers" ]
 }

The objectName parameter is optional. If omitted then the equivalent entity property value would simply be the array moved up to the root level.

   [ "developers" ]

It is equally possible to store the integer role id instead of its name. This will be less readable but does not change when administrators change role names, so it can be an advantage in some situations. Here is the above example changed to use a role id:

   [ 1234 ]

Mixing role names and ids is also ok:

   [ "developers", 1234 ]

Boolean operations

The Composite Condition module fragment can be used wherever a condition is expected. This allows the construction of boolean expressions aggregating multiple conditions.

For example, the Entity Property tool has a condition that evaluates to true when:

the user is logged in AND 
(
   (the entity property tool is NOT disabled for everybody) OR 
   (the entity property tool is enabled for me)
)

Written as a composite condition that looks like this:

{
    "modules": {
        "webItems": [
            {
                "conditions": [
                    {
                        "condition": "user_is_logged_in"
                    },
                    {
                        "or": [
                            {
                                "condition": "entity_property_equal_to",
                                "invert": true,
                                "params": {
                                    "entity": "addon",
                                    "propertyKey": "ep-tool.disabled-for-all",
                                    "value": "true"
                                }
                            },
                            {
                                "condition": "entity_property_equal_to",
                                "params": {
                                    "entity": "user",
                                    "propertyKey": "ep-tool.enabled-for-me",
                                    "value": "true"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Composite conditions allow "or" and "and" conditions to be written for Atlassian Connect add-ons. You can also get a NOT operation by using the "invert" field on single conditions; as the above example shows.

Note: The top most conditions block is implicitly a composite "and" condition.

Remote conditions

As of Atlassian Connect 1.1.96, remote conditions are deprecated and should not be used. Remote conditions will be removed from JIRA and Confluence on December 1, 2016. If required, please visit an older version of this document.

Appendix: List of predefined conditions

Each product defines a set of conditions relevant to its domain.

Common

  • addon_property_equal_to
  • addon_property_equal_to_context
  • addon_property_contains_any
  • addon_property_contains_all
  • addon_property_contains_context
  • addon_property_contains_any_user_group
  • entity_property_equal_to
  • entity_property_equal_to_context
  • entity_property_contains_any
  • entity_property_contains_all
  • entity_property_contains_context
  • entity_property_contains_any_user_group
  • feature_flag
  • user_is_admin
  • user_is_logged_in
  • user_is_sysadmin
  • addon_is_licensed

Confluence

  • can_edit_space_styles
  • can_signup
  • content_has_any_permissions_set
  • content_property_equal_to
  • content_property_equal_to_context
  • content_property_contains_any
  • content_property_contains_all
  • content_property_contains_context
  • content_property_contains_any_user_group
  • create_content
  • email_address_public
  • favourite_page
  • favourite_space
  • following_target_user
  • has_attachment
  • has_attachment_permission
  • has_blog_post
  • has_comment_permission
  • has_custom_content_permission
  • has_page
  • has_page_permission
  • has_space
  • has_space_permission
  • has_template
  • latest_version
  • not_personal_space
  • printable_version
  • showing_page_attachments
  • space_function_permission
  • space_property_equal_to
  • space_property_equal_to_context
  • space_property_contains_any
  • space_property_contains_all
  • space_property_contains_context
  • space_property_contains_any_user_group
  • space_sidebar
  • target_user_has_personal_blog
  • target_user_has_personal_space
  • threaded_comments
  • tiny_url_supported
  • user_can_create_personal_space
  • user_can_use_confluence
  • user_favouriting_target_user_personal_space
  • user_has_personal_blog
  • user_has_personal_space
  • user_is_confluence_administrator
  • user_logged_in_editable
  • user_watching_page
  • user_watching_space
  • user_watching_space_for_content_type
  • viewing_content
  • viewing_own_profile

Confluence condition parameters

has_attachment_permission, has_comment_permission, has_custom_content_permission, has_page_permission and has_space_permission require a key of the permission that will be checked for the current user to be passed via the permission parameter. Below you will find the keys of the valid permissions.

Permission keys
  • VIEW
  • EDIT
  • SET_PERMISSIONS
  • REMOVE
  • EXPORT
  • ADMINISTER

JIRA

JIRA Service Desk conditions

  • servicedesk.is_agent

    True if user is an agent for a particular Service Desk project

  • servicedesk.is_customer

    True if user raised or is a request participant for a particular Service Desk issue

JIRA condition parameters

has_issue_permission, has_project_permission and has_global_permission require a key of the permission that will be checked for the current user. The first two conditions check project permissions and the last one checks global permissions. Below you will find all the built-in permission keys.

Note that you may also provide any of your custom permission keys (defined in the project or global permission module). Permissions defined by add-ons need to be prefixed with an add-on key followed by two underscores and only then the custom permission key, for example: your.add.on.key__yourPermissionKey.

Project permission keys
  • ADD_COMMENTS
  • ADMINISTER_PROJECTS
  • ASSIGN_ISSUES
  • ASSIGNABLE_USER
  • BROWSE_PROJECTS
  • CLOSE_ISSUES
  • CREATE_ATTACHMENTS
  • CREATE_ISSUES
  • DELETE_ALL_ATTACHMENTS
  • DELETE_ALL_COMMENTS
  • DELETE_ALL_WORKLOGS
  • DELETE_ISSUES
  • DELETE_OWN_ATTACHMENTS
  • DELETE_OWN_COMMENTS
  • DELETE_OWN_WORKLOGS
  • EDIT_ALL_COMMENTS
  • EDIT_ALL_WORKLOGS
  • EDIT_ISSUES
  • EDIT_OWN_COMMENTS
  • EDIT_OWN_WORKLOGS
  • LINK_ISSUES
  • MANAGE_WATCHERS
  • MODIFY_REPORTER
  • MOVE_ISSUES
  • RESOLVE_ISSUES
  • SCHEDULE_ISSUES
  • SET_ISSUE_SECURITY
  • TRANSITION_ISSUES
  • VIEW_DEV_TOOLS
  • VIEW_READONLY_WORKFLOW
  • VIEW_VOTERS_AND_WATCHERS
  • WORK_ON_ISSUES
Global permission keys
  • ADMINISTER
  • SYSTEM_ADMIN
  • USER_PICKER
  • CREATE_SHARED_OBJECTS
  • MANAGE_GROUP_FILTER_SUBSCRIPTIONS
  • BULK_CHANGE