JetBrains Space Help

Add Custom Menu Items

An applications can add custom menu items to Space context menus. When a user clicks on a custom item, Space sends a message to the application. The message contains a payload of the MenuActionPayload type. Here you can find an example of an application that extends Space with custom menu items.

Custom menu item

Where you can add custom menu items

Currently, the context menus of the following Space entities can be extended with custom items:

  • Issues.

  • Chat messages.

  • Documents.

  • Document folders.

  • Meetings.

Add custom menu items

To add a custom menu item, the application must make the setUiExtensions API call. For example, this is how you can add an item to the issue context menu:

// using Kotlin SDK spaceClient.applications.setUiExtensions( // add issue menu item globally, for all projects contextIdentifier = GlobalPermissionContextIdentifier, // list of extensions: just a single menu item extensions = listOf( IssueMenuItemUiExtensionIn( // item name shown in the context menu displayName = "Create sub-tasks", // menu item description for the app home page description = "Create sub-tasks for current issue", // identify the menu item when it's clicked menuItemUniqueCode = "create-sub-tasks", // show the item only to users who can edit the issue visibilityFilters = listOf(IssueEditableByMe), ) ) )

For the list of possible extensions, see the setUiExtensions method in the API Playground. To see how the method is called in a real application, see our sample application.

The added menu item will be shown on the application's page in Space, namely, on the Authorization tab:

Added custom menu items

Enable custom menu items for Space users

By default, the items are enabled only for the user who installed the application (application owner). This can be changed on the application's Authorization tab. When creating an application, make sure to provide your users with the instructions on how they can enable the menu items in the required context.

An administrator with the System admin role can enable the menu items for all users in their Space organization. To do this, turn on Enabled by default for everybody.

A project or a channel administrator can enable the items for the corresponding project or channel:

  1. In In-Context Authorization, use the Authorize in project or Authorize in channel button to authorize the application in the requried context.

  2. Open project or channel authorization settings and enable the extension feature.

Handle menu item clicks

1. Handle MenuActionPayload

When a user clicks on the custom menu item, your application receives a payload of the MenuActionPayload type. Your application must accept this type. For example, if you use Space SDK:

when (payload) { is MenuActionPayload -> { // do something... } }

At this point, the application can perform an action in Space on behalf of itself or on behalf of a user. To perform an action on behalf of a user, the application needs to get the user's consent first. Learn more about user consents. To get the consent, respond to the MenuActionPayload with this kind of response:

// define permission scope: operations you need to perform on behalf of the user val permissionScope = "global:Project.Issues.Create global:Project.Issues.View global:Project.Issues.Edit" val response = AppUserActionExecutionResult.AuthCodeFlowRequired(listOf( AuthCodeFlowRightsRequest(permissionScope, purpose = "create task sub-items")) )

The code above requests permissions in all projects. The application can also request permissions only in a single project. Learn more about permission context.

3. Save the user access token

After Space receives permission request, it shows the user a consent dialog. If they agree, Space sends a RefreshTokenPayload to the application. The refresh token allows the application to access Space on behalf of the user with no time limit (or until the user revokes the authorization). To save the refresh token:

when (payload) { is RefreshTokenPayload -> { // save refresh token in a persistant storage, respond with 200 OK } }

4. Get action context

After the application successfully obtains the refresh token (Space receives HTTP 200 OK), Space sends the MenuActionPayload one more time. This is done to free the user from the need to click the menu item for the second time. This time, the application can use the refresh token to perform the required action.

The MenuActionPayload contains context: an object on which the menu item was invoked. For example, we know that our application extends the issue context menu, so the context must contain data about the corresponding issue:

val context = payload.context as IssueMenuActionContext val issue = spaceClient.projects.planning.issues.getIssue(context.projectIdentifier, context.issueIdentifier)

5. Perform the action

After the application gets the context, it can perform the action. For example, create issue sub-items:

listOf( "Pricing plan", "Proofreading", "Marketing Materials", "Documentation", "Metrics", "UI tests", ).forEach { client.projects.planning.issues.createIssue( context.projectIdentifier, title = "${issue.title}: $it", status = status, parents = listOf(context.issueIdentifier) ) }
Last modified: 25 November 2022