Skip to main content
Skip table of contents

Exporting Signals and Conditions to OSIsoft PI

Overview

The article Exporting Signals and Conditions to a Historian describes the feature for exporting data to a historian, and this article provides additional details specific to exporting data to OSIsoft PI.

The examples in this article are based on tools, servers, and services that are specific to an environment that is used for documentation purposes:

  • Uses PI System Management Tools for managing PI Points

  • Writes to a historian named DENVERPI0043

  • Runs Seeq with a service account that maps to a PI Identity called PI Engineers

Prerequisites

Ensure that export has been enabled for your connection, as described in this article: Exporting Signals and Conditions to a Historian | Enabling Export . Here are the relevant settings in the OSIsoft PI Connector.json connector file for the PI server used in these examples:

CODE 
    {
      "Name": "DENVERPI0043",
      "Enabled": true,
      "Export": {
        "Enabled": true,
        "AutoCreate": false,
        "AutoUpdate": false,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [],
        "BufferOption": "DoNotBuffer"
      }
    }

Configuration

BufferOption

The OSIsoft PI System’s “AFSDK” is used to write data to PI, and write operations allow for a BufferOption specification, which is controlled via the BufferOption parameter in the Seeq PI connection’s configuration and can be set to DoNotBuffer, BufferIfPossible or Buffer. It is DoNotBuffer by default. If you are using a PI Collective, you will want to set this appropriately to use the buffer subsystem (and likely set the configuration option to BufferIfPossible or Buffer). Note that the buffer subsystem must be configured correctly on the machine running the agent and hosting the Seeq PI Connector. Consult a PI administrator in your organization or contact OSIsoft for more information about buffering.

Invalid Values

Samples with invalid values within Seeq signals will be exported with a status of Bad and values of either 0 or INVALID (for numeric and string signals, respectively). If you wish to write invalid samples as a particular value (with a status of Good), use the replaceNotValid() function in your Seeq Formula as appropriate. Alternatively, you can filter out invalid values completely using the validValues() function.

Uncertain / Future Data

The Export Subsystem also cannot write future data to PI.

To write uncertain data to PI, you can use the INCLUDE UNCERTAIN token in the export directive - see Additional Export Instructions in the Exporting Signals and Conditions to a Historian article for more details.

Point Source

Beginning in R53.3.1, the PI-specific parameters “PointSourceDefault” and “PointSourceMatcher” are available in the export configuration. The PointSourceDefault is null if not provided, and in this case, Seeq will use the string “Seeq” for any PI Points created via the auto-create mechanism. When the PointSourceDefault is provided, this will be the Point Source used for auto-created PI Points or suggested in the export configuration (if auto-create is not enabled or if approval is required).

If you don’t plan to use anything other than the default for the Point Source, you can stop here; however, if you need to allow the Point Source to differ from the default, the PointSourceMatcher should be set to a JSON-escaped regular expression that will match all Point Source values of PI Points for which export directives are configured; this ensures the Point Source check Seeq does before writing data will pass.

Indexing new PI Points as Signals

The PI Points created by the export to PI will naturally be picked up on the next indexing cycle Seeq performs. In general, there should be little to no discrepancy between these Signals and the source Signals upon which the export directives were placed - this can be seen by trending the newly-indexed Signal in the same lane as the source Signal (and with the same axis, if non-string). Note, however, that numeric step Signals in Seeq will end up as PI Points that are indexed as numeric Signals using PILinear interpolation. This causes a visible discrepancy between the two Signals at the value changes. Additionally, any samples with less than 100ns (1 tick) between them in the Seeq signal may be collapsed to a single sample due to the available time resolution in .NET. Both of these phenomena can be seen in the following screenshot, in which SEEQ_EXPORT_TEST_5 is the Signal indexed from the written PI Point:

As noted above, compression on the PI Point can also cause discrepancies.

Workflow Examples

The following examples demonstrate the workflow for exporting signals to a PI server. The examples export signals based on formulas since they are easy to create. There are other ways to create signals for exporting data to a historian.

Manually Create a Signal in PI

  1. Create a workbench analysis in Seeq.

  2. Create a signal with a formula. Note that the formula itself is not important here; we just need something to return data that we can later write to PI.

  3. Add a variable for any signal, like Example > Cooling Tower 1 > Area A > Compressor Power.

  4. Provide a formula, such as $cp * 10 in the example below.

  5. Click Execute. The signal is added to the worksheet.

  6. Click the (info) icon in the Details Pane to the left of the signal that was just created.

  7. Click the Manage link under the Access Control section and give Everyone Read and Write access.

