Serving data from the IP.21 System to the AspenTech Inmation System
When running as a gRPC Server, the AspenTech Inmation IP.21 Server acts as a man-in-the-middle between the IP.21 system and the AspenTech Inmation system. While the connection between the AspenTech Inmation IP.21 Server and the IP.21 system is addressed on the page on Installation and Basic Configuration of the IP.21 Server, the present page focusses on the connection between the IP.21 Server and the AspenTech Inmation system.
gRPC Server Configuration
To configure gRPC Server functionality which the IP.21 Server provides for the AspenTech Inmation system …
1 Select the IP.21 Server object in the System Model.
2 In the Property Panel, expand the gRPC Server property compound.
3 To enable the gRPC Server functionality, select the checkbox for the Enable gRPC Server property.
4 The gRPC Server Port property defines on which port the IP.21 Server is listening for connection requests. By default this is 6518.
5 The ItemValue Mode defines which fields of a record on the InfoPlus.21 system are used to set the value of the corresponding IO-Item on the inmation side. Pick the option that matches the configuration on the InfoPlus.21 system:
Default - The ItemValue is selected according to the mapping configuration on the the InfoPlus.21 system. The value is taken from the first of the following fields which has PUBLISH_UPDATES activated:
1 MAP_HistoryValue field
2 Field pointer of the MAP_HistoryValue field (if set)
3 MAP_CurrentValue field
4 Field pointer of the MAP_CurrentValue field (if set)
Merge - All values of the mapped fields from MAP_HistoryValue (1), the Field pointer of the MAP_HistoryValue field (2) MAP_CurrentValue (3), and the Field pointer of the MAP_CurrentValue field that have PUBLISH_UPDATES activated, will be replicated to ItemValue.
6 Expand the Replication compound and make sure that the Replication Queue Usage property is enabled. Otherwise subscriptions are not possible. Browsing is still possible, though.
7 Click Apply on the Property Panel to confirm the property changes.
Connecting the AspenTech Inmation System to the IP.21 Server
For a data connection to the newly installed IP.21 Server, a new Datasource IP.21 gRPC object is required.
Creating an IP.21 gRPC Datasource
Create an IP.21 gRPC Datasource object as described in the Datasource IP.21 gRPC guide.
The Subscription Delivery Mode
By default IP.21 gRPC Datasources are running in Subscription Delivery Mode Realtime which focuses on transferring data as soon as an IP.21 replication message is generated and doing so as quickly as possible. In general, depending on the datasource type and communication protocol, small outages are handled by internal in-memory buffers but data may be lost due the limited buffer size. Data changes on the server are typically not persisted and forwarded in case of a datasource losing connectivity or stopping to respond for a longer period of time.
Alternatively the Guaranteed mode can be used which ensures that all data is delivered. In this mode, in case of an outage or an overload situation, data is backfilled, with the oldest changes arriving first. In case of larger outages it may take an considerable amount of time until all data is available, though.
|
While this mode can typically cover outages of multiple hours, it still operates with finite resources. If data cannot be forwarded to the configured IP.21 Datasource Target, the SaF database will use up all the disk space configured in the Store and Forward Retention Method property compound of the Node owning the Datasource object (20 GB by default). |
Guaranteed Delivery Mode Configuration
For each gRPC DataSource using Subscription Deliver Mode Guaranteed an individual IP.21 Blob Buffer object needs to be installed on the Node running the IP.21 Server object. For detailed setup instructions, see the IP.21 Blob Buffer Object Guide.
|
If a datasource loses its connection to the IP.21 gRPC server or the owner Node is restarted, current values are not received again as only data changes are received. If values change rarely and the IP.21 gRPC datasource child items should retain their current dynamic values, set the Auxiliary State Management > Strategy property to Inhibit. To keep in mind: The persistence mode will affect system performance. For example, if tens of thousands of items are configured to persist immediately, this will put strain on the speed of the entire system and there will be a lag in updating dynamic properties. It is therefore recommended to be selective in using the Persist Immediately option. |
Browsing the Server Namespace
|
Namespace browsing can be strenuous on the browsed system, depending on the amount of matching tags and the frequency of browse runs. |
To browse the server namespace …
1 In the I/O Model, select the IP.21 gRPC Datasource object.
2 In the Object Lens, navigate to the Server Type > Browse Control property compound.
3 In the Browse Options property, specify when you want to browse the server namespace.
4 If you picked 'Browse Periodically', specify the interval for the browse runs in the Browse Period property.
5
In the Tag Filter enter a string to limit the tags discovered during a browse run. For example, A* finds all tags beginning with A.
If this property is left empty, all tags from the server namespace are discovered on a browse run.
|
Filtering is case-sensitive. The asterisk * is a wildcard that represents any number of characters, including none. The question mark ? is a wildcard that represents a single character. |
6 Click Apply for the Object Lens.
If you selected Browse once as the Browse Option, the browse run is triggered and tag objects for the data tags on the source IP.21 system matching the Tag Filter string are created underneath the Datasource object.
Subscriptions
If replication of a discovered tag is enabled on the IP.21 System side, this tag is subscribed to and the IO Item is in green state. If the IO Item is in red state, replication not being enabled on the IP.21 System side for this tag is the most likely cause. For data to be transferred, enable replication for this tag on the IP.21 System.
Discrete Tags
Replication of discrete tags (IP_DiscreteDef) from IP.21 to the IP.21 gPRC Datasource requires that replication is enabled for the IP_DiscreteDef definition record and the Discrete tags/records themselves. Replication should also be switched on for the selector record definitions with fields.
After browsing, the discrete tag will be replicated along with the selector tag below the Datasource. The discrete tag will display number values but not the associated strings values. A child IO-Table Holder will be created below the selector record tag containing the mapping between numeric value and selector string values.
It is possible, using Lua scripting, to translate the number value on the discrete tag to its mapped string value in the IO-Table Holder, and return that instead.
| After browsing, The selector record tag will appear to have a bad state, this is because there is no IP_VALUE associated with selector records. |
Secure Connection Options
By default the connection between the IP.21 Server service and IP.21 gRPC Datasources the Built-in option is used for the gRPC Server > Certificate Configuration > Server Certificate Type property on the IP.21 Server service and the Server Type > TLS Credentials > Certificate Authority property on the Datasource object.
In this case a certificate which is created during the installation of the IP.21 Server service is used which is validated by the IP.21 gRPC Datasource against the built in AspenTech CA Certificate key.
In the following sections, all available configuration options for Secure Connections are discussed.
IP.21 Server Service Secure Connection Options
On the IP.21 Server object, the following options are available for gRPC Server > Certificate Configuration > Server Certificate Type:
Built-In (default) - the default certificate is used. The Built-In Certificate Credentials > Server Certificate property is automatically configured to point at this certificate.
Custom - use certificates generated by another Certificate Authority (other than AspenTech CA), e.g. a custom certificate as described in Creating a Custom Certificate
If you select this option, follow these steps:
1
In the Certificate Credentials > Certificate property, specify the server certificate file
(e.g. D:\certificate-environment\IP21\certs\server.cert.pem from Creating a Custom Certificate).
2
In the Certificate Credentials > Certificate Key property, specify the server private key file
(e.g. D:\certificate-environment\IP21\private\server.key.pem from Creating a Custom Certificate).
|
Changing this property while a connected IP.21 gRPC Datasource object has its Certificate Authority property set to System requires the re-initialization of the TLS Credentials on said Datasource object. |
IP.21 gRPC Datasource Secure Connection Options
Datasource objects of Server Type IP.21 gRPC offer the following options for Server Type > TLS Credentials > Certficate Authority:
Built-In (default): the CA certificate is taken from the system itself. In this case AspenTech’s CA Certificate is used to validate the server certificate. This is the standard option to choose if the Secure Connection on IP.21 Server object addressed above is configured to use the built-in Server Certificate.
Custom: the custom CA certificate is taken from a location in the file system. In this case the full path to the certificate needs to be specified in Custom CA Certificate property to specify the CA certificate against which the server certificate is validated. This is the standard option to choose if the Secure Connection on IP.21 Server object is configured to use a custom Server Certificate, e.g. D:/certificate-environment/certificate-authority/certs/TheCertificateAuthority.cert.pem from Creating a Custom Certificate.
System: Alternatively to the Built-In and the Custom option, the root CA certificate chain based on the Windows certificate store can be used to validate the server certificate, so the CA certificate needs to be added to the Windows Certificate Store:
If the IP.21 Server object is configured to use the Built-in option, the AspenTech CA certificate which comes along with the AspenTech InfoPlus21 system needs to be added to the Windows Certificate Store.
For the Custom option , it’s your custom CA certificate (e.g. D:/certificate-environment/certificate-authority/certs/TheCertificateAuthority.cert.pem ) which needs to be added to the Windows Certificate Store.
| To use the System option, the System Mode Requirements have to be fulfilled. |
The Server Type > TLS Credentials > Custom CA Certificate property specifies the CA Certificate which is used if the Custom option is selected for Certificate Authority property. Click on the Import icon to browse the file system to set the path to the CA Certificate. The eye icon opens the Certificate Viewer. Clicking on the Trashcan icon empties the property.
System Mode Specifics
This section addresses requirements regarding the System option for the Certificate Authority property of the IP.21 gRPC Datasource as well as specific steps which may be necessary when using this mode.
System Mode Requirements
For the System option it is necessary that the Node service is running with administrator privileges.
To promote the Node service, …
-
Log-in to the machine on which said service is running with an administrator account.
-
Run the Windows services app and find the Node service.
-
Right-click on the service and select Properties from the context menu.
-
Go to the Log on tab and select the This account: option and click Browse.
-
In the Select User dialog, enter a the name of a user to which administrator privileges have been granted in the Enter the object name to select text field and click Check Names.
-
Click OK to confirm the selected user name and close the dialog.
-
Back in the Log on tab of the service properties, enter the password for the selected user in the Password field and repeat it in the Confirm Password field.
-
Then click Apply to confirm the changes. Some feedback messages will be displayed. Confirm them by clicking OK.
-
Back in the services list, right-click on the service and select Restart from the context menu.
Re-Initializing the TLS Credentials
If System is configured as the Certificate Authority property on an IP.21 gRPC Datasource while the Server Certificate Type property on the IP.21 Server object is changed, the TLS Credentials on the IP.21 gRPC Datasource object need to be re-initialized with the other CA Certificate.
To do this, switch the Certificate Authority property to any other option but System, click Apply, switch the Certificate Authority property back to System and click Apply once more.