Configure a URL datasource
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
URL
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.
Timeout
Retrieving data from a URL datasource is done in two steps:
Connect - Establishing the connection to the remote server
Read - Reading data from the remote server
When a remote server is down or overloaded, it can take time to provide a response.
A long delay can have a negative impact on the Jira load time, whether a user is editing or viewing an Issue.
That's why two timeouts are set on URL datasources:
Connect timeout - A non-configurable 5 seconds timeout applied to the "Connection" step.
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 600 seconds (10 minutes).
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.
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 following grant types for OAuth2:
Authorization code
Client credentials
Resource Owner Password
Mutual TLS: This mode requires both the client and server to authenticate each other through certificates. It provides a very high level of security.
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.
To know more about OAuth2 authentication configuration in Elements Connect, you can read our dedicated OAuth2 page.
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):
Name | Value |
|---|---|
user-agent |
|
host | The host name of the target URL datasource |
accept |
|
connection |
|
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 favor the JSON format, which is the most supported by Elements Connect