Managing Friends

A friend is another web application that allows this application to send requests on behalf of an authorized user. In other words, a friend is a server application that makes its information available for consulting (or possibly creating/updating) to this application using an authorized friend-application user.

Friends are needed to create outgoing Collaboration Links, this means you need to register the OSLC Remote Application as a friend of Jira if you want to create Collaboration Links on Jira side; keep in mind that additional configuration will be required on the OSLC Remote Application side, but for now let's focus on the requirements of this side.

It is worth to mention that a friend is not bound to any particular friend-application user; at the proper working moment, the friend will request the friend-application user credentials to allow this application work on behalf of it (a process known as "user authentication").

Registering a Friend.

  1. Enter to the JIRA ADMINISTRATION > Manage apps page.
  2. On the left panel, click on the Friends option in the OSLC Connect section.
  3. Click on the Add Friend button at the top of the right panel.
  4. Fill out the form on the Add Friend dialog according to the following field descriptions:
    Field Required Description Notes Suggested Value
    Title Yes A logical name for human identification. Commonly the server application name. The OSLC Remote Application name.
    Root Services URI Yes The endpoint of the friend's root services service. Must be provided by the OSLC Remote Application administrator and must use the same transfer protocol (HTTP or HTTPS) as the Jira server. A valid provided root services URL.
    Key Yes Must select either you want to create (request) a provisional key or to reuse an existing one. Requesting a provisional key means the OSLC Remote Application must approve your request before you can start accessing the system. Reuse an existing one means you have been already granted with access to the system and therefore, you will be provided with the corresponding consumer's key and secret. Create Provisional
    Trusted No Whether the provisional key will be deemed as trusted or not. This field will be visible only if "Create Provisional" Key value is selected. checked
    Existing key Yes The existing authorized key to be reused. This field will be visible only if "Reuse Existing" Key value is selected. An authorized existing key.
    Secret Yes This application password. How this application will be authenticated on the server. The corresponding Key password if "Reuse Existing" Key value was selected; whatever you want as long as you don't forget it otherwise.
    Confirm Secret Yes Password confirmation Just a confirmation field to avoid password typos. The same as Secret field.
  5. Click on the Add button.

If you requested a provisional key, a second dialog is open (Authorize Provisional Key) to remind the user this key still needs to be authorized on the remote server before using it. If the OSLC Remote Application supports the remote authorization of provisional keys, this dialog will give a chance to do so from Jira. This works only if you happen to be also an administrator of the OSLC Remote Application. If this works for you, click on the Grant access for the provisional key link (only visible if remote application supports this feature). You will be asked to login in the remote application or, if you had a session already started, just follow the remote instructions to approve the provisional key, this is done typically by clicking on some Approve button. Close the Authorize Provisional Key dialog, by clicking on the OK button, when the remote application indicates provisional key has been authorized.

A new friend entry will be displayed on the Friends list. Note only the Friend Name, Root Services URI and Friend Key fields will be shown along with the current State of the friend (see details below).

Refreshing Friends' States.

Friends' states allow monitoring the health of friend applications, from this connector perspective, and possible values are:

To improve performance, these states are not computed as administrator(s) enter on the friends page, they are computed and cached at connector startup time and they will be updated (automatically in the background) every hour. If you want to make sure you are seeing the latest results, you can click on the Refresh State button. Note it may take a while in the case of some friends being Offline. It's worth to mention that OSLC Connect for Jira assigns a request timeout of one minute per registered friend to refresh their states. In the case the overall refresh request takes more than that, friends' state will change to Unknown and the legend Refresh process is taking too much, please try again later. will be displayed.

Removing a Friend.

  1. Enter to the JIRA ADMINISTRATION > Manage apps page.
  2. On the left panel, click on the Friends option in the OSLC Connect section.
  3. Locate the Registered Friends section and table at the middle of the center panel.
  4. Choose the friend you want to remove and click on the cross icon located on the last column of the table.
  5. Confirm your decision by clicking on the OK button in the confirmation dialog.

If everything went ok, the chosen friend will be removed from the system and it will no longer appear on the table.

Updating a Friend.

  1. Enter to the JIRA ADMINISTRATION > Manage apps page.
  2. On the left panel, click on the Friends option in the OSLC Connect section.
  3. Locate the Registered Friends section and table at the middle of the center panel.
  4. Choose the friend you want to update and click on the pencil icon located on the last column of the table.
  5. Update friend's information in the opened dialog (only Title and Secret fields can be updated).
  6. Click on the Save button to save these changes.

If everything went ok, the chosen friend will be updated and changes will be reflected in the list. Note: saving will be rejected when changing Secret if this does not match with the corresponding remote consumer secret.