Understanding the IP.21 Connector

How IP.21 Tags Are Discovered During Indexing

The Seeq AspenTech IP.21 Connector makes the following SQLplus queries to discover the tags to be indexed and exposed in Seeq. You can see each of these queries in the net-link.log file for the appropriate agent that is hosting the connector, which can be a useful way to troubleshoot problems.

The following query is issued to discover all of the tables that contain relevant tags:
CODE
```
SELECT PE_DESCRIPTION FROM IP_TagsBranch
```
For each table from (1) above, the following query is issued to discover field maps:
CODE
```
SELECT NAME, 
       NAME->MAP_DefinitionRecord as TTABLE,
       NAME->MAP_TimeStamp AS TTIME,
       NAME->MAP_Status AS TQUALITY,
       NAME->MAP_HistoryValue AS TVALUE,
       NAME->MAP_Units AS UNITS,
       NAME->MAP_Type AS TYPE,
       NAME->MAP_Description AS DESCRIPTION
       FROM ALL_RECORDS WHERE TTABLE = '{tableDef}'
       AND DEFINITION = 'AtMapDef' AND NAME->USABLE = '1';
```
where {tableDef} is a table returned by (1) above. This provides Seeq with the names of the fields in each table that store "well known" data that is necessary for visualization and analytics: TimeStamp, Status, HistoryValue, Units, Type, Description. Seeq considers this a Field Map and will add an entry in the connector JSON configuration file for each map.

You cannot add map entries to the JSON file manually, they will be ignored. Each entry must be generated by the connector as a result of steps (1) and (2) above. You must make appropriate entries in the IP_TagsBranch table and/or add mappings. Please consult AspenTech customer support on how to achieve this.

For each table from (1) above, the following query is issued to discover what columns are present on each table:
CODE
```
SELECT * FROM {tableDef}
```
where {tableDef} is a table returned by (1) above AND this query is limited to only return 1 record (since we don't need the whole table just to determine what columns are present).
Using the columns found in (3) above, and for each table from (1) above, the following query is issued:
CODE
```
SELECT {fieldNames} FROM {tableDef} WHERE {whereClause} ORDER BY LOWER(NAME) ASC
```
where {fieldNames} is the comma-delimited list of columns from (3) above, {tableDef} is a table returned by (1) above, and {whereClause} is used to process the list of tags in chunks, sorted by the (lower-case) tag name.
Each of the rows returned by these queries is a tag that will be searchable/accessible as a signal in Seeq.

Repeated Fields and Custom Definition Records

If your AspenTech IP.21 installation makes use of repeated fields (where a single tag record allows for multiple tag history streams) or custom definition records, you will see an entry for each field map in the AspenTech IP.21 Connection.json file.

Repeated Fields and Custom Definition Records are supported in Seeq Server version R21.0.40.05 or later.

Here is a configuration with "standard" maps:

CODE

{
  "Version": "Seeq.Link.Connector.IP.21.Config.IP.21ConnectorConfigV1",
  "Connections": [
    {
      "Name": "AspenTech IP.21 Server",
      "Id": "673c9bbe-9681-41ca-b373-d26ebb1e559d",
      "Enabled": true,
      "Indexing": {
        "Frequency": "1w",
        "OnStartupAndConfigChange": true,
        "Next": "2019-02-09T18:43:45.898652-08[America/Los_Angeles]"
      },
      "MaxConcurrentRequests": null,
      "MaxResultsPerRequest": null,
      "HostName": "localhost",
      "Port": 10014,
      "Username": null,
      "Password": null,
      "FieldMaps": [
        {
          "Map": "IP_AnalogMap",
          "Table": "IP_AnalogDef",
          "Enabled": true,
          "TagFormat": "${name}",
          "TypeOverride": null
        },
        {
          "Map": "IP_DiscreteMap",
          "Table": "IP_DiscreteDef",
          "Enabled": true,
          "TagFormat": "${name}",
          "TypeOverride": null
        },
        {
          "Map": "IP_TextMap",
          "Table": "IP_TextDef",
          "Enabled": true,
          "TagFormat": "${name}",
          "TypeOverride": null
        },
        {
          "Map": "IP_AnalogDblMap",
          "Table": "IP_AnalogDblDef",
          "Enabled": true,
          "TagFormat": "${name}",
          "TypeOverride": null
        }
      ],
      "Transforms": null
    }
  ]
}

If you make use of repeated fields or custom definition records, you'll see additional map entries and they will probably be disabled.

You can override the tag type using the TypeOverride field and it can be set to “Analog”, “Discrete”, or “Text”. Seeq will convert Analog to number and the other types to strings.

You cannot add map entries to the JSON file manually, they will be ignored. Each entry must be generated by the connector. See How IP.21 Tags Are Discovered During Indexing above.

You can set Enabled to true, but be sure to specify a TagFormat for repeated fields that allow them to be differentiated in Seeq. For example, you could specify a TagFormat like so:

CODE

"TagFormat": "${name}.SIM"