Granting Everyone access allows the Agent API Key to update the signal with metadata for managing the export directive, but this can be avoided: Exporting Signals and Conditions to a Historian | Avoiding “Everyone” Access .

  1. In the Description field, add the export directive as follows:

[EXPORT TO "DENVERPI0043" AS "SEEQ_EXPORT_TEST_ML_OUTPUT_1" EVERY "1m"]

The EVERY command is set to 1m in order to minimize the wait time for the purpose of this example, but the Exporting Signals and Conditions to a Historian | Additional Export Instructions suggests using the largest latency you can live with.

  1. Wait about one minute for the

DirectiveRefreshFrequency to process this change.

10. Open, or reload, the OSIsoft PI Connector.json connector file. The Export section should now look something like this:

CODE 
      "Export": {
        "Enabled": true,
        "AutoCreate": false,
        "AutoUpdate": false,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [
          {
            "Name": "SEEQ_EXPORT_TEST_ML_OUTPUT_1",
            "Approved": false,
            "Properties": {
              "pointsource": "Seeq",
              "instrumenttag": "0393B17B-DFED-4199-9AF4-F4AFA218C7E0",
              "engunits": "kW",
              "pointtype": "Float32",
              "step": 0,
              "exdesc": "Named 'Seeq Export ML Output 1' within http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081"
            }
          }
        ],
        "BufferOption": "DoNotBuffer"
      }

Your instrumenttag, which is the ID of the signal, and the exdesc will be different from the configuration above.

11. Use PI System Management Tools to create the point

12. Wait about two minutes for the DirectiveRefreshFrequency to process the directive and to export the values.

13. Click the (info) icon in the Details Pane to the left of the signal to refresh the Item Properties, and scroll down to the Export properties. Some additional Export- properties are visible:

Manually Update a Signal in PI

Changes to a signal that has an export directive are queued for approval. If the changes are manually applied to the PI Point, then the next directive refresh will remove the item from the queue.

This section triggers an update by changing the formula name of the signal from the previous example.

  1. Click the Edit Formula icon in the Details Pane to the left of the signal

  2. Change the formula name to Seeq Export Test ML Output 1.

  3. Click the Execute button.

  4. Wait about two minutes for the DirectiveRefreshFrequency to process the change.

  5. Open, or reload, the OSIsoft PI Connector.json connector file. The Export section should now look something like this:

    CODE 
          "Export": {
        "Enabled": true,
        "AutoCreate": false,
        "AutoUpdate": false,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [
          {
            "Name": "SEEQ_EXPORT_TEST_ML_OUTPUT_1",
            "Approved": false,
            "Properties": {
              "exdesc": "Named 'Seeq Export Test ML Output 1' within http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081"
            }
          }
        ],
        "BufferOption": "DoNotBuffer"
      }
    }

    Note that the exdesc reflects the name change.

6. PI System Management Tools to modify the point

  1. Wait about two minutes for the

DirectiveRefreshFrequency to process the directive.

  1. Open, or reload, the

OSIsoft PI Connector.json connector file. The list of NewOrChanged entries should be empty. The Export section should now look something like this:

CODE 
      "Export": {
        "Enabled": true,
        "AutoCreate": false,
        "AutoUpdate": false,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [],
        "BufferOption": "DoNotBuffer"
      }

Automatically Create Approved Signals in PI

The export feature can be configured to automatically create signals once they are approved. This section creates another signal with a formula, and then demonstrates the approval process.

The PI Identity of the Seeq service must have Write permissions to the PIPOINT table in order to create PI Points.

1. Use PI System Management Tools to give write permissions to the Seeq service account

  1. Create another signal with a formula. Again, the formula itself is not important here, we just need something to return data that we can later write to PI.

  2. Add a variable for any signal, like

Example > Cooling Tower 1 > Area A > Compressor Power.

  1. Provide a formula, such as

$cp * 10 in the example below.

  1. Click Execute. The signal is added to the worksheet.

  2. Click the

(info) icon in the Details Pane to the left of the signal that was just created.

  1. Click the

Manage link under the Access Control section and give Everyone Read and Write access.

  1. In the

Description field, add the export directive as follows:

[EXPORT TO "DENVERPI0043" AS "SEEQ_EXPORT_TEST_ML_OUTPUT_2" EVERY "1m"]

  1. Wait about one minute for the

