Access to context parameters

To use context parameters in a descriptor the corresponding scopes should be provided. If the required scopes are not specified the context parameters won’t be replaced.

Please refer to the table to see required scopes for each context parameter:

Certain conditions will also require an additional scope according to the table bellow:

Examples

Context parameters in a URL

In this example, we used context parameters repository.uuid and pullrequest.id. According to the table, we need to provide repository and pullrequest scopes to populate context data in the url.

1
2
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "url": "/selectTarget?repository={repository.uuid}&pr={pullrequest.id}",
                "location": "org.bitbucket.pullrequest.summary.actions",
                "key": "webItem-example",
                "name": {
                    "value": "WebItem example"
                }
            }
        ]
    },
    "scopes": ["repository", "pullrequest"]
}

NOTE: In this example you can also provide pullrequest scope only as it implies repository.

Multiple context objects in one context parameter

In the url below, we reference several context objects in one context parameter - repository, app and user. app doesn't require a scope, so we need to add just repository and account scopes to the descriptor.

1
2
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "url": "/url?enabled=repository.properties.get(attribute=app.key).enabled.get(attribute=user.uuid)",
                "location": "org.bitbucket.pullrequest.summary.actions",
                "key": "webItem-example",
                "name": {
                    "value": "WebItem example"
                }
            }
        ]
    },
    "scopes": ["repository", "account"]
}

Context parameters in conditions

Context parameters used in a condition also requires a scope. In this example, we used repository.owner.uuid as a condition target and user.uuid as a condition value. So we should add repository and account scopes to the descriptor.

1
2
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "conditions": [
                    {
                        "condition": "equals",
                        "target": "repository.owner.uuid",
                        "params": {
                            "value": {
                                "eval": "user.uuid"
                            }
                        }

                    }
                ]
            }
        ]
    },
    "scopes": ["repository", "account"]
}

Inline conditions

In this example, we access a repository context data and use has_account_permission condition so required scopes are repository and account

1
2
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "url": "/url?is_admin={repository.owner.has_account_permission(permission=\"admin\")}",
                "location": "org.bitbucket.pullrequest.summary.actions",
                "key": "webItem-example",
                "name": {
                    "value": "WebItem example"
                }
            }
        ]
    },
    "scopes": ["repository", "account"]
}

Module condition section

In this example we use multiple conditions:

1. equals condition requires repository and account scopes to access context data.
2. user_has_premium condition requires account scope.
3. has_addon condition requires account scope to evaluate condition and repository scope to substitute target

As a result, repository and account scopes should be provided in the scope section.

1
2
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "conditions": [
                    {
                        "condition": "equals",
                        "target": "repository.owner.uuid",
                        "params": {
                            "value": {
                                "eval": "user.uuid"
                            }
                        }
                    },
                    {
                        "condition": "user_has_premium"
                    },
                    {
                        "condition": "has_addon",
                        "target": "repository.owner",
                        "params": {
                            "key": "my-addon"
                        },
                        "invert": true
                    }
                ]
            }
        ]
    },
    "scopes": ["repository", "account"]
}