Data Source Type and Address

Required: Specify the data source type and the address from which the incoming data will be taken.

There are four data source types:

• File

• REST Server Basic

• REST Server API Key

• REST Client

File

The File option specifies the path and mask from where the input files will be copied. For example:

D:\UFL\Input\Data\*.dat or \\DataShare\Input\Data\*.csv

Note: The path and mask should be specified in the Address field of the Connector Configuration.

Unzip input files

The connector is capable of opening and processing the content of ZIP archives. If you want to process both the not-zipped files as well as the ZIP archives, specify the keyword zip at the end of the path and mask. Use the pipe | as the delimiter. For example: D:\UFL\Input\Data\*.dat | zip.

Note: The mask is applied on files found in the root of the ZIP archive. The content of any subdirectory is ignored.

After processing is complete, the ZIP archive is moved to the output folder.

REST Server Basic

With this selection, the Address field should remain empty as it will be populated automatically with the REST endpoint address at which the connector listens. The endpoint address will display after the data source configuration settings are saved and reopened. The endpoint address pattern is:

• For PUT requests:

  https://ComputerName:port#/ConnectorData/DatasourceName/

• For POST requests:

  https://ComputerName:port#/ConnectorData/DatasourceName/Post

In this mode, the connector expects the data to be pushed to the above address. The data format is arbitrary, and every PUT or POST request executed by a client brings in a textual input onto which the INI logic is applied.

By default, the REST endpoint is configured to use Basic authentication and requires that a user name and password combination be provided in a request. The password cannot be blank; no other rules are enforced.

The PowerShell script example DataPutExample.ps1 located in the %PIHOME64%\Connectors\UFL\PowerShellScripts folder shows how the client side logic should appear.

REST Server API Key

The other option for a secure REST communication is to use the API key method, also known as the Token method name. If selected, the connector verifies that all incoming HTTP requests have the correct key-value pair in their headers. The key must match with what is entered in the User Name input and the value is verified against the Password entry. The Address field will again be auto-populated.

The REST Server channel replies to client requests with response codes. See REST Server mode responses for details.

REST Client

The REST Client channel expects the endpoint address on which the GET command will be executed. For example:

https://restcountries.eu/rest/v1/alpha/LIE

Executing the GET command on the above REST endpoint brings back the structured text (JSON format) about one European country.

Note: The returning data format can be JSON, XML, CSV or a plain text.

REST endpoint parameters

There are three options for extending the REST Client URL address with parameters:

• List of static parameters

  In scenarios where the REST endpoint URL allows for a parameter, the connector logic offers the option to list the individual parameter values and suffix them to the endpoint address. The keyword UFL_Placeholder is used to indicate that the following part of the URL lists the individual parameters divided by the pipe '|'character. With this syntax, more GET commands can run simultaneously. For example, to execute three GETs on the URL:

  https://restcountries.eu/rest/v1/alpha/parametervalue

  You can write the following into the Address edit box:

  https://restcountries.eu/rest/v1/alpha/UFL_Placeholder|LIE|DE|AT

  As a result, the connector logic will execute three GET commands, each using one of the pipe-delimited parameter values.

  With the previously described logic, you can replace any part of the endpoint address denoted by the UFL_Placeholder keyword, not only the parameter part. For example:

  UFL_Placeholder:6894/RESTServiceImpl.svc/json/|10.105.0.1| 10.105.0.2|10.105.0.3

• Dynamic parameters

  If the URL needs to be parameterized by time, you can suffix it by the following pattern: {relative time, output format}

  Relative time format complies with the PI Time format rules, where asterisk * denotes current time. The output format complies with the Date and Time format specifiers described in Custom Date and Time Format Strings. For example:

  http://servername.com/data?start={*-10m,yyyyMMdd_HHmm}&end={*,yyyyMMdd_HHmm}

  The result is the text executed through the http GET command:

  http://servername.com/data?start=20190228_0950&end=20190228_1000

• HTTP headers

  Some HTTP servers require the client to send a set of operating parameters for the HTTP transactions. These parameters are called HTTP headers and the connector allows their definition in the form of a colon-separated name-value pair. You define the parameters manually in %PIHOME64%\Connectors\UFL\Configuration\Datasource.config.json.

  The HttpHeaders keyword is predefined for each data source, and initially it defines an empty string. For example, to specify two HTTP headers, replace the empty string with corresponding name-value pairs in square brackets and separate them by comma:

  "HttpHeaders":

  "[User-Agent:OSISoft UFL Connector/1.2.1.x],

  [Accept:application/vnd.noaa.dwml+json;version=1]"

  Note: You must restart the connector Windows service to activate the HttpHeaders setting.