Table of contents

Definition

URL datasources can be used to connect Elements Connect custom fields to a server through the HTTP protocol.

This datasource gives you access to various remote REST APIs. 
HTTP and HTTPS protocols are supported and the only method allowed is GET.

Datasource configuration

This field must contain the root URL to your service (Example: http://myserver.mycompany.com/REST-API).

One thing to keep in mind is that this url value will be concatenated with what is defined in your Elements Connect field configuration 'query' property.

The rule is simple:

• if the Elements Connect field query result is empty, the final URL is the datasource URL unchanged
• if the Elements Connect field query result is not empty, the final URL is the concatenation of the datasource URL, a "/" char and the field query.

Authentication

Elements Connect supports multiple authentication methods:

• Basic HTTP: This mode that allows to provide a login and password to the server. It is recommended to use with the HTTPS protocol.
• OAuth2 : A more secured authentication mode used by many remote systems. Elements Connect supports the OAuth2 authorization code grant type.
• Headers: A popular authentication mode, where credentials - often an API Key - are passed in the HTTP headers
• URL param: Similar to the "Headers" authentication mode, the API key is provided as a URL parameter. If you want to use this authentication mode, you'll have to configure the URL parameter at the field configuration level.
  

Timeout

Retrieving data from a URL datasource is done in two steps:

1. Connect - Establishing the connection to the remote server
2. Read - Reading data from the remote server

When a remote server is down or over loaded it can take time to provide a response.
A long delay can have a negative impact on the Jira load time, wether a user is editing a viewing an Issue.

That's why two timeouts are set on URL datasources:

1. Connect timeout - A non configurable 5 seconds timeout applied to the "Connection" step.
2. Read timeout - A configurable timeout with a default value of 10 seconds applied to the "Read" step
   This value can be configured from the datasource configuration, from 1 second to 60 seconds.
   The lower this value, the less impact a slow remote server might have on the Jira load time.

When a timeout is reached, the query to the remote server is aborted.
Elements Connect behavior depends on the context:

• Field edit: no option available in the field editor
• Issue display: you'll see the field "stored" value (the field key) on which the "No result template" is optionally applied

Other datasources: The "Connect" timeout is hardcoded for URL, Salesforce, Zendesk and Jira REST API datasources.
The "Read" timeout is only configurable on the URL datasources on the other datasources (Zendesk, Salesforce, Jira REST API) it is hardcoded to 20 seconds.

Request headers

To configure HTTP headers that will be added to all the HTTP requests made on the datasource.

Some headers have a default value set by Elements Connect (you can override them by configuring your own headers):

Content properties

Here you must manually specify what kind of content - response - you are expecting from the remove server.
Elements Connect does not rely on the content-type  header present in the HTTP response.

Supported response formats are:

• JSON
• XML
• CSV

This attribute will have an impact on the field configuration, JSON datasources and not configured the same way as XML datasources.
It is the same value for all fields connected to the same datasource.

If you have the opportunity, we advise you to favour the JSON format which is the most supported by Elements Connect

OAuth2 

Definition

OAuth is a standard for authorisation. In short, it allows you authorise an access to a third party cloud service without having to provide your login and password to your local system.

Elements datasource supports OAuth 2.0, which is also supported by many cloud services such as those provided by Google, Salesforce, Facebook and Microsoft. The only grant type supported is the "Authorization code", more will be supported in the future (like Client credentials for exemple - see CO-3634 - Getting issue details... STATUS ).

Principles

We will not detail the communication flow here, because this is rather technical and it does not help in the context of this documentation.

All you need to know to setup an OAuth2 authentication is :

1. You will need to create an authorisation on your target service.
2. While creating a new URL datasource in Elements Connect, you will have to provide this authorization.
3. There will be potential redirections from Elements Connect administration page to your remote service and back, to finalise the process.
4. Once your datasource is saved, your authorisation is stored and valid (unless you revoke it).

Configuration

Configure OAuth2 parameters

To configure OAuth2, select OAuth2 authentication and click the Configure button. This will open the following dialog: 

All the parameters asked in this dialog are specific to the service that you are trying to connect to.

You need to configure an OAuth2 authorisation on your remote service first before you can fill in these parameters. 

The parameters explained:

Callback URL

You might need to input the callback URL to Elements Connect on your platform. It is relative to the Jira base URL: https://<jira_base_url>/nfeed/admin/models/datasources/oauth/_callback.

Get a credential

The next step is to get a credential from the remote service for Elements Connect.

1. If all parameters are filled in correctly, you can click on 'Get new credential'.
2. Elements Connect will contact the remote service and ask for an authorisation. At this step, there can be a moment when you are redirected to the remote service login or authorisation page. This page will not display if you already granted Elements Connect access and you did not revoke the authorisation.
3. If you grant Elements Connect the access, you are finally redirected back to Elements Connect and you should see the dialog again with your parameters and a success message :

You can now close the dialog.

The datasource Authorisation section should now display 'Authorized' in green.

Clear credential

If for any reason you need Elements Connect to forget a credential, you can click 'Clear credential'.

The parameters in the form will remain unchanged, but any authorisation tokens obtained from your remote service will be lost.
You will need to get new credentials again for the datasource to work properly.

The datasource must be saved for the changes to be taken into account.

Authorisation status

In the datasource, in the authentication you have a status marker displayed. The status can be :

• AUTHORISED: This indicates that Elements Connect has a credential stored.
• NOT AUTHORISED: This indicates that Elements Connect does not have any valid credential.
• NOT CONFIGURED: The OAuth 2 parameters are not provided yet.
• ERROR: This indicates an error while trying to test the status. The error details is in the JIRA log files.

 The information AUTHORISED only denotes that there is a credential stored. We do not test if this credential is still valid against the remote service.
If a field using this datasource displays an access error and the OAuth status indicates AUTHORISED, try to get a new credential.

OAuth2 configuration examples

Troubleshooting

• URL datasource - SSLHandshakeException when configuring URL datasource with HTTPS and SSL

FAQ

• Can I get data from SOAP web service?
• When editing an Elements Connect field, what authorisation will my JIRA user have on the remote platform?