Jira Global Permission module and Jira Project Permission module

This page describes how to migrate a Jira Global Permission module and a Jira Project Permission module from Connect to Forge.

Note that migrated permission modules will be exposed by the Forge platform using their original Connect-style identifier.

This process consists of four major steps:

• Follow the instructions outlined in the parent page.
• Move the permission modules from the connectModules section to the modules section.
• Make sure references to these permission modules keep using the Connect-style format .
• Test that everything works as expected.

Keep reading for more details.

Example

Let's assume that in its app descriptor, our Connect app declares a Global Permission module and a Project Permission module:

1
2
{
  "modules": {
    "jiraGlobalPermissions": [
      {
        "description": {
          "value": "Custom Global Permission by Connect app"
        },
        "anonymousAllowed": false,
        "defaultGrants": [
          "all"
        ],
        "name": {
          "value": "My Global Permission from Connect"
        },
        "key": "my-global-permission"
      }
    ],
    "jiraProjectPermissions": [
      {
        "description": {
          "value": "Custom Project Permission by Connect app"
        },
        "category": "projects",
        "name": {
          "value": "My Project Permission from Connect"
        },
        "key": "my-project-permission"
      }
    ]
  }
}

Let's also assume that these permissions are used respectively, via the conditions element, a General Page module, and a Project Page module:

1
2
{
  "modules": {
    "generalPages": [
      {
        "key": "home-1",
        "location": "system.top.navigation.bar",
        "name": {
          "value": "My General Page"
        },
        "url": "/generalpage",
        "conditions": [
          {
            "condition": "has_global_permission",
            "params": {
              "permission": "${addon.key}__my-global-permission"
            }
          }
        ]
      }
    ],
    "jiraProjectPages": [
      {
        "key": "home-2",
        "location": "system.top.navigation.bar",
        "name": {
          "value": "My Project Page"
        },
        "url": "/projectpage",
        "conditions": [
          {
            "condition": "has_project_permission",
            "params": {
              "permission": "${addon.key}__my-project-permission"
            }
          }
        ]
      }
    ]
  }
}

The steps described in the parent page will generate a Forge manifest that looks like the following:

1
2
connectModules:
  jira:generalPages:
    - key: home-1
      location: system.top.navigation.bar
      name:
        value: My General Page
      url: /generalpage
      conditions:
        - condition: has_global_permission
          params:
            permission: permission-migration-test-app__my-global-permission
  jira:jiraProjectPages:
    - key: home-2
      location: system.top.navigation.bar
      name:
        value: My Project Page
      url: /projectpage
      conditions:
        - condition: has_project_permission
          params:
            permission: permission-migration-test-app__my-project-permission
  jira:jiraGlobalPermissions:
      - description:
          value: Custom Global Permission by Connect app
        anonymousAllowed: false
        defaultGrants:
          - all
        name:
          value: My Global Permission from Connect
        key: global-connect-permission
  jira:jiraProjectPermissions:
    - description:
        value: Custom Project Permission by Connect app
      category: projects
      name:
        value: My Project Permission from Connect
      key: my-project-permission

You can now move the jira:jiraGlobalPermissions and jira:jiraProjectPermissions modules from the connectModules: section to the modules: section. This will transform them into native Forge modules. Note that the migratedFromConnect field must be set to true.

1
2
modules:
  jira:projectPermission:
    - key: "my-project-permission"
      name: "My Project Permission from Forge"
      description: "Custom Project Permission by Forge app"
      category: projects
      migratedFromConnect: true
  jira:globalPermission:
    - key: "global-connect-permission"
      name: "My Global Permission from Forge"
      description: "Custom Global Permission by Forge app"
      anonymousAllowed: false
      defaultGrants:
        - "all"
      migratedFromConnect: true

Note also that the module keys used to reference the permissions, such as permission-migration-test-app__my-project-permission, need to correspond to the module keys from the original Connect modules. This is because modules marked with migratedFromConnect: true are exposed by the Forge platform using the Connect-style module identifier format ${app_key}__${moduleKey}.

Testing

You are now ready verify the migration on the Jira instance that your team uses for testing.

1. Install the Connect app.
2. Install the Forge app.
3. Verify that the permission name reflects the one used by Forge (if different).
4. Verify that existing permission conditions work as expected.
   1. Project Pages and Global Pages referencing the migrated permission modules are displayed or hidden appropriately, based on the permissions in the permission scheme used by your Jira project.