Understanding the OSIsoft AF Event Frames Connector

A Simple Example

In a simple case, an entry in the EventFrameQueries list results in exactly one condition - no partitioning of the results of searches against the AF Event Frames database is done, and any child Event Frames of Event Frames found by the search are not considered and will not result in conditions being created in Seeq. For this configuration type, the parameter CreateConditionsForDescendants should be false, and the Partitions parameter should be null (the word by itself, with no quotes) or an empty list (a pair of square brackets with nothing except possibly whitespace between them: [ ]). A sample simple configuration might look like this:

Simple Query Definition

CODE

"EventFramesQueries": [
            {
              "ConfigName": "(use this field to explain the configuration; it will appear here and also in some log messages)",
              "ConditionNameTemplate": "Cold Starts",
              "ConditionDescriptionTemplate": "This Condition collects capsules associated to Event Frames with names starting with Cold Start",
              "ConditionMaxDuration": "3 hours",
              "SearchFullHierarchy": false,
              "SearchMode": "Overlapped",
              "SearchRootId": null,
              "EventFrameNameFilter": "Cold Start*",
              "EventFrameCategoryFilter": null,
              "ElementNameFilter": null,
              "PrimaryReferencedElementCategoryFilter": null,
              "EventFrameTemplateFilter": null,
              "AttributeFilters": null,
              "ExtendedPropertyFilters": null,
              "Partitions": null,
              "CreateConditionsForDescendants": false,
              "PropagatedProperties": null,
              "HierarchicalConditions": false,
              "TrainingIntervalStart": "2018-11-05T20:21:14.9337781Z",
              "TrainingIntervalEnd": "2018-11-16T02:31:02.5376307Z",
              "ResetTrainingWindow": true,
              "ExtendTrainingWindowEachSync": true,
              "UseSimplePropertyNames": true,
              "AttributePropertyPaths": null
            }
          ]

This configuration will create a single condition named "Cold Starts" in Seeq. Prior to R57, since no partitioning or syncing of child Event Frame conditions is indicated, no training would be necessary. However, beginning with R57, it is necessary to train even simple conditions to ensure all capsule properties are identified during indexing and before any capsule requests. A simple query always results in creation or update of a single condition. The condition is available for use in Seeq after training completes, and queries made from Seeq (by changing the time range in the Trend Viewer in Workbench or making a call through the REST API) will cause a search of the AF Event Frames database to occur, the results of which will be translated into capsules in Seeq with capsule properties defined by the attributes and other characteristics of the Event Frame. For the configuration shown above, the query will find only Event Frames that match a name filter of Cold Start* in PI System Explorer. It is possible to add further filtering based on the Event Frame Template, Categories, Referenced Elements, and so on, as described in the Configuration section above. In some cases, the filters cannot be applied to the Event Frame search directly and are therefore applied only after the results of queries are returned to Seeq. Thus, it is better to use the search filters available in the PI System Explorer Event Frame search dialog where possible so that requests for data from the connector are efficient.

Partitioned Conditions

Partitioning makes it possible to create many related conditions with a single configuration block in the EventFrameQueries list. This makes for a compact, readable config file, and it reduces the repetitive work necessary for the configurer; a short config file also means fewer places for transcription errors that might occur in replicating a single working query to multiple queries. When using partitioning, the conditions created in Seeq are defined by the Event Frames found in AF, so it is important to consider Event Frames that cover all of the variations we expect to see. This is done by "training" the connector during indexing. The configurer must choose a time range for this training, which is defined by the TrainingIntervalStart and TrainingIntervalEnd parameters. Since at some point new Event Frames might be created in AF that don't match any of the existing partitions, the ExtendTrainingWindowEachSync parameter enables the extension of the training window each sync by querying over the time since the last TrainingIntervalEnd until now and creating any new conditions as needed. Here is an example of a query configuration that uses partitioning:

Partitioned Query Definition

CODE

