Sign in

Data Source - Web Service

The Web service connector has the capability to connect and retrieve data from a web service request.

To create a connection to a Web Service endpoint, right-click on the Data Sources group, then click “Cloud”, and select “Web service”.

DataSources-ConnectWebservice.png

To successfully retrieve data from a Web Service, the following properties need to be set.

DataSources-WebServiceProperties.png

  • Name (String)
 Name to identify the data source.
  • Host (String / Url)
 Address of the web service endpoint.
  • Authentication Type (Dropdown)
 Selection for the type of authentication to use to connect to the Web service. Default is "None".
  • Username (String)
 Username to use to connect to the endpoint.
  • Password (String)
 Password to use to connect to the endpoint.
  • Endpoint Key (String)
 Security Key to connect to the endpoint.
  • Headers (String)
 Supply any headers if required to the endpoint request.
  • Cache (Dropdown)
 Select to cache the connection details. Default is "True".
  • Maximum Connections (Int)
 Maximum concurrent count for connections. Default is "20".
   

Namespace

To create a measure from data points that are returned from a web-service call, a custom namespace must be created. Flow does not create a namespace automatically as it first needs to understand the dataset that would be retrieved from the web service endpoint.

As an example, to create a namespace, data will be retrieved from a weather service web service endpoint. The endpoint address that needs to be configured is:

Host: https://api.darksky.net

To get a key to connect to the API, register an account for a free key at https://darksky.net/dev/. Paste your key into “Endpoint Key”. 

In the blank namespace, create a custom namespace by adding a folder and custom tag. In this case we will be creating a tag for temperature in Charlotte.

DataSources-WebserviceNamespace.png

Right-click custom “Charlotte Temperature” tag and click ”Edit”.

DataSources-WebserviceEditNamespace.png

The endpoint for the particular temperature tag at Charlotte is:

Endpoint: forecast/[Key]/35.225049, -80.839375,[PeriodEnd]

The components of the endpoint are discussed below:

  1. These are Charlotte’s coordinates
  2. The default endpoint provides Fahrenheit. If you want Celcius, add “?units=si” to the end of the Endpoint.
  3. [Key] will be replaced by the “Endpoint Key” configured at the Data Source level.
  4. [PeriodEnd] will be replaced by the Date and Time of local Flow System time. Use [PeriodEndUTC] for UTC.
  5. To replace specify the timestamp you want to make use of with a custom formatting option, the format can be specified by adding the string format option in brackets after the datetime placeholder i.e. [PeriodEnd("yyyy-DD-mm")]
  6. Date time options available include:
    1. PeriodEnd - Formatting can be applied.
    2. PeriodStart - Formatting can be applied.
    3. PeriodEndUTC - Formatting can be applied.
    4. PeriodStartUTC - Formatting can be applied.
    5. PeriodEndUNIX
    6. PeriodStartUNIX
Note: Please consult the API documentation for the specific endpoint you are configuring to set the specific endpoint address.

Other setting to configure include:

  • Data path
 This is the JsonPath in the JSON returned where Flow will search for the result set.
  • Value Path
 This is the JsonPath within the Data path where Flow will find the value (or values if Data path is an array).
  • Quality Path
 This is the JsonPath within the Data path where Flow will find the quality (or values if Data path is an array).
  • Timestamp Path
 This is the JsonPath within the Data path where Flow will find the timestamps (this will only be used if the Aggregation property is not “None”).
  • Scaling
 Scaling to be applied to the retrieved value.

 

Example:

For a Json response like this:

{
  "d": [
  {
    "t": "2024-08-01T00:07:57.265617Z",
    "v": 33.40165084319127,
    "q": 192
  },
  {
    "t": "2024-08-01T00:07:58.269826Z",
    "v": 26.45115386779352,
    "q": 192
  }
  ]
}

The following configuration would point to the correct paths:

See JsonPath syntax here: JSONPath Online Evaluator