DirectiveRefreshFrequency to process this change.

  1. Open, or reload, the OSIsoft PI Connector.json connector file. The Export section should now look something like this:

CODE 
  "Export": {
    "Enabled": true,
    "AutoCreate": false,
    "AutoUpdate": false,
    "RequireApproval": true,
    "DirectiveRefreshFrequency": "1m",
    "NewOrChanged": [
      {
        "Name": "SEEQ_EXPORT_TEST_ML_OUTPUT_2",
        "Approved": false,
        "Properties": {
          "pointsource": "Seeq",
          "instrumenttag": "02A13D89-FD2D-40A5-B6FB-C2C9B6E464AE",
          "engunits": "kW",
          "pointtype": "Float32",
          "step": 0,
          "exdesc": "Named 'Seeq Export ML Output 2' within <http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081">
        }
      }
    ],
    "BufferOption": "DoNotBuffer"
  }
}

  1. Click the (info) icon in the Details Pane to the left of the signal that was just created. Note the Export - Status is Failed because an Administrator must approve the creation of the point.

  1. Edit OSIsoft PI Connector.json connector file. Change AutoCreate to true, change Approved to true, and then save the file. The Export section should now look something like this:

CODE 
      "Export": {
        "Enabled": true,
        "AutoCreate": true,
        "AutoUpdate": false,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [
          {
            "Name": "SEEQ_EXPORT_TEST_ML_OUTPUT_2",
            "Approved": true,
            "Properties": {
              "pointsource": "Seeq",
              "instrumenttag": "02A13D89-FD2D-40A5-B6FB-C2C9B6E464AE",
              "engunits": "kW",
              "pointtype": "Float32",
              "step": 0,
              "exdesc": "Named 'Seeq Export ML Output 2' within http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081"
            }
          }
        ],
        "BufferOption": "DoNotBuffer"
      }
    }

  1. Wait about one minute for the DirectiveRefreshFrequency to process this change.

  2. Open, or reload, the OSIsoft PI Connector.json connector file. The Export section should now look something like this:

CODE 
      "Export": {
        "Enabled": true,
        "AutoCreate": true,
        "AutoUpdate": false,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [],
        "BufferOption": "DoNotBuffer"
      }

  1. Click the (info) icon in the Details Pane to the left of the signal that was just created. Note the Export - Status is Success.

Automatically Update Approved Signals in PI

The export feature can be configured to automatically update signals once they are approved. This section updates a signal, and then demonstrates the approval process.

The PI Identity of the Seeq service must have Write permissions to the PIPOINT table in order to update PI Points.

  1. Use PI System Management Tools to give write permissions to the Seeq service account

  1. Click the Edit Formula icon in the Details Pane to the left of the signal that was created in the previous step.

  2. Change the formula name to

Seeq Export Test ML Output 2.

  1. Click the Execute button.

  2. Wait about two minutes for the

DirectiveRefreshFrequency to process the change.

  1. Open, or reload, the

OSIsoft PI Connector.json connector file. The Export section should now look something like this (Note that the exdesc reflects the name change.):

CODE 
      "Export": {
        "Enabled": true,
        "AutoCreate": true,
        "AutoUpdate": false,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [
          {
            "Name": "SEEQ_EXPORT_TEST_ML_OUTPUT_2",
            "Approved": false,
            "Properties": {
              "exdesc": "Named 'Seeq Export Test ML Output 2' within http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081"
            }
          }
        ],
        "BufferOption": "DoNotBuffer"
      }
    }

  1. Edit the OSIsoft PI Connector.json connector file. Change AutoUpdate to true, change Approved to true, and then save the file. The Export section should now look something like this:

CODE 
       "Export": {
        "Enabled": true,
        "AutoCreate": true,
        "AutoUpdate": true,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [
          {
            "Name": "SEEQ_EXPORT_TEST_ML_OUTPUT_2",
            "Approved": true,
            "Properties": {
              "exdesc": "Named 'Seeq Export Test ML Output 2' within http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081"
            }
          }
        ],
        "BufferOption": "DoNotBuffer"
      }
    }

  1. Wait about one minute for the DirectiveRefreshFrequency to process this change.

  2. Open, or reload, the OSIsoft PI Connector.json connector file. The Export section should now look something like this:

CODE 
      "Export": {
        "Enabled": true,
        "AutoCreate": true,
        "AutoUpdate": true,
        "RequireApproval": true,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [],
        "BufferOption": "DoNotBuffer"
      }
    }

Automatically Create or Update Any Signal in PI

