Is it fine to rely on undocumented Custom UI context properties?

Forge Forge UI Kit and Custom UI
, ,
1

The context object returned by view.getContext() does not match the current documentation or TypeScript types. We see additional properties that are not documented.

In my particular case, I am looking at the permissions property and wonder if:

  1. Is it fine to rely on undocumented Custom UI context properties?
  2. Is it safe to build code that relies on the permission data provided?
  3. Is this property always available with the structure and properties shown below (scopes, external, etc.)?
  4. Why does the read:app-system-token scope appear twice? Appears to be a bug.

Below is an extract of the context object, including the permission object that I get in my Custom UI.

{
    ...
    "permissions": {
        "scopes": [
            "read:app-system-token",
            "read:app-system-token",
            "read:connect-jira",
            "read:jira-user",
            "read:jira-work",
            "storage:app",
            "write:jira-work"
        ],
        "external": {
            "fetch": {
                "backend": [
                    "https://example.com"
                ],
                "client": [
                    "https://example.com"
                ]
            },
            "fonts": [],
            "styles": [],
            "frames": [],
            "images": [
                "*.example.com"
            ],
            "media": [],
            "scripts": [
                "https://example.com"
            ]
        }
    }
}
2

Reviving this unanswered old thread to add another question: How did you even manage to have permissions.scopes listed in the result of view.getContext()? I’m asking because in my new currently-developed app (only on development environment currently, not yet on staging or production) I don’t have any; permissions.scopes is empty in my case, despite having 5 scopes defined in my manifest.yml, incl. read:account which needs user-consent.
Is that data available only on production, not on development or staging? The 2nd paragraph of this docu about Forge environments mentions something like this; not sure if this applies for forge/bridge’s view.getContext().

My use-case is that I want to invoke resolver-handlers only if the user consented already, and otherwise do something else. We are unhappy with Jira’s/Forge’s(?) default “Access required”-popup that would pop up in this case, because it does not state the offending app’s name, so end-users might be confused about what exactly needs access. I’m talking about this popup here:

image
image633×188 11.9 KB

@CaterinaCurti, I saw you on other threads about similar topics. Any insights you could share here?

3

I just posted in RFC-138 about the broader point here: Forge context needs a clearer contract, ideally with documented schemas and generated TypeScript types/documentation per module.