Last updated Jan 27, 2025

Ending Connect support

You can no longer publish Connect apps on the Atlassian Marketplace. All new extensibility features will be delivered only on Forge.

Refer to this blog post for our timeline to end Connect support.

Have an existing Connect app? You can incrementally migrate it to Forge.

Navigator

The Navigator API enables your add-on to change the page displayed using JavaScript.

Methods

getLocation (callback)

Returns the context of the current page within the host application.

This method will provide a context object to the passed in callback. This context object will contain information about the page currently open in the host application.

The object will contain a target, which can be used when calling the go method, and a context map containing in formation about the opened page.

Currently this method supports two contexts in Confluence only:

contentview: The host application is currently viewing a page, blog post or other content.
contentedit: the host application is currently editing a page, blog post or other content.

Parameters

Name	Type	Description
callback	function	function (location) {...}

Example

1
2
AP.navigator.getLocation(function (location) {
  console.log(location)
  // location will be:
  // {
  //   "target": "contentview",
  //   "context": {
  //     "contentId": 1234,
  //     "contentType": "page",
  //     "spaceKey": "DS"
  //   }
  // }
});

go (target, context)

Navigates the user from the current page to the specified page. This call navigates the host product, not the iframe content.

Requires a target location and the corresponding context. Navigating by passing a concrete url is currently unsupported.

Parameters

Name	Type	Description
target	Navigator~target~Jira \|\| Navigator~target~Confluence	The type of page to navigate to.
context	Navigator~context	Specific information that identifies the page to navigate to.

Example

1
2
// To navigate to the view page for a piece of content in Confluence:
AP.navigator.go('contentview', {contentId: '12345'});

// To navigate to the view page for version 2 of a piece of content in Confluence:
AP.navigator.go('contentview', {contentId: '12345', versionOverride: 2});

// To navigate to the edit page for a piece of content in Confluence:
AP.navigator.go('contentedit', {contentId: '12345'});

// To navigate to the issue view page of an issue in Jira:
AP.navigator.go('issue', {
  issueKey: 'TEST-1'
});

// To navigate to any page in the current site:
AP.navigator.go('site', {
  relativeUrl: '/browse/TEST-1'
});

reload()

Triggers a reload of the parent page.

Throttle is applied to prevent infinite reloads

Example

1
2
AP.navigator.reload();

Types

Navigator~target~Confluence

Defines the available navigation targets for Confluence.

Properties

Name	Type	Description
contentview	String	The view page for pages, blogs and custom content. Takes a `contentId` to identify the content.
contentedit	String	The edit page for pages, blogs and custom content. Takes a `contentId` to identify the content.
spaceview	String	The space view page. Takes a `spaceKey` to identify the space.
spacetools	String	The space tools page. Takes a `spaceKey` to identify the space.
dashboard	String	The dashboard of Confluence.
userProfile	String	The profile page for a specific user. Takes a `username` or `userAccountId` to identify the user.
addonModule	String	The module page within a specific add-on. Takes an `addonKey` and a `moduleKey` to identify the correct module.
contentlist	String	The list/collector page for pages, blogs and custom content contained in a space. Takes a `spaceKey` and a `contentType` to identify the content type.
site	String	A specific location contained within a site. Takes a `relativeUrl` to identify the path.

Navigator~target~Jira

Defines the available navigation targets for Jira.

Properties

Name	Type	Description
dashboard	String	A dashboard in Jira. Takes a `dashboardId` to identify the dashboard.
issue	String	An issue in Jira. Takes an `issueKey` to identify the issue.
addonModule	String	A module page within an add-on. Takes an `addonKey` and a `moduleKey` to identify the module.
userProfile	String	The profile page for a Jira User. Takes a `userAccountId` to identify the user.
projectAdminSummary	String	The admin details of a Jira project. Takes a `projectKey` to identify the project. Only accessible to administrators.
projectAdminTabPanel	String	The admin panel defined by a connect addon. Takes an `addonKey`, `adminPageKey`, `projectKey`, and `projectId`. Only accessible to administrators.
site	String	A location in the site. Takes either a `relativeUrl` or `absoluteUrl` to identify the path.

Navigator~context

Defines the context information required for navigation targets.

Properties

Name	Type	Description
contentId	String	Identifies a piece of content. Required for the `contentView` target.
contentType	String	Identifies the type of content. Can be either `page` or `blogpost`. Required for the `contentEdit` target.
spaceKey	String	Identifies a space. Required for the `spaceView` and `spaceTools` targets.
username	String	Identifies a user. One of this or `userAccountId` required for the `userProfile` target.
userAccountId	String	Identifies a user. One of this or `username` required for the `userProfile` target.
addonKey	String	Identifies a connect add-on. Required for the `addonModule` and `projectAdminTabPanel` targets.
moduleKey	String	Identifies a connect add-on module. Required for the `addonModule` target.
dashboardId	String	Identifies a Jira dashboard. Required for the `dashboard` target in Jira.
projectKey	String	Identifies a Jira project. Required for the `projectSummary`, `projectAdminSummary` and `projectAdminTabPanel` targets.
issueKey	String	Identifies a Jira issue. Required for the `issue` target.
adminPageKey	String	Identifies a Jira Project Admin Tab Panels module key. Required for the `projectAdminTabPanel` target.
projectId	String	Identifies a Jira Project by its ID number. Required for the `projectAdminTabPanel` target.
customData	String	Contains parameters that will be added as query parameters to the product url with "ac." prepended. Used only in `addonModule` target. See Add-on specific context parameters for more info.
embeddedContentRender	String	Identifies the mode for rendering embedded content in Confluence, such as attachments embedded in a page. This only applies to the `contentView` target. Valid values are `current` (render the embedded content using the latest version) and `version-at-save` (render the embedded content using the version at the time the content was saved). This parameter is optional and defaults to `current`.
relativeUrl	String	Identifies a specific page within a site. Required for the `site` target and must begin with `/`.
absoluteUrl	String	Identifies a specific page within a site. Required for the `site` target and must be within the site's domain.