Documentation

Context parameters

Context parameters are additional values pairs that are sent to your add-on in the request URL from the host application.

Table of contents

Standard parameters

The following parameters are common across all requests and are always included in the URL query string.

  • lic: the license status
  • loc: the user's locale (eg: en-GB)
  • tz: the user's timezone (eg: Australia/Sydney)
  • cp: the context path of the instance (eg: /wiki)
  • xdm_e: the base url of the host application, used for the JavaScript bridge (xdm - cross domain messaging)
  • xdm_c: the xdm channel to establish communication over
  • user_id: the user's username. This may change and user_key should be used instead DEPRECATED
  • user_key: the user's unique identifier DEPRECATED
  • cv: the version of Atlassian Connect that made the HTTP request to your add-on.

NOTE The user_id and user_key parameters are deprecated in favour of the context.user JWT claim.

Additional parameters

Your Atlassian Connect add-on can also request context parameters from the Atlassian application by using variable tokens in the URL attributes of your modules. The add-on can use this to present content specific to the context, for example, for the particular JIRA issue or project that is open in the browser. A particular variable is available only where it makes sense given the application context.

URL variables are available to any of the page modules, including web panels, web items, general pages and dialog pages, except for Confluence macros. To add a variable to a URL, enclose the variable name in curly brackets, as follows: {variable.name}. The context variable must be either a path component or the value in a query string parameter formatted as name=value.

For example, the following URL includes variables that are bound to the JIRA project id and current issue key at runtime:

{
    "url": "/myPage/projects/{project.id}?issueKey={issue.key}"
}

Note that conventional URL encoding means that context parameters passed as a query parameter will be encoded slightly differently from those included as a path component. The path component will use percent encoding, while the query component will use application/x-www-form-urlencoded encoding. The primary difference to be aware of is that a space in a query parameter will be encoded as a +, while in the path component it will be encoded as %20.

If the application isn't able to bind a value to the variable at runtime for any reason, it passes an empty value instead.

Inline conditions

Conditions are a powerful way to control whether your UI elements should be shown or not. However, sometimes you may want your element to always be shown but behave differently depending on user permissions or other state that the conditions allow you to check.

You can achieve this goal by putting the conditions in query parameters. The condition will be dynamically evaluated every time the URL is requested based on the current user and context.

The syntax of such variables is as follows (in the BNF notation with optional items enclosed in square brackets):

<variable>        ::=  "condition." <condition-name> [<parameters>]
<parameters>      ::= "(" [<parameters-list>] ")"
<parameters-list> ::=  <parameter-key> "=" <parameter-value> | <parameters-list> "," <parameters-list>

Any condition available in other places can be used as a condition-name; parameter-key and parameter-value are expected to be simple alphanumeric strings with some additional characters like underscores or hyphens.

For example:

 {
     "url": "/myPage/?adminMode={condition.is_admin_mode}",  
     "url2": "/myPage/?adminMode={condition.has_project_permission(permission=BROWSE_PROJECTS)}"
 }

The following conditions do not work as context parameters:

  • user_is_the_logged_in_user (JIRA)
  • following_target_user (Confluence)
  • tiny_url_supported (Confluence)
  • viewing_content (Confluence)
  • viewing_own_profile (Confluence)

JIRA

JIRA supports these context variables.

  • user.id, user.key
  • issue.id, issue.key, issuetype.id
  • project.id, project.key
  • version.id
  • component.id
  • profileUser.name, profileUser.key (available for user profile pages)
  • dashboardItem.id, dashboardItem.key, dashboardItem.viewType, dashboard.id (available for dashboard items)

JIRA issue pages only expose issue and project data. Similarly, version and component information is available only in project administration pages.

JIRA Software

JIRA Software supports these context variables.

  • board.id, board.type, board.screen (available for plugin points that are displayed in multiple board screens), board.mode DEPRECATED in favor of board.screen
  • sprint.id, sprint.state

Confluence

Confluence supports these context variables.

  • user.id, user.key
  • content.id, content.version, content.type, content.plugin
  • space.id, space.key
  • page.id, page.version, page.type DEPRECATED
  • attachment.id, attachment.name, attachment.mediaType

Confluence provides the content.* variables wherever a page, blog post, or custom content is present. Some examples are viewing or editing a page / blog post, or viewing a Confluence Question.

NOTE The page.* variables are available, but have been deprecated in favor of their content.* counterparts.

The content.plugin variable is a special case variable that is only present if the content in question is a Custom Content entity provided by a plugin. For example, a question in Confluence Questions will have a content.plugin value of "com.atlassian.confluence.plugins.confluence-questions:question". As a general rule, the content.plugin variable will only be present if content.type is equal to "custom".

Add-on specific context parameters

Add-ons can define their own context for pages. To do this, add query parameters to the URL of the Atlassian application. Use ac. as the prefix for each query parameter key.

For example:

 {
     "url": "/things/{ac.action}/?thingId={ac.thingId}"
 }

In the url above, {ac.action} and {ac.thingId} will be substituted with values of the ac.action and ac.thingId parameters that are taken from the Atlassian application's current URL. For example, if the application's current URL is http://example.atlassian.net/plugins/servlet/ac/add-on-key/general-page-key?ac.action=edit&ac.thingId=12 then the resulting add-on URL will be /things/edit/?thingId=12.

If there are multiple query parameters with the same name in the Atlassian application URL, only the value of the first occurrence will be used.

You can also provide custom parameters when creating a dialog. To do so, you need to define a dialog module with a url which contains path or query parameters prepended with ac. that you wish to use.

"dialogs": [
      {
        "key": "dialog-module-key"
        "url": "/things/{ac.action}/?thingId={ac.thingId}",
      }
    ]

We can then create a dialog via the JavaScript API with a customData defined as follows:

AP.dialog.create({
    key: 'dialog-module-key',
    width: '500px',
    height: '200px',
    chrome: true,
    customData: {
        action: edit,
        thingId: 12
    }
});

This will result in a dialog which will have the provided data filled in the url.

/things/edit/?thingId=12

Note: Only values which are booleans, numbers or strings less than 255 characters are supported for custom context substitution. Any other invalid input will be ignored.