"EventFramesQueries": [
            {
              "ConfigName": "Test Partitions",
              "ConditionNameTemplate": "Condition_${PartitionByPhase}",
              "ConditionDescriptionTemplate": "This is Condition_${PartitionByPhase}",
              "ConditionMaxDuration": "1h",
              "SearchFullHierarchy": false,
              "SearchMode": "Overlapped",
              "SearchRootId": null,
              "EventFrameNameFilter": "Phase? Event",
              "EventFrameCategoryFilter": null,
              "ElementNameFilter": null,
              "PrimaryReferencedElementCategoryFilter": null,
              "EventFrameTemplateFilter": "BA Phase",
              "AttributeFilters": null,
              "ExtendedPropertyFilters": null,
              "Partitions": [
                {
                  "PartitionName": "PartitionByPhase",
                  "PartitionScope": "Name",
                  "PartitionExpression": "(.*) Event",
                  "PartitionSearchFilter": "${PartitionByPhase} Event"
                }
              ],
              "CreateConditionsForDescendants": true,
              "PropagatedProperties": [
                "BatchID"
              ],
              "HierarchicalConditions": false,
              "TrainingIntervalStart": "2018-11-05T20:21:14.9337781Z",
              "TrainingIntervalEnd": "2018-11-16T02:31:02.5376307Z",
              "ResetTrainingWindow": true,
              "ExtendTrainingWindowEachSync": true,
              "UseSimplePropertyNames": false,
              "AttributePropertyPaths": [
                ".\\|BatchID"
              ]
            }
          ]

In this configuration, it is assumed that there are Event Frames named Phase1 Event, Phase2 Event, etc. where the Phase number is single digit. This allows the EventFrameNameFilter of "Phase? Event" to be narrowly focused, only finding Event Frames that do indeed belong in the condition. Due to the partition with PartitionName "PartitionByPhase", the Event Frames' names will be matched by the regex in the PartitionExpression, and the captured strings, which will be Phase1, Phase2, etc., will be substituted into the ConditionNameTemplate. The resulting conditions will be named Condition_Phase1, Condition_Phase2, etc., and queries in Seeq against these conditions will return only capsules associated to Event Frames that match. The results of the query defined by the configuration above are shown in the left screenshot at the top of this article; a sampling of the Event Frames that become the capsules are shown in the right screenshot in PI System Explorer.

Child Conditions

This configuration is most likely going to be used in association with Event Frames that adhere to ISA88 structure rules in whole or in part. In any case, the Event Frames that satisfy the search filters are expected to have one or more levels of descendant Event Frames, and by setting CreateConditionsForDescendants to true, these will be mapped into child conditions in Seeq. It is important to note that there is no explicit relationship between the capsules of a condition defined for a parent Event Frame and those of a condition defined for the associated child Event Frame. In practice, however, the time ranges of the capsules will generally reflect this relationship effectively. In case of ambiguity, a PropagatedProperty can usually be defined to pass an identifier into the child condition's capsules on the basis of the associated Event Frame's ancestors in AF.

Child Conditions

CODE

          "EventFramesQueries": [
            {
              "ConfigName": "S88 Batches",
              "ConditionNameTemplate": "North Plant Batches",
              "ConditionDescriptionTemplate": "This Condition is related to batches created in our north plant.",
              "ConditionMaxDuration": "7d",
              "SearchFullHierarchy": false,
              "SearchMode": "Overlapped",
              "SearchRootId": null,
              "EventFrameNameFilter": "*-EN-*",
              "EventFrameCategoryFilter": null,
              "ElementNameFilter": null,
              "PrimaryReferencedElementCategoryFilter": null,
              "EventFrameTemplateFilter": "Procedure",
              "AttributeFilters": null,
              "ExtendedPropertyFilters": null,
              "Partitions": null,
              "CreateConditionsForDescendants": true,
              "PropagatedProperties": [
                "BatchID"
              ],
              "HierarchicalConditions": true,
              "TrainingIntervalStart": "2014-11-05T20:21:14.9337781Z",
              "TrainingIntervalEnd": "2018-11-16T06:31:20.5345501Z",
              "ResetTrainingWindow": false,
              "ExtendTrainingWindowEachSync": true,
              "UseSimplePropertyNames": false,
              "AttributePropertyPaths": [
                ".\\|BatchID"
              ]
            }
          ]

