This page describes an example of how to set up a common application links scenario — creating a two-way link between two applications that trust each other and share the same set of users. For example, you may wish to link your internal JIRA server to a private FishEye server. Setting up an application link allows you to take advantage of integration features like viewing FishEye changesets in JIRA. The instructions below also detail how to link two entities of your two linked applications, e.g. a JIRA project to a FishEye repository. Linking two entities will enable other integration features, such as link rendering.
Applications Links is bundled with FishEye 2.4 and will be bundled with Confluence 3.5 and JIRA 4.3. If one of the applications you are connecting to does not have Applinks, you can still set up an application link to it. See Adding an Application Link.
On this page:
Before You Begin
- The instructions below describe how to link a FishEye server to a JIRA server. However, the instructions will be similar for other Atlassian applications.
- You must be an administrator with permissions to configure changes at the application level, for both of your applications. That is, you must be a 'JIRA System Administrator' in JIRA, not a 'JIRA Administrator'.
- Your local application (FishEye) must have Unified Application Links (UAL) installed. You can link from an application with UAL to an application that does not have UAL (as described on this page), however you will have to configure authentication manually (see Configuring Authentication for an Application Link).
- Make sure that the base URL is set correctly in both the local application and the remote application, (JIRA instructions | Confluence instructions | FishEye/Crucible instructions | Bamboo instructions).
Adding an Application Link
In this example, we will create a two-way Trusted Apps application link between a "local" FishEye server with UAL ((http://fisheye.example.com/ in this example) and a "remote" JIRA server without UAL (http://jira.example.com/ in this example). We'll add the link from the FishEye server.
In FishEye, do the following: Log in as an administrator and navigate to the administration page. Click 'Application Links' in the administration menu. The 'Configure Application Links' page will be displayed, listing all of the application links that have currently been set up for your application. Click 'Add Application Link' to open the add application link wizard.
1. Specifying the Remote Application
First, we need to specify which application we are linking to. Enter the URL for the JIRA server in the 'Link to another server' dialogue, as shown in the screenshot below, and click 'Next'.
Screenshot: Entering the server URLGliffy
2. Creating the Application Link
Enter an 'Application Name' and choose the 'Application Type' to be 'JIRA'. Click the 'Create' button. The application link will be created and displayed on the 'Configure Application Links' page.
Our JIRA server does not have UAL, so we cannot automatically create a link back to our FishEye server nor set up authentication. We'll manually set these up in the next step.
Screenshot: Creating the application linkGliffy
3. Configuring Authentication for the Application Link
We are going to use Trusted Apps authentication for all incoming and outgoing requests via the application link, as both servers share the same userbase. Trusted Apps authentication is recommended when both applications fully trust each other and share the same set of users (read more about configuring Trusted Apps authentication). Other authentication configurations are described in Configuring Authentication for an Application Link.
On the 'Configure Application Links' page, click the 'Configure' link next to the application link just created. The configuration dialogue for the application link will be displayed.
First, we need to configure our JIRA server to trust our FishEye server. Navigate to the 'Outgoing Authentication' tab on the configuration dialogue and click the 'Configure' button on the 'Trusted Applications' sub-tab. Click the 'Apply' button to apply trusted apps authentication.
We also need to configure our FishEye server to trust our JIRA server. Navigate to the 'Incoming Authentication' tab on the configuration dialogue and click the 'Configure' button on the 'Trusted Applications' sub-tab. Click the 'Apply' button to apply trusted apps authentication.
Screenshot: Setting up Trusted Apps authentication for an application link (click to view larger image)Gliffy
4. Additional JIRA Configuration
Our JIRA server does not have UAL, so we need to perform additional trusted apps configuration in JIRA before our application link will work.
Follow the instructions on adding a trusted app in the JIRA documentation: Configuring Trusted Applications. You will need to enter the following information:
- 'Base URL' — Enter the URL of your FishEye server, 'http://fisheye.example.com/'
- 'Application Name' — Enter the name for your FishEye server, 'Example FishEye'.
- 'Timeout' — '10000'
- 'IP Addresses' — Leave this blank, unless you are using a proxy server (if so, see the trusted apps documentation for further instructions).
- 'URL Patterns' — Enter the following URLs:
/sr/jira.issueviews:searchrequest, /secure/RunPortlet, /rest, /rpc/soap
You may also want to enable issues activity in your activity stream. To do this, navigate to your Application Links and click the 'JIRA settings' link next to your application link. Tick the 'Include in 'Activity Streams' checkbox and click 'Save'.
Congratulations, you've just created an application link!
Adding an Entity Link for the Application Link
Once you have added an application link, you may wish to link entities between the applications. Linking entities enables additional integration features, such as link rendering. An entity is one of the following:
- JIRA project
- Confluence space
- FishEye repository
- FishEye project (this is the Crucible project if it is a FishEye/Crucible server, otherwise it is the paths associated via the 'FishEye Project Content' function in FishEye)
- Crucible project
In the following example, we'll create an two-way entity link between a JIRA project (project key is 'MYPROJECT') and a FishEye repository (repository key is 'MYREPO'), for the application link we previously created.
First, navigate to the FishEye administration console and find the repository that you want to link from. Click the icon and select 'Application Links' from the dropdown menu. The entity links screen will be displayed.
Screenshot: Entity links for a FishEye repository
Click 'Add Entity Link' and click the remote application where the target entity is located. In this case, it will be the 'Example JIRA' application that we linked to previously. The add entity link dialogue will be displayed.
Screenshot: Adding an entity link
Enter the key ('MYPROJECT') and an alias, i.e. display name, for the entity ('My Project'). Click 'Create' to create the entity link.
Congratulations, you've just added an entity link!
You've now successfully linked your JIRA server to a FishEye server. Try out some of the integration features enabled by your new application link, including: