SARTORIUS PI AF SimApi User Guide

This document is the user guide for the PI AF SimApi from Sartorius Stedim Data Analytics.
A SimApi is the connection between the Umetrics Suite and external data sources.

The PI AF SimApi described in this document is the connector between an Aveva (formerly OSIsoft) PI Asset Framework system and SIMCA®-online Solution and SIMCA® Multivariate Data Analysis Solution.
For a detailed list of changes in different versions of this SimApi, see the Version Info.txt file that comes with the installation. For more information on SimApis, see sartorius.com/umetrics-simapi.

Terms

Aveva PI name	SIMCA-online terminology
Event Frame (EF)	A batch with a start and stop time. Batches live in a Batch node in SIMCA-online. It can also be a phase with a start and stop time.
Event Frame attribute	A tag that holds batch data (one observation per batch)
Asset Framework Element	Unit, a physical thing such as a particular tank, or a logical such as a location, or building.
Element attribute, an attribute on an element, can be a PI point with process data or metadata describing the element.
Asset Framework Element Template (specifies the attributes that an event frame generated from that template can have)	Loosely corresponds to a Unit group
PI point	Tag

Features

The SimApi implements the following SimApi features: Refer to sartorius.com/umetrics-simapi to learn more about the general SimApi features.
Connect to an Aveva PI server with support for numerical (analog or discrete) values and text values

Connect to a PI AF server, enabling the use of Event Frames and the Element hierarchy
Use provided credentials, or use the account of the calling process (such as the SIMCA-online service account)

Current and historical continuous data for PI points and Element attributes
Top-level Points node containing all process data PI points

Batch data, partial support
Write back – continuous data for PI points (not for Element Attributes)
Write back – batch data, partial support
Optional node hierarchy of the PI AF Elements matching an Element Categories filter. Displayed in the top-level Elements node.
A batch node in the top-level Event Frames node, showing event frames that live in the root in PI AF.
Optional Event Frames Filters that expose a subset of event frames (batches) to SIMCA-online, based on criteria you specify.
You can filter on element, event frame name, event frame template, event frame category, and event frame attributes.
Synthetic process batch data tags, enabling easy batch project execution in SIMCA-Online.
Multiple instances of the SimApi can be run on the same SIMCA-Online server
Connection resiliency – the SimApi reestablishes the connection to the data source automatically after being disconnected. Some of these features are explained further below.
The following picture is used to illustrate the concepts, where the highlighted nodes correspond to bold items in the feature list above.

PI Elements hierarchy

When connected to an AF server, the SimApi will enumerate all Elements matching the Element Categories filter that you provide when configuring the SimApi.
More than one element category can be used to filter the elements. Separate categories with a semicolon (;). Elements belonging to any specified category will be displayed.
You can also specify * to show all elements, but this may negatively affect startup performance if there are many elements. An empty category filter means that no elements will be exposed.
The matching elements are displayed under the top-level node Elements. The same structure is used as in PI System Explorer.
Note that to expose synthetic process tags for an element (see below), it must match the element categories filter. Otherwise, the element is just shown as a container of child elements without attributes.

Element Attributes

Element attributes are displayed as tags in the Element node in SIMCA-online.
Attributes that are hidden or excluded in PI are not displayed.

Hierarchical attributes are named using their relative path separated by pipe (|), as seen from the containing element. For example, the Temperature|Attribute1 attribute in the screenshot above.

PI Points

If you specify to connect to a PI server when configuring the SimApi, that server’s PI points are displayed in the Points top-level node.

Points correspond to data tags in SIMCA-online, or variables in SIMCA, and are used to read process data for project execution.

On how batch data is read and written

Batch data is like an Event Frame attribute when the Event Frame describes a batch. However, Event Frame attributes are currently not supported by the PI AF SimApi.

Instead, the SimApi works as follows (corresponding to how Aveva implemented their AF SimApi):
Batch data is read as a PI point using the start time of the batch as given by the Event Frame to know for which time to read data.
Batch data is written to a PI point defined by the user with the time stamp of the batch start time as given by the Event Frame.

Event Frames

PI Event frames, for the SimApi, correspond to batches or phases in the process.
When an event frame represents a batch, it specifies the start and stop time of the batch and is used as a batch node in SIMCA-online, which enables monitoring event frames in that node in SIMCA-online, where you can also right-click on it to find matching batches in it, as this screenshot illustrates:

When an event frame represents a phase, it specifies the start and stop times of a phase.
If you want to monitor all phases of the batch in SIMCA-online, you can configure a hierarchy in PI so that batch event frames encompass the phases that belong to the batch.
Then you use the batch event frame as the batch node in SIMCA-Online.

Event frames are exposed by the SimApi in the Element node hierarchy, the Event Frames top-level node, and all configured Event Frame Filter nodes.

Synthetic process tags for Event Frame (batch/phase/step) name and duration

Synthetic process tags are created by the SimApi to help simplify project execution.

This feature does not work with concurrent (parallel) Event Frames. Thus, for any given time, there must be only one Event Frame active in the batch node.
Synthetic tags are created for the top-level Event Frames node, all Element nodes matching the Element Categories filter, and all Event Frame Filter nodes (see next section).

Synthetic tag name

Purpose

The name of the most recent active Event Frame in the node at the given time.

<EventFrameDuration(s)>

<EventFrameDuration(min)>

<EventFrameDuration(h)>

<EventFrameDuration(d)>

The duration of the most recent active Event Frame in the node at a given time.

The duration is scaled to seconds, minutes, hours, and days, respectively, allowing you to pick the one that matches your modelling needs.

Note: Synthetic batch tags generate an overhead in the SimApi, which can lead to lower performance, especially during catch-up and prediction of past finished batches in SIMCA-online.

Using the synthetic process tags for batch project execution in SIMCA-Online

In a batch project, the process data for each phase has to have a batch identifier tag. Data read in this tag is matched against the batches in the specified batch node to know if a phase should execute.
If the process data doesn’t have a batch ID tag, the synthetic process tags can be used instead, as the data for those is generated from knowledge about the event frame (batch).

To use this feature, go to the Execution conditions page of the project configuration in the SIMCA-online client and configure the Batch identifier tag to be the synthetic batch ID tag <EventFrameName> of the batch node.
Whenever the server reads the batch ID for the process data, the batch ID from the batch node will be returned, ensuring that the unit can execute (the phase execution condition must also be true, as usual in SIMCA-online).
Here’s the Batch node page of the configuration, showing that it is the same.

The filter node that is used as the batch node:

Read more on execution logic in the SIMCA-online Technical Guide.

Event Frame Filters

Event frame filters are optional and must be configured before they are exposed by the SimApi. You can add as many filters as you like; each is configured individually.
An event frame filter node is used as a batch node in SIMCA-Online to control project execution. The filter node exposes event frames (batches) that fulfil specified filter criteria.
Filter nodes also populate values for the synthetic tags that can be used in batch project execution as described earlier.

You can filter on reference element, event frame name, event frame template, and either event frame category or event frame attributes.

For example, you can create event frame filters for:

Event frames that have the attribute productType with the value of 42 under the Element “Sweden_Site”.

Event frames that have the name starting with “b” and the event frame category “SIMCAonlineBatches”.

Here’s an example of finding batches in SIMCA-online in one of the nodes containing Event Frames:

Prerequisites

This SimApi was originally developed for PI System version 2012 and has been tested on various PI Server versions up to PI Server 2018 SP3 Patch 5, at the time of writing.

To use the SimApi on a computer, it must have the following software installed:

The Aveva PI AF1 SDK. It is included in the PI AF Client that you obtain from Aveva. The SimApi was developed with version PI AF Client 2018 SP3 Patch-5 (version 2.10.11.2717).
Install this version or the most recent available version. https://techsupport.osisoft.com/Products/PI-Server/PI-AF/Overview

The Microsoft Visual C++ Redistributable for Visual Studio 2015-2022. Often, these are already installed on a computer (for example, they are installed automatically by SIMCA or SIMCA-online), but if the SimApi fails to start because of this, download and install the latest version from https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads

Aveva PI System security

PI uses the following concepts that control access.

PI can use Windows authentication, which means that Active Directory accounts are used to configure the security.
This method is recommended by Aveva and Sartorius Stedim Data Analytics since it is the only method to authenticate towards the Asset Framework SDK.
PI Users are users with passwords that are created on the PI server. Groups can be used to group users.

PI Trusts determine which computers are allowed to connect to the PI server. Trusts are IP-based, thus, they rely on DNS.
The SIMCA-online server must be added to the PI trust; otherwise, it won’t be able to connect to the PI server.
In addition, networking firewalls might also have to be configured to allow the SimApi to connect to remote servers.

These topics are explained in detail below. For details, consult the PI documentation.

Windows security

Windows security principals (groups or user accounts) can be used to configure access to the PI server.

You must know the user account used for running the SimApi. For SIMCA this means the user account that are logged in on the computer, but for SIMCA-online it means the service account used by the SIMCA-online server service (configured in the Services control panel in Windows). Note that the default for a SIMCA-online server is to use the service account Local System. This must be changed to a domain user service account in order to be able to setup access for it inside PI.
If you are unable, for any reason, to change the user account which is used for running the SimApi, you can also set the user account from the SimApi configuration dialog.
This makes it possible to use a different account to connect to PI than the service account for SIMCA-online.

When you know the user account, you configure PI to allow this account to connect to the PI server.
This can be done by making sure the user (or a group where the user is a member) is included under Security Mappings in the PI System Management Tools.

PI servers in another domain than the SIMCA-online server

If the PI system sits on a different domain than the SIMCA-online server, the deployment might not allow you to set up a Windows trust between the different domains.
One solution in this case is to have a local Windows account created on both the PI AF server and SIMCA-online server since it is then able to resolve an authenticate the “.\UserName” passed from one machine to the other across domains.

PI Trust

PI Trust is another way to grant access to PI to application names, IP numbers, or names of computers. This is done in the PI System Management Tools under Security

Trusts, where you can specify:

Application name: A specific application name can be used to create a trust.
- For SIMCA, it is simca.exe (and simpler.exe for SIMCA before version 15).
Note that this SimApi does not work with the older OSIsoft PI Batch SDK (only PI AF as described above). If your PI system only supports PI Batch, you must use the PI SimApi developed by Aveva/OSIsoft.
- For SIMCA-online, the name is SIMCAonlineserver.exe, and SIMCAonlineconfig.exe (SIMCA-online Server Options, which is used to make the SimApi configuration).

IP Information: You can define a trust based on the IP information of the computer that runs the PI SimApi that you want to trust. You can specify IP information as a network path or IP address and netmask:
Network Path: The fully qualified domain name. For example, my_laptop.my_company.com
IP Address: IP address of the computer running the PI AF SimApi.

NetMask: If you specify an IP address, you must also explicitly provide a netmask. Failure to do so will generate an error. If you are requiring an exact match on an IP address, specify the netmask as 255.255.255.255. If you are specifying a Class C subnet, specify the netmask as 255.255.255.0 and the fourth field of the IP address as 0.

Windows account information

Windows Domain: Windows domain of the user running the application.

Windows Account: Windows username of the user running the application.
It is possible to use a dollar sign ($) for the username for a particular domain; then users on that domain can connect through this trust to existing PI users of the same name as the Windows user running the application.
This is called a dollar-sign trust.

To configure a dollar-sign trust, you typically first import your Windows usernames and passwords as PI users.
See Import Windows users in the PI System Management Tools documentation for PI. (The dollar sign is a valid value for the domain as well as the username.)
Here all three different ways to configure a PI trust have been used in combination, even though only one is needed.

This example trust allows permissions for SIMCA-online from the machine computer.sartorius.com.
For further information about PI Trusts, please refer to the help for the OSIsoft PI System Management Tools.

Firewalls between SimApi and the PI server

A networking firewall between the SimApi running in SIMCA, or SIMCA-online server, and the PI server can restrict network traffic so that the SimApi doesn’t work.
To enable the PI network traffic through, TCP port 5450 needs to be opened, this is the normal firewall access for PI. Also, from the AF Server to any AF Client application, TCP port 5457 needs to be open.
See the following knowledge base article for further details: https://techsupport.osisoft.com/Troubleshooting/KB/KB00751

To learn more about firewall requirements for PI, see the PI Server / PI-SDK documentation from Aveva. The PI AF SimApi acts like a PI Application, so look for that term in that document.
Using the SimApi with only a PI AF server (without a PI server configured in the SimApi)
When using only PI AF server and the user wants to read element attributes connected to a PI point, the SimApi cannot authenticate against the PI server since there is no such option through the SDK.

In this case we either rely on what the SIMCA-online server service is running as or if there is a trust setup against the SIMCAonlineserver.exe.

One reason for the error message ‘Failed to initialize SimApi’

The error message “Failed to initialize SimApi” appears when clicking the Configure button in Server Options. This problem was solved in PI Database Security by giving the identity mapped to the trust write access to the PIMSGSS table.

Real-time delays caused by to PI-to-PI interface configuration

If the data on the PI server is pushed from another PI server via a PI to PI interface, delays in reading current data can occur since data is pushed at a specified time interval.
Make sure the time interval configured in the PI to PI interface is short enough to detect changes in your process in real time. It must be comparable to the execution interval used in SIMCA-online.

Installation and setup

Refer to the SimApi Guide located at sartorius.com/umetrics-simapi for general step-by-step instructions that apply when installing a SimApi. That document also contains many troubleshooting and testing tips when installing a SimApi.
There are settings that must be made inside Aveva PI to enable the use of the PI AF SimApi, as well as many different settings that can be made for SimApi itself.
We recommend that you involve people from your company that knows your PI infrastructure when you configure this SimApi.

The tool PI System Explorer (installed with the PI AF SDK) lets you see how your PI AF is configured, and helps you make the necessary settings.

Configuring SimApi settings

To change settings for the SimApi in SIMCA-online, launch the Server Options utility, and on the SimApi tab, click Configure… for the SimApi instance you want to configure.

The same guidelines apply to SIMCA, although all screenshots and examples below are for SIMCA-online.
The following dialog is displayed. Configure the settings you require for your environment.
After saving and exiting, the SIMCA-online server service needs to be restarted for the changes to be effective.

The following settings are available.

Setting	Explanation
PI server	Enables PI points with data to be available in the Umetrics Suite. Write the name of the PI server to connect to and enumerate PI points from. This is optional, but if you leave this out, AF Server must be specified.
AF server	Enables Event Frames in the Umetrics Suite. Write the name of the Asset Framework server to connect to. This is optional, but if you leave this out, PI Server must be specified.
AF database	Directs the Asset Framework server to a specific database. Write the name of the Asset Framework database within the Asset Framework server to use. If this is left empty, the SimApi will use the default database on the server.
Element categories	More than one element category can be used to filter the elements. Separate categories with a semicolon (;). You can also specify * to show all elements, but this may negatively affect startup performance if there are many elements. If left empty, no Elements will be exposed.
Username	The credentials used to connect to the PI servers are provided above. Leave blank to use the account of the calling process, typically the SIMCA-online service account.
Password	The credentials used to connect to PI servers provided above. Leave blank to use the account of the calling process, typically the SIMCA-online service account. The password is encrypted, and not saved in clear text in the configuration file.
Event frame filters	You can create optional filter nodes by clicking the … button. These are used as batch nodes to define batches that execute in SIMCA Online. See 1.2.7 above to learn more, and see the next section for the available settings that you can control.

Log level	Controls how much information is written to the log file. (Debug, Information, Warning, Error, Critical). Debug helps troubleshoot issues with the SimApi.
Log max size (MB)	Controls the max size of the logfile before creating a new one. Setting this to 0 means infinite size.
Advanced settings	Refer to the descriptions of these items in the configuration utility.

Event Frame Filter settings

Event Frame filters expose Event Frames (batches) that fulfil filter criteria. They can be used as batch nodes in SIMCA-online as described in 1.2.7.

You can create two types of Event Frame Filters:

By Event Frame Attribute – these allow you to create logical conditions on one or more event frame attributes.
By Event Frame Category – these allow you to select an event frame category.
Both types of filters also let you specify a reference element, filter on event frame name, and specify an event frame template.
Each filter node must have a unique name that you provide. This is the node name used in SIMCA-online below the Event Frame Filter node top-level node.
Here is a table summarizing the various settings you can make in the configuration dialogs. Also refer to PI AF configuration dialog which has built in help for each setting.

Setting	Description	Used in a filter by Event Frame Attribute	Used in a filter by Event Frame Category
Node Name	An arbitrary name of the node (unique among other nodes). For example, ProductABatches.	X	X
Name Filter	Filter based on event frame name. Wildcard * and ? are supported.	X	X
Reference Element	Filter based on Element name. Wildcard * and ? are supported. Event frames that reference this element will be returned by the filter.	X	X
Event Frame Template	Filtered based on a specific Event Frame template.	X	X
Event Frame Category	Filter based on a specific Event Frame Category. Use * for any category.		X
Attributes	Filter-based Event Frame attributes. You can specify one or more attributes. For each attribute, you specify settings that control a logical expression that must evaluate to true for the event frame to match the filter. The settings for each attribute are:	X
Attribute Path	The name of the Event Frame template attribute. The path should be relative to the specified Event Frame template. The value for this attribute is compared with the Compare Value setting using the specified Operator.	X
Operator	Defines the type of comparison to make. For example, Equals.	X

Compare Value

The value to compare with the Event Frames attribute value. For string values, only operators Equal and Not Equal can be used.

More than one value can be used when using the operator in. Separate values with a semicolon (;).

Configuration example

This section gives an example how the PI system can look, and how the PI AF SimApi can be configured to connect to it.
The PI AF SimApi has already been installed, and the PI system has been configured to allow the user to connect to the server as described in 2.

Basic configuration

Here is the configuration for the PI AF SimApi opened via the SIMCA-online Server Options. As you can see, we have made a few settings which are explained below.
We have one server, ServUmVM3, which is entered in both the PI server and AF server fields.
In PI, our database is called Production as you can see in the below screenshot, so that’s what we use in the configuration too.
We also specify the username and password that the PI AF SimApi uses to connect to the PI AF servers. This user has already been given rights to access PI.
We use a different service account for our SIMCA-online server. It is different because it must be able to access our Active Directory for user authentication.
These are the service properties on the SIMCA-online Server machine.

Optional Element categories

We specify Element Categories A_Simca_Element; Other_Category. This means that we’ll see all Elements matching either category in SIMCA-online.
Here is how the Element category A_Simca_Element looks on the PI Server.

Optional ‘By Attribute’ Event Frame filter

We have configured an Event Frame filter node by Attribute as follows, to only see event frames with a tank level below 40:

Here’s what our Event Frame Template looks like in PI:

We’ll use that Level attribute in our filter node to show only Event Frames with Level below 40

Here’s the first configuration page for our By Attribute filter node:

Important: The Level as provided in the above screenshot must be replaced with the full path to the attribute, which you can copy from PI System Explorer.
For example: \\serverName\Production\Level

Here are the settings for the Level attribute:

Optional ‘by Category’ Event Frame filter

Finally, we have also configured a Filter node that exposes event frames based on the Event Frame Category Yeast.

What does this look like in SIMCA-online

This is what the above settings result in in SIMCA-online.

Here, the Element nodes, the Event Frame Filter nodes, and the Event Frames node can be used as batch nodes in project configurations.
Synthetic <EventFrameName> tags can be used in Execution Conditions for the simple execution of batch projects. An example of this can be found in 1.2.6.1.
The PI points of the PI server are visible under the Points node. These tags are connected to variables in the Phase tags page of the project configuration.

On SIMCA-online project execution and PI AF

This chapter gives a short primer on what SIMCA-online needs to execute batch projects and gives some recommendations that apply to PI Asset Framework (AF) and PI Event Frames (EF).
For full details on SIMCA-online execution logic, see the SIMCA-online Technical Guide.

Batch IDs in SIMCA-online

SIMCA-online makes use of batch IDs in two ways.
The batch ID is an event frame defined in PI AF.
- In SIMCA-online, these are interpreted as batches in what is referred to as the batch node.
- The batch node is used to identify completed and presently active batches.
- Finished batches are those that both have a start time and an end time.
- Active batches are those that only contain a start time, with the end time as empty/null.
Batch ID as a process tag:
- Each unit that may process a phase for a batch requires a separate process tag indicating the batch that is active in that unit.
- The value of the batch ID must match the batch name in the batch node, or, to use the PI terminology, by the name of the event frame in PI.

Batch node selection in SIMCA-online

In the asset framework, there is a hierarchy of events created following the ISA 88 batch standards.
The batch must stay active for the duration of all phases that belong to that batch. For batches with multiple phases, the batch event needs to start at or before the first phase is triggered and end at or after completion of the last phase.
In SIMCA-online, independent phase execution conditions are used to define the lifespan of each phase.
The EF batch event is only used for genealogy of phases, to map which active units belong to which batches.
This allows for tracking of parallel and complex material flow through multiple units.

In PI, the hierarchy of units takes the form:

Batch
- Unit
  - Phase
  - Subphase
In SIMCA-online, there is a lot of flexibility in how batch nodes and batches are defined and interpreted.

For example, in Chromatography, where:

Each cycle may be defined as a phase,
Each unit operation (Loading, Equilibration, Elution, etc.) may be defined as a subphase,
The batch node in SIMCA-online could be defined on the unit level,
- Each cycle could be defined as an event in EF and a batch in SIMCA-Online, and
- Each unit operation could be defined as a subphase in EF and a phase in SIMCA-Online.

SIMCA-online execution logic

This outlines the sequence SIMCA-online follows to start batches and phases. For the full algorithm with all details, see the SIMCA-online Technical Guide.

SIMCA-online determines the active batches
- a. Request the EF items – maybe there is a special request for only the active ones – from the SIMCA-online’s defined batch node (the batch node could be server or Unit level).
- b. Active batches are defined as those that do not have an entry for the end time (it is left null/blank).
- c. SIMCA-online records the names of the active batches.
SIMCA-online determines if there are any active phases
- a. SIMCA-online requests the name of the batch running in each phase. The name of the batch is the value retrieved from the process tag configured as the Batch ID in the unit.
- b. SIMCA-online checks to see if the name of the batch is in the list of active batches It does by checking if the value matches the name of an active batch.
- c. SIMCA-online evaluates the trigger logic configured in SIMCA-online to determine if the phase is active.
SIMCA-online extracts the snapshot values for all tags used by active phases

Support

This SimApi is developed by Sartorius Data Analytics. For support, please visit sartorius.com/umetrics-support
For Aveva PI related questions such as the Asset Framework, Event Frames, PI security and the like, we advise you to contact you Aveva representative or their technical support directly.

FAQs

Q: What is a SimApi?
- A: A SimApi is the connection between the Umetrics Suite and external data sources.
Q: What are Event Frames in SIMCA-online?
- A: Event Frames represent batches with start and stop times, residing in a Batch node in SIMCA-online.
Q: Where can I find more information on SimApis?
- A: Visit sartorius.com/umetrics-simapi for detailed information on SimApis and their features.

Documents / Resources

SARTORIUS PI AF SimApi [pdf] User Guide
PI AF SimApi, AF SimApi, SimApi

References

User Manual

SARTORIUS PI AF SimApi

Product Information

Product Usage Instructions

Introduction