In this case, it is assumed that the AF Event Frame database has some top-level Event Frames that contain the string -EN- and were created using a template named "Procedure". They are required to be at the top level of the Event Frames database because the SearchFullHierarchy parameter is set to false - this keeps the search in AF narrow, which reduces the likelihood of unintended matches; on the Seeq side, it improves performance of indexing and trending, since a smaller query against AF is required to find all relevant matches. The top-level condition in Seeq will be named "North Plant Batches" and will return capsules for all Event Frames that match the top-level search criteria. Child conditions will be created on the basis of each unique name of an Event Frame found below the Event Frames of the top-level search, and the names of the associated conditions will be like "North Plant Batches\Operation1", "North Plant Batches\Operation2", etc., where the part after the backslash in the condition name is one of the unique child Event Frame names found while training the connector during a sync. If the child Event Frames have child Event Frames of their own, conditions will be created for these also, with the same naming pattern continuing for each additional level of Event Frame. If all of these requirements are satisfied, the child conditions be arranged hierarchically below the root condition by tree relationships. As with partitioned conditions, the training window must be set correctly using the TrainingIntervalStart, TrainingIntervalEnd, ResetTrainingWindow, and ExtendTrainingWindowEachSync parameters to ensure that all relevant conditions are available for trending and analysis in Seeq.

Partitioned with Child Conditions

In the most complex case, both partitioning and child conditions will be used to define content in Seeq. Fortunately, since partitioning is only applied at the top level of the resulting hierarchy of conditions, the configuration is not much different from previous cases. For completeness, here is a configuration with both partitioning and child conditions:

Query Configuration with Partitioning and Child Conditions

CODE

          "EventFramesQueries": [
            {
              "ConfigName": "Partitioned S88 Batches",
              "ConditionNameTemplate": "Series ${PartitionBySeries} Batches",
              "ConditionDescriptionTemplate": "This Condition covers batches in Series ${PartitionBySeries}",
              "ConditionMaxDuration": "7d",
              "SearchFullHierarchy": false,
              "SearchMode": "Overlapped",
              "SearchRootId": null,
              "EventFrameNameFilter": "*-EN-*",
              "EventFrameCategoryFilter": null,
              "ElementNameFilter": null,
              "PrimaryReferencedElementCategoryFilter": null,
              "EventFrameTemplateFilter": "Procedure",
              "AttributeFilters": null,
              "ExtendedPropertyFilters": null,
              "Partitions": [
                {
                  "PartitionName": "PartitionBySeries",
                  "PartitionScope": "Name",
                  "PartitionExpression": "[0-9]{3}[A-Z]-([0-9]{2}).*-EN-.*",
                  "PartitionSearchFilter": "*-${PartitionBySeries}*-EN-*"
                }
              ],
              "CreateConditionsForDescendants": true,
              "PropagatedProperties": [
                "BatchID"
              ],
              "HierarchicalConditions": true,
              "TrainingIntervalStart": "2014-11-05T20:21:14.9337781Z",
              "TrainingIntervalEnd": "2018-11-16T06:31:20.5345501Z",
              "ResetTrainingWindow": false,
              "ExtendTrainingWindowEachSync": true,
              "UseSimplePropertyNames": false,
              "AttributePropertyPaths": [
                ".\\|BatchID"
              ]
            }
          ]

In this case, it is assumed that some of the Event Frames at the top level of the AF Event Frame hierarchy have names that contain the string -EN- and start with three numbers, followed by an uppercase letter, a dash, and a two-digit number. The requirement to contain -EN- is used for the initial search for Event Frames, and the remaining nomenclature is used to identify partitions of the conditions in Seeq. The captured expression is the two-digit number, which represents the production "Series". This is reflected in the name of the associated Seeq condition using the partition rules described in the section above for Partitioned Conditions. In this case, however, each top-level Event Frame is expected to have one or more levels of descendant Event Frames, for which conditions are created using the partition-based names of the top-level conditions as the first component of the name. Otherwise, the patterns for child conditions are the same as described above in the section on Child Conditions. The result is a set of hierarchical conditions for each partition-defined condition created by the Partitions list. If HierarchicalConditions is true, tree relationships will be defined for all of the resulting parent-child relationships between the conditions, which is also reflected by the nomenclature for the child conditions.