Wiki

Options

New Case Case Status
Log In

Wiki

Options

 
Knowledge Base Articles»KB100021 - Setup for a Web Ser…
  • RSS Feed

Last modified on 12/5/2018 5:09 PM by User.

KB100021 - Setup for a Web Service Client Interface

Introduction

 

This article will cover setting up an EtaPRO Data Interface to acquire data from a Web Service Client API. It assumes that you have the following already done:

  • All necessary software installed and licensed. Which includes:
    • EtaPRO Server
    • EtaPRO Data Interface
      • Ideally installed on the same machine as the Web Service Client
  • Have the computer name and IP Address of all the computers you'll work on
  • Have the URL and credentials necessary to authenticate the Web Service Client
  • Administrator rights to EtaPRO 
  • Administrator rights to the EtaPRO Server computeOther
  • Web Service Client supports several authentication methods

 

Getting Started

The first thing you'll need to do is create a new Data Interface. Open up the EtaPRO Data Interface Service Manager and click the Configurator button.

 

Choose Web Service Client from the Source combo box and leave EtaPRO selected in the Transport combo box.

Switch the Logging Level to High. This will increase the amount if information that is written to the log. If you run into problems setting up an interface, this will help diagnose the issue.

Connection Setup

Web Service Client Server Connection

STEP: Setup the connection to both the Web Service Client Server. Switch to the Data Source tab.

STEP: Set the URL to the API without the endpoint. 

STEP: Set the Authentication Type to what type the API server requires to authenticate the client application (EtaPRO).

 

STEP: Setup the endpoint. From the General -> Service Queries, select the Ellipses (...).

STEP: Add an entry to the Service Query Collection.   NOTE: A minimum of one (1) entry must be entered for web service client to work properly.

STEP: Add a name to the Query entry Name field.

STEP: Add the endpoint to the entry in the Query entry Query field.

 

After all queries are entered, click Test Connect to check that a connection to the server is successful.

 

Example of Setting up a Web Service Client: 

