Configure a URL datasource


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




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:

  1. Connect - Establishing the connection to the remote server
  2. 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:

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

NameValue
user-agentElements-Connect/x.y.z  (where x.y.z is your version of Elements Connect)
hostThe host name of the target URL datasource
accepttext/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 
connectionkeep-alive 

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

Troubleshooting


FAQ