Configure a URL datasource


Table of contents


Definition

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.


Datasource configuration





URL field

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 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.

Request headers

Here you can add any number of custom fields to your http request.

Content properties

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:

  • JSON
  • XML
  • CSV


Field configuration

See how to configure fields for the supported response formats: Field query configuration


OAuth2 

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).

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:

  • 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).

(info) 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.


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.

(info) 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.

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.

You will need to save your datasource 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.
  • 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.

(info) 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.

Troubleshooting


FAQ