Registering External Gadgets
You can register gadgets from external sites (such as Jira applications), so the gadgets appear in the macro browser and people can add them to Confluence pages using the gadget macro.
There's two ways to register external gadgets:
- Subscribe to all of the external application's gadgets: You can add all the gadgets from your Jira application, Bamboo, FishEye or Crucible site – or from another Confluence site – to your Confluence gadget directory. People can then pick and choose the gadgets to add to their Confluence pages.
- Register the external gadgets one by one: If you cannot subscribe to an application's gadgets, you will need to add the gadgets one by one. This is necessary for applications and websites that do not support gadget subscription, and for applications where you cannot establish a trusted relationship via Application Links.
Both methods are described below. First, consider whether you need to set up a trust relationship between Confluence and the other application.
On this page:
Related pages:
Setting up a trust relationship with the other application
In addition to registering the external gadgets, we recommend that you set up an OAuth or Trusted Application relationship between the application that serves the gadget (the service provider) and Confluence (the consumer). The trust relationship is required for gadgets that access restricted data from the external web application.
See how to configure OAuth or Trusted Applications Authentication, using Application Links.
If the external web application provides anonymous access to all the data you need in the gadgets, then you do not need a trust relationship.
For example, if your gadgets will retrieve data from Jira and your Jira server includes projects and issues that are restricted to logged-in users, then you will need a trust relationship between Confluence and Jira. If you do not set up the trust relationship, then the gadgets will show only the information that Jira makes visible to anonymous users.
If you want to subscribe a third-party gadget, that doesn't require an application link, you will also need to add the gadget URL to the allowlist.
Subscribing to all of the application's gadgets
You can add all the gadgets from your Jira, Bamboo, FishEye or Crucible site – or from another Confluence site – to your Confluence gadget directory. People can then pick and choose the gadgets to add to their Confluence pages.
To subscribe to another site's gadgets:
- Go to Administration
> General Configuration > External Gadgets - Choose the Gadget Feeds tab.
- Enter the base URL of the application you want to subscribe to, for example,
http://example.com/jiraorhttp://example.com/confluence. - Choose Add. Confluence will convert the URL to a gadget feed and place it in the list of 'Added Gadget Feeds'.
Screenshot: Subscribing to a gadget feed
Registering individual gadgets
If you cannot subscribe to an application's gadgets, you will need to register the gadgets one by one. This is necessary for applications and websites that do not support gadget subscription, and for applications where you cannot establish a trusted relationship via Application Links.
First you will need to get the gadget URL and copy it to your clipboard.
Getting a gadget's URL from an Atlassian application
If your application is another Atlassian application:
http://example.com/my-gadget-location/my-gadget.xmlIf the gadget is supplied by a plugin, the URL will have this format:
http://my-app.my-server.com:port/rest/gadgets/1.0/g/my-plugin.key:my-gadget/my-path/my-gadget.xml
For example:
http://mycompany.com/jira/rest/gadgets/1.0/g/com.atlassian.streams.streams-jira-plugin:activitystream-gadget/gadgets/activitystream-gadget.xml
To find a gadget's URL in JIRA:
- Go to your dashboard by clicking the Dashboards link at the top left of the screen.
- Click Add Gadget to see the list of gadgets in the directory.
- Find the gadget you want, using one or more of the following tools:
- Use the scroll bar on the right to move up and down the list of gadgets.
- Select a category in the left-hand panel to display only gadgets in that category.
- Start typing a key word for your gadget in the Search textbox. The list of gadgets will change as you type, showing only gadgets that match your search term.
- Right-click the Gadget URL link for that gadget and copy the gadget's URL into your clipboard.
To find a gadget's URL in Confluence:
- Choose Help > Confluence Gadgets to see the list of available Confluence gadgets.
- Find the gadget you want.
- Right-click the Gadget URL link for that gadget and copy the gadget's URL into your clipboard.
Getting a gadget's URL from another application
If the gadget comes from a non-Atlassian web application or web site, please consult the relevant documentation for that application to get the gadget URL.
Registering the gadget for use in Confluence
Now that you have the gadget's URL, you can register it in Confluence, so that people can add it to their pages. You need system administrator permissions to register a gadget.
To register the gadget in Confluence:
- Go to Administration > General Configuration > External Gadgets
- Paste your gadget's URL into the Gadget Specification URL field in the 'Add a new Gadget' section.
- Choose Add. Your gadget will be shown in the list of registered gadgets below and it will also become available in the macro browser.
Screenshot: Registering external gadgets one by one
Removing access to external gadgets
To remove a single gadget from Confluence, click the Delete button next to the gadget URL.
If you have subscribed to an application's gadgets, you will need to remove the entire subscription. You cannot unregister a single gadget. Click the Delete button next to the gadget feed URL.
The gadget(s) will no longer be available in the macro browser, and people will not be able to add them using the Gadget macro. Any pages that already use the gadget will show a broken gadget link.