Batch Record Datasource
This section will demonstrate the configuration set up of the Batch Record Datasource. For more information, please visit the Batch Record Datasource section of the System Documentation.
Creating a Batch Record Datasource
Select the appropriate Connector in the I/O Model and right-click. Select from the context menu. In the Create Object wizard, enter a name for your Datasource and, optionally, an Object Description. Click Next.
On the Server Type page of the wizard, select Batch Record from the drop down menu and then enter a BatchRecord Name (this is a logical name that is used only used internally by system:inmation - but can contain some technical attributes of the server if desired). Click Create to create the Datasource in the I/O Model.
Once created, the Datasource will be in a neutral communication state, (indicated by the green-grey light combination in the I/O model) until the rest of the configuration is completed.
The Properties panel of the created Datasource should look like below with the Operation Mode set to Configuration.
Operation Modes
When a Batch Record Datasource is first created it is by default in the Configuration Operation Mode. Once configuration has been completed, the Operation Mode can be changed to go through testing and then production modes. The table below explains each Operation Mode and its behavior.
| Operation Mode | Meaning | Note |
|---|---|---|
Configuration |
The Batch Record Datasource object is ready to be configured. No action, data acquisition or data forwarding are carried out. |
|
One Shot |
The Batch Record Datasource attempts to acquire the most recent batch from the configured external system. In case data is successfully acquired the object will process the data according to the current configuration and display the resulting data document in the Diagnostics. No data is forwarded to Asset Effectiveness and/or Production Tracking recipients. |
Use this mode to learn about the data structures returned from the external system and to complete the configuration. |
Test |
The Batch Record Datasource will run as if in Production mode, but it will not forward data. Inspecting the Log entries created, you will be able to judge whether the configuration is sufficient in order to create the correct inserts for Asset Effectiveness and/or Production Tracking. |
Use this mode once you have completed your configuration and use the Log messages created in order to check for erroneous or incomplete configuration or general problems. |
Production |
The Batch Record Datasource acquires data periodically from the configured external system, applies the configuration, processes the data and forwards it to the Asset Effectiveness and/or Production Tracking recipients using an Event Stream co-object in the Connector. |
Use this mode once the configuration for one or multiple Batch Units is complete for a particular Batch Record Datasource. |
Selection of the Interface
The interface type is selected from the drop-down menu in the Interface property. The following interface options are available:
-
AspenTech SQLplus
-
PI Bridge
-
External Tags
Each interface type and their important properties are described.
AspenTech SQLplus
The AspenTech SQLplus interface allows the Batch Record Datasource to retrieve Batch Records from any AspenTech APRM system (AspenTech Production Record Manager, formerly known as Batch.21). inmation uses the SQLplus ODBC interface to access the data so the main configuration should be done in the ODBC Connection section of the properties.
- Datasource Name
-
This setting must be identical with the name which has been configured with the Windows Operating System’s ODBC configuration for this ODBC data source.
- User Name
-
A user name can be configured here. This is only required in case the Connector executing the Batch Record Datasource is not running under an account which has access to the AspenTech software.
- Password
-
Again, only needed if the parent Connector is not running under an account which has access to the AspenTech software.
- UTF-8
-
This setting is checked as default and in most cases should be kept this way. This prevents errors in converting country-specific characters (for example ä, ö or ß) during text transmissions.
- Code Page
-
This setting should be kept in default state (00000 Current Code Page). For character translations, inmation defaults to the Code Page which is active for the user account which the Connector service uses. This setting should only be changed if the textual parts read from AspenTech’s APRM contain unusual characters.
- Batch Data Source
-
This is the Batch Data Source as originally defined in the APRM configuration software. In case you are not sure, which Batch Data Sources exist in a particular APRM system, you can use Aspen One’s Batch viewer to see which Batch Data Sources are provided for a particular APRM connection.
- Batch Area
-
This is the Batch Area as originally defined in the APRM configuration software. Batch Areas belong to a batch Data Source. All Batch Records for a certain Batch Area share the same characteristics, which in turn means that one inmation Batch Record Datasource can process data for all Batch Units which have been configured under a particular Batch Area. In case you are not sure, which Batch Data Areas exist per Batch Data Source in a particular APRM system, you can use Aspen One’s Batch viewer to see which Batch Data Sources are provided for a particular APRM connection.
PI Bridge
The PI Bridge interface allows the Batch Record Datasource to retrieve Batch Records using the PI Bridge system. To configure this interface the PI Connection settings section of the object properties should be set.
- Host Name or IP
-
This is the Host Name or IP Address of the PI-Bridge service, which shall be used to make the connection to the PI-Batch interface. It is not the IP Address of the PI system itself. In most of the cases, the PI Bridge will be installed on the Connector Host which executes the Batch Record Datasource, so no change is required.
- Port
-
This is the standard port of the PI-Bridge. It must be identical with the PI-Bridge configuration.
- Timeout
-
The default connection timeout is set to 10s. This can be changed if required.
- Debug
-
This puts the PI Bridge library in Debug mode and should only be checked when troubleshooting issues.
- Batch Data Interface
-
This configures which interface the Batch Data will be acquired from. Options are:
-
PI Server using the PI-Batch SDK
-
PI Server using Asset framework (AF) server and event frames (for this option, the OSI PI AF server needs to be properly configured).
-
- PI-Server
-
This setting is important as it informs PI-Bridge which PI system to connect to in order to retrieve Batch Records.
Testing the Interface
After the Interface property has been chosen and configured, it is wise to do an interface test to be sure everything is working and data can be received by the Batch Record Datasource object. In the Object Properties pane and select the Operation Mode property. Set it to One Shot and click Apply.
| The One Shot operation mode differs from the Test mode in that it will only retrieve the latest Batch Record from the connected system. This is usually a better first testing approach than using the Test mode which retrieves multiple Batch Records. Changing from the Configuration Operation Mode to One-Shot (or any other operation mode) will also automatically create a Script Event object underneath the Connector in the I/O Model tree. This object will receive event information from the Batch Record Datasource. The events can be viewed by adding the object to an Event Viewer display. |
There are three indicators as to whether the interface is working correctly:
-
The Datasource shows two green lights in the I/O model, indicating that both the overall object state and the communication state are good.
-
The fields in the Diagnostics section of the Object properties are filled.
-
An Information message will be visible in the Datasource object’s log indicating a successful connection.
If the interface is not working correctly these indicators will not be present and an Error message will most probably be visible in the log. The Diagnostics information will look something like below if the interface is working correctly.
| Property fields with a grayed background are non-configurable in inmation. They are mainly used to report back and give feedback about the background processing state of the various system objects. |
An explanation of the Diagnostics fields is given below.
- Recent BatchID
-
This field shows the unique ID of the most recent Batch Record obtained from the external system. As this example has been taken from an AspenTech APRM system, it is a numerical value (AspenTech APRM uses increasing counter values as unique batch identifiers).
- Recent Acquisition
-
The local time (of the DataStudio user’s timezone) of the most recent (successful) data retrieval operation against the external system.
- Recent Data
-
The Recent Data field holds the entire Batch Record data document. This Diagnostics field is very important for the support of the configuration activities, because you might use it to test the success of your configuration activities on the fly. It is important to remember that keeping the Batch Record Datasource object in Configuration or One-Shot mode until the configuration is complete is considered best practice. Incorporating the visual inspection of the Recent Data field as a routine during configuration eases the task considerably. From a final reception perspective of the Asset Effectiveness and/or Production Tracking components in the system: What you see (in Recent Data) is what you get (into the system).
- Active Batches
-
This table lists all active batches which the Batch Record Datasource has currently obtained from the external system. It can be empty, in case there is no active Batch at the moment of the One-Shot execution.
The Recent Data field will contain the last Batch Record in its entirety. Right-clicking on the field and selecting Zoom (shortcut Shift+F2) will display the JSON string in a new dialog window:
The structure of the Batch Record JSON can be seen by clicking on JSON Viewer to open the Batch Record in the JSON Viewer display.
Troubleshooting
If you encounter problems connecting the interface, these examples should help you identify the source of the issue.
Diagnostics property compound stays empty and the Datasource shows two red dots in I/O Model tree
In this case (indicating that no data has been transmitted), right-click on the Batch Record Datasource object in the I/O Model panel and select Admin → Open Log → Last 10 Minutes (you may choose another time period which suits you, but you should be sure that it covers the connection attempt). You should see one or multiple error messages showing up. If you double-click one entry in the list it shows the log details. You can also navigate up and down in the detail view.
ODBC Datasource is not working This would show a Batch Interface Error with the following detail:
Please make sure that the prerequisites and interface configuration are correct. See the Prerequisites description and the interface selection for details on configuration.
The APRM Batch Data Source is misconfigured
The APRM Batch Data Source is misconfigured
The Information message indicates that the Batch Interface is connected, however the error message which follows indicates an error raised within the AspenTech ODBC driver software (respectively the AspenTech APRM SQL database). It tells us that the name of the Batch Data Source property is not correct and should be changed in the object properties.
The APRM Batch Area is misconfigured
The object in the tree now shows a green (lower) dot and a red (upper) dot The Log contains a message sequence like the one below:
This is similar to the error above, the information message indicates that the ODBC connection works fine. The message which follows right after indicates an error which again is raised within the AspenTech system. It tells us that the name of the Batch Area property is not correct and should be changed in the object properties.
Prerequisites
The configuration of a Batch Record Datasource requires some prior knowledge about the type of Batch Record system that is being connected to. Currently, external AspenTech APRM/Batch.21 and OSI-PI systems are supported (as well as obtaining Batch Records from tags within system:inmation). The different external system’s configuration details are covered here.
AspenTech APRM/Batch.21
All APRM batch records are fetched from the source system through a pre-configured ODBC data source on the computer running the Connector service. The Connector must have access to the particular ODBC data source. Therefore the following things need to be configured.
-
The APRM ODBC data source needs to be configured as system data source.
-
The APRM ODBC data source needs to be configured for the same bit-model which was chosen for the Connector service (due to the fact that there is no 64-bit APRM ODBC data source available, Connector services connecting to APRM need to be installed using the 32-bit version – inmation32.exe).
-
The Connector must be configured to use Logon credentials which grant access to the APRM system without supplying additional credentials in the Batch Record Datasource object, or alternatively such credentials need to be configured in the Batch Record Datasource and the Connector may run under its default LOCAL_SYSTEM account.
To set up the ODBC system DSN, open the appropriate ODBC Data Sources app in Windows (32 bit) and configure a System DSN using the AspenTech SQLplus driver.
The AspenTech SQLplus configuration dialog should look like the below example.
To configure the Connector service to use APRM logon credentials, open the Services app in Windows and right-click on the Connector service and select Properties from the context menu. In the Properties dialog, select the Log On tab and enter the APRM account details.
Connector Service - Configure APRM Log On credentials
OSI-PI
The OSI-PI interface requires the installation of a separate inmation service in order to retrieve Batch Records using PI-Bridge. Please see the PIBridge installation instructions for details.
Batch Record Configuration
Once the interface is connected and working properly, the configuration of the Batch Records themselves can begin. This can be used then as a corporate-wide standard for Batch Records and is the basis for unified Asset Effectiveness reporting and/or Production Tracking (including vertical integration with MES and ERP systems). If we again bring up example of the Batch Record JSON document we can see some of the important parts of the JSON structure:
It consists partially of data from the external system (in this case AspenTech’s APRM), but is already extended in its structure as the Batch Record Datasource has already pre-processed the data, and tried to apply the configuration. At this stage, we might not yet have a configuration, but we already get the idea how the data document structure might look like. The basic node structure is explained in the table below:
| Node | Meaning |
|---|---|
SubBatches |
The SubBatches structure is an array of nodes, which may contain other SubBatches. SubBatches on the first level are Unit Batches. |
Batch |
This is the main Batch node. It holds the Characteristics node, plus a Processor node which is added by the Batch Record Data Source object. It also creates an Analytics node, which is populated by the data which is born out of the Batch Record Data Source configuration. |
Characteristics |
The characteristics data fetched from the external system either on Batch or SubBatch level. |
Unit Configuration
The Batch Record Datasource will only process Units that are configured in the object properties under the Unit Configuration property group. These will be transmitted to Asset Effectiveness and Production Tracking sinks. One Batch Record Datasource can be configured to manage multiple Units by adding separate Unit Configurations. To add a Unit Configuration open the property group in the Object Properties panel and click the plus symbol.
The configurable fields are:
- Source Unit
-
The Source Unit field must be configured with the exact Unit name or ID which is reported by the external system. From our example Batch Record that was obtained from the diagnostics panel, the "UNIT" field under the SubBatches’s Characteristics node, gave the Unit as "10002953". With other external systems, this could be name like "UNIT_01". This can be checked by examining the node contents in the Batch Records of your own system.
- Unit Asset Code
-
The Unit Asset Code field should be configured with the exact asset code, with which this particular Batch Unit is listed in the MES or ERP systems. It will guarantee compatibility between system:inmation and such systems in order to unambiguously characterize a particular Batch Unit.
- Unit Description
-
The Unit Description might be used in the Asset Effectiveness database sink in order to fully characterize the Batch Unit. It could give a more descriptive name, such as “DE-XXX Test Plant Unit C”. ISA-95 Parent Object The ISA-95 Parent Object allows you to select a particular Area object in the system:inmation S95 Equipment Model. This allows the system to automatically create an entry in the ISA-95 Equipment Model as soon as a particular Batch Unit is reported for the first time.
- ISA-95 Object Name
-
Here an actual Object Name can be selected for the Batch Unit object that will be created in the ISA-95 Equipment Model when the Batch Unit is reported for the first time. For this test example we will leave the ISA-95 object properties blank. The Unit Configuration will look like the below example. Click Apply to confirm.
Field Configuration
Following on from the above Unit Configuration, we still need to provide information so that the Datasource knows to look for the "UNIT" field in the Batch Record to retrieve the Source Unit property. This is done in the Field Configuration section of the Datasource properties.
For this example we will add a Unit Field option to link the Unit Configuration we created. Click on the plus sign to add a Unit Field Option.
The fields are filled out in the following ways:
- Source Field
-
The field name which is supplied in the ‘Characteristics’ table provided by the external system. You may learn about available source characteristics either by inspecting the ‘Actual Data’ property in the ‘Diagnostics’ compound, or by good knowledge obtained from the configuration of the external system which supplies the characteristics.
- Target Field
-
This is the list of well-known fields which have relevance and importance for the further processing chain in terms of Asset Effectiveness and Production Tracking in general. Select an appropriate target field from the dropdown menu.
- Field Processing
-
This property dictates how the source field value will be processed. This includes options to use the value directly (or convert to a number or Data/Time), to specify a fixed value to use when this field is encountered, to specify a table that contains multiple mapping options depending on the Source Field or to specify a custom Lua script to process and return a calculated value. For this example we use our "UNIT" Source Field and the corresponding "Unit Name" Target Field, and set the Field Processing to "Direct". Click Apply to confirm the changes.
This addition of the Unit Field Option also extends the Batch Record Data document by adding these fields to the Analytics node. Instigating the "One Shot" retrieval of the last Batch Record and then opening the Recent Data Field (Right-click on the field, then select Zoom and JSON Viewer in the dialog) you can see the entries in the Batch Record.
Product Options
The Product Options property compound allows the user to configure the Datasource to reclassify products to be either Main Products, Side Products or Waste Products. The different product types can be entered into the appropriate property Table, thus allowing for multiple products for each type to be specified.
Opening one of the table properties from the Object Properties panel, different products can be entered. If a Unit is involved in multiple process steps, the different main products from each step can be entered in the Main Products table.
The same is true for side and waste products from different steps. These can be entered in the Side Products and Waste Products tables respectively.
Once you have finished adding products to the tables, click OK to return to the Object Properties panel, then click Apply to save the configuration changes to the server.
| Care should be taken that the Batch Record Data Source is configured so that only one main product is present in each batch record. For any particular process step that contains multiple products, only one of these can be configured in the Main Products table, the rest should be added to either the Side Products or Waste Products tables. |
Timestamp Options
Timestamp Options apply to the entire Batch Record Datasource configuration. It is assumed that one external system has always one consistent way of reporting timestamps. These configuration options will be extended if future batch systems requiring the definition of multiple timestamp formats are added to the supported interfaces.
| When using the Batch Record Datasource in conjunction with Aspentech APRM or the PI-Bridge, you do not need to specify any Timestamp Options. The timestamp formats for such systems are known to the Batch Record Datasource, and as such the Timestamp Options are ignored. |