The export feature can be configured to automatically create or update signals once they are approved. This section demonstrates the auto-create workflow.

The PI Identity of the Seeq service must have Write permissions to the PIPOINT table in order to create and update PI Points.

  1. Use PI System Management Tools to give write permissions to the Seeq service account

  1. Edit the OSIsoft PI Connector.json connector file. Change AutoCreate to true, AutoUpdate to true, change RequireApproval to false, and then save the file. The Export section should now look something like this:

CODE 
      "Export": {
        "Enabled": true,
        "AutoCreate": true,
        "AutoUpdate": true,
        "RequireApproval": false,
        "DirectiveRefreshFrequency": "1m",
        "NewOrChanged": [],
        "BufferOption": "DoNotBuffer"
      }
    }

Troubleshooting

You can view export related entries in the net-link logs, or the _NET_Agent logs, by searching where the Message Contains ExportOrchestrator:

The directive is ignored

You have added the directive to a signal, and ensured that the Agent API Key (or Everyone) has Write access, and you have waited for a long time, but directive has not been processed.

Suggestions

  • Verify that the export feature has been enabled. Edit the OSIsoft PI Connector.json connector file, change Enabled to true, and then save the file. Note the value for DirectiveRefreshFrequency and wait that long, and then reload the OSIsoft PI Connector.json connector file.

  • The value for DirectiveRefreshFrequency in the OSIsoft PI Connector.json connector file determines when directives are processed, not the EVERY “<latency>” export instruction.

  • Verify the directive’s syntax is correct – there are no typing mistakes and the instructions are upper case: [EXPORT TO "<ConnectionName>" AS "<SignalName>" EVERY "<Latency>" BACKFILL TO "<BackfillDate>" INCLUDE UNCERTAIN CLEAN VERBOSE]

  • Ensure the API Agent Key, or Everyone, has Write access to the Seeq Signal. If not, then you might see a similar entry in the net-link logs

    CODE 
    ERROR 2021-08-12T22:25:15.586+00:00 [15] Seeq.Link.SDK.Export.ExportOrchestrator - ERROR: Could not write export status to item 441E7EBF-FA6F-4B70-8F8B-3B45EF2B01FA
Seeq.Sdk.Client.ApiException: Error calling SetProperties: {"statusMessage":"Identity \u0027agent_api_key\u0027 d8ad2bc8-cc00-462a-b0d2-510c5dc02269 does not have WRITE access for the CalculatedSignal 441e7ebf-fa6f-4b70-8f8b-3b45ef2b01fa"}
   at Seeq.Sdk.Api.ItemsApi.SetPropertiesWithHttpInfo(String id, List`1 body)
   at Seeq.Sdk.Api.ItemsApi.SetProperties(String id, List`1 body)
   at Seeq.Link.SDK.Export.ExportOrchestrator.doJob(ExportJob job, ExportStatus status, TimeInstant startTime, TimeInstant endTime) in C:\BuildAgent\work\757a28bcf1240baf\net-link\sdk\Seeq.Link.SDK\Export\ExportOrchestrator.cs:line 313

     

  • The directive is waiting for approval. For example, a signal has been successfully exporting data and then the signal name is changed; the next directive refresh detects he change and adds it to the OSIsoft PI Connector.json connector file for approval. See Manual Create, Manual Update, Auto Create, or Auto Update.

Unrecognized export directive

The Export - Message properties says “Unrecognized export directive fragment…”

Suggestions

  • Export directives are case sensitive. The following example uses as instead of AS:

  • Verify the directive’s syntax is correct – there are no typing mistakes and the instructions are upper case: [EXPORT TO "<ConnectionName>" AS "<SignalName>" EVERY "<Latency>" BACKFILL TO "<BackfillDate>" INCLUDE UNCERTAIN CLEAN VERBOSE]

Agent API Key does not have write permission to the Signal

The Agent API Key must have Write access to the the signal in order to update the Export properties on the signal.

Suggestions

  • Ensure the API Agent Key, or Everyone, has Write access to the Seeq Signal. If not, then you might see a similar entry in the net-link logs

    CODE 
    ERROR 2021-08-12T22:25:15.586+00:00 [15] Seeq.Link.SDK.Export.ExportOrchestrator - ERROR: Could not write export status to item 441E7EBF-FA6F-4B70-8F8B-3B45EF2B01FA
