Exporting Signals to AspenTech IP.21

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 AspenTech IP.21.

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 `sqlplusx` for managing tags
Writes to a historian named ASPENIP21001

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 AspenTech IP21 Connector.json connector file for the IP.21 server used in these examples:

CODE

{
  "Version": "Seeq.Link.Connector.IP21.Config.IP21ConnectorConfigV2",
  "Connections": [
    {
      "Name": "ASPENIP21001",
      "Id": "e7ebb53e-a006-456e-b265-1d24c1d47034",
      "Enabled": true,
      "ExcludeBadSamples": true,
      "Export": {
        "Enabled": true,
        "VerboseLogging": true,
        "MinimumLatency": "1m",
        "DirectiveRefreshFrequency": "1m",
        "ExportBatchSize": 10000
      }
    }
  ],
  "QueryMethod": "sqlplusx",
  "QueryTimeoutInSeconds": 900
}

Configuration Options

QueryMethod

The QueryMethod configuration option specifies the method used for querying data. Export to AspenTech IP.21 is only supported when the queryMethod is set to rest or sqlplusx. Ensure the appropriate method is configured based on your system requirements and environment setup.

ExportBatchSize

The export is performed in batches. Each batch is processed as an INSERT operation, with the maximum number of samples in a batch determined by the ExportBatchSize configuration option.

ExcludeBadSamples

Because AspenTech IP.21 does not support deleting samples, Seeq marks existing samples as Bad when the CLEAN token is used in an export directive. Each time the CLEAN token is applied, samples between the BackfillDate and the current time are marked as Bad, and the new values are re-inserted. This process results in multiple samples at the same timestamp—some marked as Bad and one as Good—which disrupts interpolation for these signals in Seeq.

If such signals need to be trended in Seeq, the ExcludeBadSamples option should be set to true to address this. This ensures that the connector ignores the Bad samples rather than treating them as invalid. When enabled, this option is applied to all signals from the AspenTech IP.21 data source, ensuring the connector ignores the Bad samples instead of treating them as invalid.

Special considerations

Creation of target tags

Automatic creation of target tags from Seeq into the AspenTech IP.21 historian is not currently supported.

Tags that Seeq will write to must be created manually in IP.21 primarily because they require special considerations, such as selecting parameters like IP_REPOSITORY, IP_VALUE_FORMAT, IP_#_OF_TREND_VALUES, IP_ARCHIVING, and configuring the repository Past/Future Time parameter.

The repositories in IP.21 have both Past and Future time parameters to restrict how far into the past or future data can be entered. For the repository where the tag is set to archive, you can adjust these settings by right-clicking on the repository name, selecting Properties, and navigating to the Repository tab. Under the Time section, you’ll find the Past parameter, which defaults to 1 00:00:00 (allowing history to be inserted up to one day in the past).

If you need to backfill data further into the past than this default, you will encounter an error. The repository Past time parameter must be adjusted accordingly when using the BACKFILL TO token.

SignalName must be preceded by the table name

As described in the article Exporting Signals and Conditions to a Historian, an export directive typically follows this syntax:
[EXPORT TO "<ConnectionName>" AS "<SignalName>" ... ]

However, for the AspenTech IP.21 connector, the table definition of the target tag is required to infer column names, as these may depend on the table definition. To accommodate this, the connector uses a slightly modified syntax that includes the table definition:
[EXPORT TO "<ConnectionName>" AS "<table definition>||<tag name>" ... ]

For example, a valid export directive for IP.21 might look like this:
[EXPORT TO "ASPENIP21001" AS "IP_AnalogDef||SEEQ_CREATED" EVERY "10s" BACKFILL TO "2024-11-12T00:00:00Z" VERBOSE]

This ensures the connector can correctly interpret and handle the export operation based on the table’s structure.

Tag approval process

Because the creation of tags is not automated, there is no approval process supported in the current version of the connector. This means that any tag specified in the export directive must already exist in the AspenTech IP.21 historian, and Seeq must have the necessary permissions to write to it.

`INCLUDE UNCERTAIN` token in the export directive

The Export Subsystem does not support writing future data to AspenTech IP.21.

Additionally, because AspenTech IP.21 does not provide a mechanism to delete samples, the INCLUDE UNCERTAIN token cannot be used in export directives targeting IP.21 tags.

`CLEAN` token in export directive

See ExcludeBadSamples section above.

Indexing new tags as Signals

The tags created by the export to AspenTech IP.21 will be automatically picked up during the next indexing cycle performed by Seeq. Generally, there should be minimal to no discrepancy between these signals and the source signals on which the export directives were based. This can be verified by trending the newly indexed signal alongside the source signal in the same lane (and on the same axis if the signals are non-string).

It is important to note that True and False values in IP.21 are represented as double values in Seeq: True is reported as -1, while False is reported as 0.

Workflow Examples

The following examples demonstrate the workflow for exporting signals to a IP.21 historian. 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 IP.21

Create a workbench analysis in Seeq.
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 IP.21.
Add a variable for any signal, like Example > Cooling Tower 1 > Area A > Compressor Power.
Provide a formula, such as $cp * 10 in the example below.
Click Execute. The signal is added to the worksheet.
Click the Item Properties in the Details Pane to the left of the signal that was just created.
Click the Manage link under the Access Control section and give Everyone Read and Write access. Note: Granting Everyone access allows the Agent 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.
In the Description field, add the export directive as follows:[EXPORT TO "ASPENIP21001" AS "IP_AnalogDef||SEEQ_EXPORT_TEST_ML_OUTPUT_1" EVERY "1m"]. Note: The EVERY command is set to 1m to minimize the wait time for this example, but the Exporting Signals and Conditions to a Historian | Additional Export Instructions suggests using the largest latency you can live with.
Wait about one minute for the DirectiveRefreshFrequency to process this change.
Click Item Properties on the source signal again, and you will see a message saying, "InfoPlus.21 record 'SEEQ_EXPORT_TEST_ML_OUTPUT_1' does not exist" in the Export - Message section.
Open sqlplusx and run the following command to create the signal in the historian: INSERT INTO IP_ANALOGDEF (NAME, IP_VALUE_FORMAT, IP_REPOSITORY, IP_#_OF_TREND_VALUES,IP_ARCHIVING) VALUES ('SEEQ_EXPORT_TEST_ML_OUTPUT_1', 'F10.3', 'TSK_DHIS', 100, 1); to create the signal in the historian.
Wait about one more minute for the DirectiveRefreshFrequency to process this change.
Click Item Properties on the source signal again. The error in the Export - Message should disappear, and you should see a new message like:
"Wrote 150 samples, at 97 per second, tardy by 0.3 seconds."