Context parameters

Context parameters are placeholders you can put into a module's URL to have Bitbucket send contextual information with each request to that module. They follow the same pattern as if they were normal API objects.

In fact you can deduce all the parameters from the API JSON object. Let's start by looking at an example repository object:

1
2
{
    "scm": "git",
    "website": "",
    "has_wiki": true,
    "name": "documentation-tests",
    "links": {...},
    "fork_policy": "allow_forks",
    "uuid": "{b4434b4d-6a0e-4f57-8d75-e02a824abeb0}",
    "project": {...},
        "name": "Master station"
    },
    "language": "",
    "created_on": "2014-07-24T21:48:26.648365+00:00",
    "full_name": "teamsinspace/documentation-tests",
    "has_issues": true,
    "owner": {
        "username": "teamsinspace",
        "display_name": "Teams In Space ",
        "type": "team",
        "uuid": "{61fc5cf6-d054-47d2-b4a9-061ccf858379}",
        "links": {...}
    },
    ...
}

In that object you can see:

1
2
"full_name": "teamsinspace/documentation-tests"

We need to include the repository parameter first since that's the object we're looking at. To call the full_name context parameter you would use the format:

1
2
https://example.com?repoPath={repository.full_name}

Which might look like this in the descriptor:

1
2
        "repoPages": [
            {
                "url": "https://example.com?repoPath={repository.full_name}",
                "name": {
                    "value": "Example Page"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-repo-page",
                "params": {
                    "auiIcon": "aui-iconfont-doc"
                }
            }
        ],

Let's dig in a little deeper

Let's say you want the uuid of a repository's owner displayed in a module.

The context parameter might look like this:

1
2
https://example.com?repoOwner={repository.owner.uuid}

The parameters it references are repository.owner.uuid.

When you look at the response object from a repository API call you can see the uuid nested within the owner parameter:

1
2
{...
    "uuid": "{b4434b4d-6a0e-4f57-8d75-e02a824abeb0}",
    "project": {...
    },
    "language": "",
    "created_on": "2014-07-24T21:48:26.648365+00:00",
    "full_name": "teamsinspace/documentation-tests",
    "has_issues": true,
    "owner": {
        "username": "teamsinspace",
        "display_name": "Teams In Space ",
        "type": "team",
        "uuid": "{61fc5cf6-d054-47d2-b4a9-061ccf858379}",
        "links": {...
            }
        }
    },
    "updated_on": "2016-07-29T18:45:36.317590+00:00",
    "size": 1172663,
    "type": "repository",
    "is_private": false,
    "description": ""

You format your parameter as {repository.owner.uuid} because the repository has the owner and the owner has the UUID.

Your parameter might look like this in the descriptor:

1
2
        "webItems": [
            {
                "url": "https://example.com?repoOwner={repository.owner.uuid}",
                "name": {
                    "value": "Example Web Item"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-web-item",
                "params": {
                    "auiIcon": "aui-iconfont-link"
                }
            }
        ],

You can expand this base concept to create more complex calls using context parameters like so:

1
2
https://myapp.example.com/pages/repos/{pullrequest.to_repository.full_name}/pulls/{pullrequest.id}?currentUser={user.uuid}

Even more complex:

1
2
https://myapp.example.com/pages/repos/{issue.repository.uuid}/issuepage/{issue.id}/comments?reporter={issue.reporter.uuid}&issueLink={issue.links.html.href}

Context parameters in path segments

Variables are replaced by their runtime value. In some cases your parameter's value might be an empty string. This can be problematic when you use it as part of your path. For instance, if a repository object does not have a description, /repos/{repository.description}/foo/ turns into /repos//foo/, which many webservers and frameworks might normalize as if there was only one slash (/repos/foo/), which could effectively make the variable disappear.

To avoid this potential ambiguity you could move the parameters into the query string.

1
2
/repos/foo?currentUser={user.uuid}

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.

For example:

1
2
{
    "url": "/myPage/?has_access={target_user.meets_access_requirements()}",
    "url2": "/myPage/?isAdmin={repository.has_permission(permission=\"admin\")}"
}

Location and contexts

The location of the module determines which context parameters are available for use. The general idea is that if you can do it on that page those contexts apply.

For example a webItem on the Pull Request page could have these parameters:

• pullrequest
• repository
• user
• target_user

User and target_user

The user is the currently authenticated user. This is the person actually using Bitbucket and your app.

The target_user is the principal owner of the thing (repository, snippet, file, other...) the user is viewing or interacting with.

Context parameters based on module

The following context objects are available for each of these modules.

Context parameters based on location

The following context objects are available for these locations.