Seeq.Sdk.Client.ApiException: Error calling SetProperties: {"statusMessage":"Identity \u0027agent_api_key\u0027 d8ad2bc8-cc00-462a-b0d2-510c5dc02269 does not have WRITE access for the CalculatedSignal 441e7ebf-fa6f-4b70-8f8b-3b45ef2b01fa"}
   at Seeq.Sdk.Api.ItemsApi.SetPropertiesWithHttpInfo(String id, List`1 body)
   at Seeq.Sdk.Api.ItemsApi.SetProperties(String id, List`1 body)
   at Seeq.Link.SDK.Export.ExportOrchestrator.doJob(ExportJob job, ExportStatus status, TimeInstant startTime, TimeInstant endTime) in C:\BuildAgent\work\757a28bcf1240baf\net-link\sdk\Seeq.Link.SDK\Export\ExportOrchestrator.cs:line 313

     

See Exporting Signals and Conditions to a Historian | Avoiding “Everyone” Access

“Not exported: Administrator must approve…”

You added a directive to a signal and waited for the directive to be processed, and now the Export - Message says “Not exported: Administrator must approve…”

Suggestions

An error like the following means the point must be created manually, or it must be approved.

“Not exported: PI tag's "Instrument Tag" attribute is not…”

You moved the directive to another signal, and now the Export - Message shows something like Not exported: PI tag's "Instrument Tag" attribute is not "EBE6DA93-77A7-495B-96EF-6CBE68205688". Check tag name and/or change "Instrument Tag" in PI System Management Tools if necessary.

Suggestions

The error message means that the PI Point is already bound to another signal.

  • To resolve this issue, the OSIsoft PI Connector.json connector file contains an update that is pending approval. See Manual Update or Auto Update.

“Not exported: PI tag's "Point Source" attribute is not "…". Check tag…”

The directive seems correct and the PI Point exists, but the Export - Message shows a message like Not exported: PI tag's "Point Source" attribute is not "Seeq". Check tag name and/or change "Point Source" in PI System Management Tools if necessary.

Suggestions

Seeq only writes to PI Points where the Point Source is as specified by the export configuration. The default Point Source is Seeq, but this may be changed by setting the PointSourceDefault. Additionally, the PointSourceMatcher can be used to allow the Point Source to vary as long as it can be matched by the PointSourceMatcher’s value, which should be a JSON-escaped regular expression.

  • To resolve this issue, use PISMT to ensure that the Point Source is set appropriately on the PI Point and/or configure the PointSourceDefault and PointSourceMatcher. See Manual Update or Auto Update.

“Could not create PI Signal…”

You reviewed and approved an item in the OSIsoft PI Connector.json connector file, and now the Signal shows an error message that is similar to Could not create PI Signal 'SEEQ_EXPORT_TEST_ML_OUTPUT_4': [-10401] No Write Access - Secure Object

Suggestions

The Seeq service account does not have permissions to update the PIPOINT table.

  • Ensure that the PI Identity of the Seeq service account has Write permissions to the PIPOINT database table under Security > Database Security in the PI System Management Tools.

“Error(s) while writing values for …”

The Export - Message for a signal shows a message similar to Error(s) while writing values for 'SEEQ_EXPORT_TEST_ML_OUTPUT_4': [-10401] No Write Access - Secure Object.

Suggestions

The Seeq service account does not have Write permissions on the PI Point.

  • Ensure that the PI Identity of the Seeq service account has Write permissions to the PIPOINT in PI System Management Tools. For example,

 

Frequently Asked Questions

Can two signals write to the same PI Point?

No.

Explanation

In this scenario, the Export - Message on both signals would be similar to ERROR: Multiple items trying to write to the same signal. Check net-link logs for "Duplicate/conflicting export directives for SEEQ_EXPORT_TEST_ML_OUTPUT_4:" for more information.

The net-link logs identifies each item attempting to write to the same PI Point:

CODE 
ERROR 2021-08-26T00:39:47.963+00:00 [Export Orchestrator for 'DENVERPI0043'] Seeq.Link.SDK.Export.ExportOrchestrator - Duplicate/conflicting export directives for SEEQ_EXPORT_TEST_ML_OUTPUT_4:
Named 'Seeq Export Test ML Output 4' within http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081
Named 'Seeq Export Test ML Output 4 - Copy' within http://ec2-3-85-239-140.compute-1.amazonaws.com:34216//workbook/FF059173-7C46-4BEE-B6CF-66A56482D081

  • Resolve this error by changing the directive for one or more of the signals listed in the net-link log, or by removing the directive from one or more of the signals listed in the net-link log.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close