From the Edit Historian Connection window you can select REST Client. In this implementation of the External Historian the DataHub instance acts as a REST client, transmitting data to a REST server. The DataHub instance makes HTTP calls containing data point values as a payload. The server responds with a success or fail indication.

Connection Settings

Document Settings

The attributes of the JSON, XML, or other document used to establish the REST connection.

The following three entries (Relative path, HTML headers and Document definition) define their values using a script that is processed through an ASP processor. This allows you to specify these settings in a way that varies with the data or other information that changes at runtime. See below for the syntax and examples of document definitions.

Once you have completed the REST Client-specific configuration, you can return to Picking Points in General Configuration to continue.

ASP Document Definition

ASP values are defined in the following dialog:

The left-hand pane   contains the ASP document that defines the value. Type your document here.

The center pane   contains saved examples and templates that you can load by double-clicking on the template name. Once you have created a document definition you can save it by selecting File -> Save As to give your template a name. It will then appear in the My Templates list.

The right-hand pane   contains the result of processing some example point change events using the document definition in the left-hand pane. The two check-boxes, Valid JSON and Valid XML, will be checked automatically if the resulting document in the Example pane is valid JSON or valid XML. This is to help you identify errors in the document definition when the result should be JSON or XML.

An ASP document is any text document that combines normal text with special ASP directives. The content of an ASP directive is a script, written in S-Sharp. Script expressions and script statements are any valid S-Sharp expressions and statements respectively. S-Sharp is documented here. There are two ASP directives, differing only by an equals sign ( = ). These are:

JSON Example

This is an example of a JSON document that is valid for transmitting data to Microsoft Power BI:

[
<%
  var point; var i;
  for (i = 0; i < points.Length; i++)
  {
    point = points[i];
%><%= i == 0 ? "" : ",\n" %>  {
    "<%= point.Name %>": <%= point.JsonValue %>,
    "Date": "<%= point.IsoTimestamp %>"
  }<% } %>
]

	There is an XML example below.

Breaking down the PowerBI example makes it easier to understand. The outermost square brackets [ ] are literal brackets that surround a JSON array. Within the array we want to iterate through the list of points that need to be transmitted. The array of points is provided automatically in the variable points. The loop through the array of points contains both literal text and scripts within ASP directives. Colorizing the code helps to understand it:

The text within <% %> directives is script code that produces no output. This represents the script structure, not the document content. Extracting that script code we see the structure as:

The document content is a combination of literal text and the result of evaluating code within <% %> directives. Extracting this gives us the structure of the document content:

The directive inserts a comma and a newline character into the resulting document for all items in the points list except the first one.

The directive inserts the point name within double quotes into the resulting document. Note that we must explicitly add the double quote characters. This will fail for point names that contain double quote or backslash characters. If you need to escape point names with backslash and double quote characters, use:

The directive inserts the point value in JSON format into the output. If the point value is a string this includes surrounding the string in double quote characters and escaping quote and backslash characters.

The directive inserts the point timestamp in ISO 8601 format.

Data points contain several members that can be inserted into the document:

XML Example

This is an example of an XML document that sends a global timestamp and then a series of data points including name, value, quality and timestamp:

<DataPoints>
  <Timestamp><%= DateTime.UtcNow.ToString("o") %></Timestamp>
  <Points>
  <%
    var point; var i;
    for (i = 0; i < points.Length; i++)
    {
      point = points[i];
  %>  <Point>
      <Name><%= point.Name %></Name>
      <Value><%= point.Value %></Value>
      <Quality><%= (int)point.Quality %></Quality>
      <Timestamp><%= point.IsoTimestamp %></Timestamp>
    </Point>
  <% } %>
  </Points>
</DataPoints>