For this example to Yahoo weather (https://query.yahooapis.com/v1/public) their documentation how to setup their web service is located at (https://developer.yahoo.com/weather/)

Using Postman (https://www.getpostman.com), you can view what each of your query parameters are be used in the full url.

Then, determine what parameters are used in individual queries and can be shared among all queries. 

 

Full URL: https://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20weather.forecast%20where%20woeid%20in%20(select%20woeid%20from%20geo.places(1)%20where%20text%3D%22buffalo%2C%20ny%22)&format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys

URL:  https://query.yahooapis.com/v1/public

Service Queries: Setup each of the following service queries

Query 1:

Name: Buffalo

Query: yql?q=select%20*%20from%20weather.forecast%20where%20woeid%20in%20(select%20woeid%20from%20geo.places(1)%20where%20text%3D%22buffalo%2C%20ny%22)

Query 2:

Name: Chicago

Query: yql?q=select%20*%20from%20weather.forecast%20where%20woeid%20in%20(select%20woeid%20from%20geo.places(1)%20where%20text%3D%22chicago%2C%20il%22)

Query 3:

Name: MtWashington

Query: yql?q=select%20*%20from%20weather.forecast%20where%20woeid%20in%20(select%20woeid%20from%20geo.places(1)%20where%20text%3D%22MTWashington%2C%20nh%22)

 

 

Shared Query Parameters:   Use Shared Query Parameters when all queries have the same query parameter in common. In this example all the queries have keys format and env in common.

(1)    Key: format

Value: json

(2)    Key: env

Value: store%3A%2F%2Fdatatables.org%2Falltableswithkeys

 

 

 

 

 

EtaPRO Tag Setup

Open up the EtaPRO Client and identify an acquired point that you not only expect to be available, but to be frequently changing.

To start out with, only setup one point first. 

Enable Edit Mode in the EtaPRO Client and then right-click on the point and select Data Point Configuration.

Click on the Function Setup tab and select Web Service Client Interface from the Instance Type combo box. 

 

The Instance field will link this point with the specific interface you just set up. When the Instance fields are the same, the point is assigned to that interface. The interface will then attempt to look for that point on that Web Service Client.

 

The InstrumentID field will link the JSON Path expression to the specific key and value pair. (Example: $..wind.speed)

The Timestamp (Optional parameter) field will link the JSON Path expression to the specific key and value pair.

The timestamp is expected to be in the YYYY-MM-DDThh:mm:ssTZD format (example: "2018-03-28T12:27:25.8708523-04:00")

where:
     YYYY = four-digit year
     MM   = two-digit month (01=January, etc.)
     DD   = two-digit day of month (01 through 31)
     hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
     mm   = two digits of minute (00 through 59)
     ss   = two digits of second (00 through 59)
     s    = one or more digits representing a decimal fraction of a second
     TZD  = time zone designator (Z or +hh:mm or -hh:mm)

The Quality (Optional parameter) field will link the JSON Path expression to the specific key and value pair. 

The quality is expected to be a numeric value with an OPC Quality. If a quality needs to be converted, the Quality Conversion values will need to be set to match the OPC Quality standards.

 

NOTE: If the return type of the Web Client API is XML, it will be converted to a JSON Object internally. It is preferred to have the API return JSON if available from the server.

NOTE: A website that is useful for evaluating a valid JSON Path expression is http://jsonpath.com and documentation on how to do JSON Path expressions is http://goessner.net/articles/JsonPath/index.html#e2

A sample of how to complete a JSON Path Expression:

JSON (Example 1):

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
{
    "results": [
        {
            "date": "2010-05-03T14:00:00",
            "datatype": "QGAG",
            "station": "COOP:010008",
            "attributes": ",,HT",
            "value": 4.32
        },
        {
            "date": "2010-05-03T14:15:00",
            "datatype": "QGAG",
            "station": "COOP:010008",
            "attributes": ",,HT",
            "value": 4.36
        }
  ]
}

A simple JSON Path Expression for the above JSON object (Example 1) would look like:

JSON Path Expression: $..results[:1].value

$ - Root Element

.. - recursive descent

results - key element

[:1] - 1 record

.value - key element to retrieve result

Result: 4.32

 

A filter JSON Path Expression for the same JSON object (Example 1) above would look like:

JSON Path Expression: $..results[?(@.date == '2010-05-03T14:00:00')].value

$ - Root Element

.. - recursive descent

results - key element

? - Filter

@.date - Find JSON Key element

== '2010-05-03T14:00:00' - equal to element value

.value - key element to retrieve result

Result: 4.32

 

JSON (Example 2):

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
23:
24:
25:
26:
27:
28:
{
   "Colors": [{
      "color": "black",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [255,255,255,1],
        "hex": "#000000"
      }
    },
    {
      "color": "white",
      "category": "value",
      "code": {
        "rgba": [0,0,0,1],
        "hex": "#FFFFFF"
      }
    },
    {
      "color": "red",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [255,0,0,1],
        "hex": "#FF0000"
      }
    }]
}

A complex filter JSON Path Expression for the JSON object above (Example 2) would look like:

JSON Path Expression: $..Colors[?(@.color == 'black' && type == 'primary')].code.rgba[:1] 

Alternative way to write it is: $..Colors[?(@.color == 'black' && type == 'primary')]..rgba[:1]

$ - Root Element

.. - recursive descent

Colors- key element

? - Filter

@.color == 'black' - Find any color with black

&& type == 'primary'- and any type with primary

..rgba - recursive descent to rgba

[alternative] .code.rgba - descend to code then rgba  

[:1] - 1 record

Result: 255

 

The Refresh Rate ID  tells the EtaPRO Data Interface to acquire the data at the rate of whatever has been assigned for the rate with that ID. The EtaPRO Data Interface has a default acquisition rate of once per minute at the top of the minute. (Example: 1)

The Query Name is  the Name of Query (Example: Buffalo)