Synchronization in PI APS

The Synchronization overview section discussed the general concepts for automatically synchronizing the PI points for an interface instance with the corresponding data source tags. This section provides details on additional features of PI APS and its actual implementation. The following diagram shows the major subcomponents of PI APS.

PI APS Internal Structure

The diagram in this figure is a more detailed version of the PI APS Overview figure shown in Introduction to PI APS. As in the earlier figure, dotted arrows represent the flow of actual process measurements, and the solid arrows represent the flow of tag and attribute data.

In the Synchronization overview section, the concepts and algorithms for automatic point synchronization are universal, but many of the details are interface specific. In the interest of maintainability and extendibility, the implementation of the actual synchronization process in PI APS is partitioned into a generic component called the PI APS Synchronization Engine and interface-specific components called PI APS Connectors.

The Synchronization Engine is a program that is installed as a Windows service. The Synchronization Engine implements scheduling and the generic aspects of synchronization, including all PI SDK calls to obtain or change PI point information (and, as discussed later, all calls to obtain or change information in the APSPoints database). By itself, the Synchronization Engine is unable to communicate with any data source.

PI APS Connectors embody the interface-specific details. All PI APS Connectors implement a specific set of functions required by the Synchronization Engine, although the implementation of each PI APS Connector is different. PI APS Connectors are built as dynamic link libraries (DLLs), which allows them to be dynamically loaded by the Synchronization Engine. That is, the PI APS Connectors "plug into" the Synchronization Engine. PI APS Connectors cannot execute on their own and, except in unusual cases (like the PI to PI Interface - APS Connector), PI APS Connectors do not contain any PI API or PI SDK calls for PI point information.

Primarily, each PI APS Connector is a wrapper for the programming interface to a specific data source. The Synchronization Engine calls functions in the PI APS Connector that actually call the data source programming interface. Other functions in each PI APS Connector return details that the Synchronization Engine needs to adapt itself for a specific interface instance. For example, each PI APS Connector implements functions that return the specific attribute used for interface instance ID, the list of key attributes, the list of known attributes, and the list of syncable attributes.

Because completely automatic synchronization may not be appropriate for all users, PI APS provides additional choices for handling available points, deleted points, and attribute differences for existing points. Each category of points has an automatic option that behaves as described earlier in the Synchronization overview section. In addition, PI APS provides two other choices for each point category: do nothing and store for review. Also, PI APS provides three variations of automatic for deleted points. The specific options for handling each point category are referred to as Rules.

When an interface instance is registered with PI APS, an APSPoints database is created for the interface instance. PI APS uses this database for several purposes, one of which is to store the differences between PI points and data source tags when a store for review rule is selected for a point category. The available points, deleted points, and point edits tables in the APSPoints database are cleared at the start of every synchronization scan.

Referring to the figure, the flow of tag and attribute data during a synchronization scan is from the data source through the PI APS Connector to the Synchronization Engine. When the Synchronization Engine synchronizes an interface instance, it uses the rule for the particular point category to determine where the tag and attribute data goes next. If the rule is "do nothing", the information goes no farther. If the rule is automatic, the Synchronization Engine uses PI SDK to make any necessary changes to the PI Server (the updated information from the data source flows into the PI Server). If the rule is "store for review", the updated information from the data source is stored in the APSPoints database. In the latter case, the PI APS Configuration Utility can display deleted points, available points, and attribute differences for existing points that the Synchronization Engine found on the latest synchronization scan for the interface instance. The PI APS Configuration Utility can also selectively delete deleted points, create or hide available points, or synchronize attributes of existing points.

When a store for review rule is selected for a point category, tag and attribute data for the points in the category are always stored in the APSPoints database. The Synchronization Engine can be configured to create optional point logs for store for review rules. The optional point logs contain essentially the same information as is stored in the APSPoints database. The difference is the format of the data: the point logs can be formatted as either piconfig scripts or Excel workbooks suitable for PI Tag Configurator. The point logs can be used with the appropriate tool, either as-is or after editing, as an alternative to the PI APS Configuration Utility for updating the PI Server points to match the data source.

Each registered interface instance has a folder under %PIHOME%\APS where the APSPoints database is stored. See Registration of an interface instance with PI APS. If the optional point logs are enabled, one or more point log files may be created in the same folder each time the interface instance is synchronized. The PI APS Configuration Utility provides convenient access to the point log files (without having to navigate to them with Windows Explorer). To prevent the point logs files from accumulating, the Synchronization Engine provides options to remove point logs after they reach a configured age.

The APSPoints database has two other notable purposes. First, every PI point for an interface has a set of synchronization settings. Every point has a master synchronization setting and a synchronization setting for each syncable attribute. The per-point synchronization settings are stored in the APSPoints database. The master synchronization setting for a point must be enabled for any synchronization to occur. If the master synchronization setting for a point is enabled, then the per-attribute settings apply to the individual syncable attributes.

Second, the key attributes for any data source tags designated as hidden points are stored in the APSPoints database. In effect, hiding a point excludes it from the set of available points. If the Synchronization Engine is configured to automatically create PI points for available points, no PI points are created for the hidden points. If the Synchronization Engine is configured to store available points in the APSPoints database, the list of available points shown by the PI APS Configuration Utility excludes the hidden points. Thus, the list of available points only shows points that you may actually be interested in creating, relieving you from having to search for them among the extraneous points.

When the Synchronization Engine is idling in its main scheduling loop, discussed in Synchronization overview, any abnormal conditions are logged to the %PIHOME%\dat\pipc.log file. The pipc.log file receives messages from all PI applications on the host computer.

When the Synchronization Engine begins a synchronization scan for an interface instance, it creates a synchronization log specifically for that synchronization. Progress messages (such as times when the synchronization scan started and ended), auditing messages, and a summary of the synchronization are written to the synchronization log. Any errors detected by the Synchronization Engine also are noted in the synchronization log. The synchronization logs are created in the %PIHOME%\APS folder. The PI APS Configuration Utility provides convenient access to the synchronization log files (without having to navigate to them with Windows Explorer or understand how they are named).

During a synchronization scan, the Synchronization Engine calls the specific PI APS Connector for the interface instance. PI APS Connectors can report abnormal conditions in pipc.log, the synchronization log, or both and return an error code to the Synchronization Engine. The Synchronization Engine reports the error code in the synchronization log and also reports fatal errors to the pipc.log.

The first place to check for a synchronization failure is the pipc.log file. Check the synchronization log for additional information about the failure and about the synchronization.