Table of contents
URL Datasource allows you to connect to any data available on the remote web servers, accessible via URL. This datasource gives you access to various remote REST APIs. HTTP and HTTPS protocols are supported and the only allowed method is GET.
This field must contain the root URL to your service (Example: ).
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.
Elements Connect supports two authentication methods:
- Basic HTTP: Standard method that allows to provide a login and password to the server. This is recommended to use with HTTPS
- OAuth2 : a more secured authentication method used by many remote systems
Please note that you could use request headers to add a custom fields that may be needed to authenticate.
Here you can add any number of custom fields to your http request.
Here you must manually specify what kind of content (response) your service is expected to return. Elements Connect does not rely on the Content-Type header present in the HTTP response.
Supported response formats are:
See how to configure fields for the supported response formats: Field query configuration
What is OAuth 2?
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.
URL datasource supports OAuth 2.0, which is also supported by many cloud services such as those provided by Google, Salesforce, Facebook and Microsoft.
How it works
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 :
- You will need to create an authorisation on your target service. We will help you as far as we can for that.
- While creating a new URL datasource in Elements Connect, you will have to provide this authorisation.
- There will be potential redirections from Elements Connect administration page to your remote service and back, to finalise the process.
- Once your datasource is saved, your authorisation is stored and valid (unless you revoke it).
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:
- Client ID: This is a unique client identifier that you obtain when you create the authorisation on your remote service
- Client Secret: Secret code provided at the same time as the client identifier above.
- Authorise URL: This is a URL pointing to your remote service, specific to OAuth 2 authorisation flow.
- Token URL: This is a URL pointing to your remote service, specific to OAuth 2 authorisation flow.
- Scopes: The authorisation scopes depend on your remote service. Some services do not require it, whereas other services have a strict list of scopes. These scopes can be defined when you first create the OAuth2 authorisation on your remote service or can be validated when Elements Connect requires a credential (see next step).
Authorise and token URL are OAuth 2 endpoints provided by the remote service. You should be able to find them in the service technical documentation.
You might need to input the callback URL to Elements Connect on your platform.
In short, if your dashboard URL isthen the value here will be:
Get a credential
The next step is to get a credential from you remote service for Elements Connect. If all parameters are filled in correctly, you can click on 'Get new credential'.
Elements Connect will try and 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.
Elements Connect does not store you login and password. We do not have access to this information and we do not need it. This is one of the interest in using OAuth.
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 'AUTHORISED' in green.
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.
You will need to save your datasource for the changes to be taken into account.
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.
- NOTCONFIGURED: 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. We will improve this in a future version. 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
For security reason, client secret and password values will not appear in the edit configuration screen.
If you want to change the client secret or the password you can click on Change client secret or Change password. A field will appear to let you enter a new one.
If you do not click on "Change password" link while editing, Test connection action will use the password stored in database.
If you click on "Change password" and let field empty, Test connection action will use an empty password.
- Can I get data from SOAP webservice?
- When editing a Elements Connect field, what authorisation will my JIRA user have on the remote platform?