Message Configuration

For an initial MSI connection between PAS-X and system:inmation, a Message Configuration object is not needed but as soon as data is exchanged, the Message Configuration object is required to send or receive messages.

Be aware that most of the properties of a Message Configuration are intended to specify an Order Parameter Message and especially the parameters involved, while other message types like Order Status Message only require a small amount of configuration.

The settings for each Message Configuration will be explained in the following section.

Message Configuration objects can be created below Message Processor and Message Broker objects in the I/O Model. To do this, right click on the parent object and select Admin New External Interfaces Message Configuration from the context menu to open the Create Object Wizard.

Figure 1. Message Configuration Properties

Apart from the mandatory Object Name and optional Object Description properties, the important properties are described below. These configure the header information of the message:

In the Common property compound:

Processing Mode - During these configuration steps, the Processing Mode should be kept in "Configuration" mode. When everything is fully configured and ready to start, the Processing Mode is set to "Operation". The other two modes are used for automatic generation of the configuration or generation of XML messages. Both of which will be explained later.

In the Communication Options property Compound:

Communication Mode - This property configures whether the message shall be sent from PAS-X to the system or Received by Pas-X. Be aware, that this definition can be perceived as counter intuitive, since it is defined from the PAS-X point of view, although it is configured in the system. In this example we have a message which is sent from PAS-X to inmation.

In the Message Description Properties property compound:

Message ID - This is the id of the message. This field is mandatory and is used within inmation to identify the message.
Supplier ID - this field defines the id of the supplier. This field is mandatory.
Device Type ID - this field defines the type of device in question. It is also mandatory.
Description - this gives a short, human-readable description of the message, which is optional.
Supplier Version - this field is intended to distinguish between several versions of a message configuration on the supplier side. It is optional, since message description are versioned within PAS-X independently.
System Name - this field holds the system name information and is optional.
Functional ID - this field provides a functional ID, which is also optional.

After these fields are configured, the header of an Order Parameter Message is defined.

The next thing to configure is the actual message content, also called “parameters” in the MSI realm. The parameters are defined within the Tag List table property, which can be opened from the object properties panel.

Figure 2. Message Configuration - Tag List Table Property

The column names and configuration options are detailed below:

Object Name: The object name defined the name of the parameter in the MSI message
Object Description: this is an optional field for further information on that object
Data Type: this defined the datatype of the parameter. With the Data Type automatic type conversion is managed by the system.
Direction: Is this a parameter which is sent from MES to Shopfloor, or is it sent from Shopfloor to MES.
MES Qualifier: this information is used in order to identify the correct EBR and Basic Function. This message belongs to the MES side. As the example shows a Send message, which is sent from MES to SF, this field does not have a meaning.
Shopfloor Qualifier: this field identifies, if the parameter is used as a qualifier, meaning it identifies e.g. the device to which the message shall be routed, or the process this message belongs to (in case, there are several processes running simultaneously on a device). Currently this parameter is not used by the system.
Range Low and Range High: These fields define the allowed range of values for this parameter. This only makes sense for numeric values.
UOM: Unit of Measure: this defines the unit of measure for the given parameter. The entries here should match the units of measure defined within the PAS-X MES system. There is no validity check on this text field.
Locked: This field is only used for automatic taglist generation and not needed if the taglist is configured manually (which is recommended)

A more complex message would look like the following screenshot. Here some parameters are only sent from MES to Shopfloor while others are sent from Shopfloor to MES and even others are bidirectional.

Figure 3. Message Configuration - Tag List Table More Complex

Here the BatchID is bidirectional and acts as the MES Qualifier, therefore it is important, that the same BatchID received from the MES is returned in the response message. Otherwise the message will not be assigned to the correct EBR and will probably return an error.

Mapping Data to Tags

The next thing to consider now, is how the received information shall be processed, or better, to which tags it should be mapped. Also, where information should be read from in, case we want to send a "receive" message.

There are several ways how the mapping can take place:

Direct Mapping - the simplest option, where parameters are mapped 1:1 to tags.
Group Mapping - A more complicated option, where one device out of a group of devices can be addressed
Custom Mapping - Here the mapping is performed by user defined Lua scripts.

This is defined in the Mapping Type property at the bottom of the Message Description Properties property compound.

Direct Mapping

Direct mapping is a simple form of mapping data from a MSI Message into the system. In this case, each parameter of a message is mapped to exactly one IO-Item. In order to use direct mapping, the Mapping Type has to be configured as "Direct"

Figure 4. Mapping Type - Direct

Open the Direct Mapping table property to configure the mapping. This table basically maps the Object Name to an Object Path. The Object name must be identical to the definition in the tag list, otherwise the mapping will fail and no messages will be sent or received.

Figure 5. Direct Mapping Table

It is also possible to define a property of an object in the I/O-Model as Source or Target of the information in an MSI message by using the appropriate property path.

Whenever a MSI message shall be sent to the MES System, the message processor must be notified to do so. In the case of the direct mapping, a Trigger Item is configured. Whenever this trigger item is true, a new message is generated and sent. After the message was generated, the Trigger Item is automatically reset to false. In the case of a bidirectional message, it is possible to automatically clear the trigger on reception of a new message, so that no overlapping communications can exist. This is activated with the configuration Trigger Auto Reset.

Whenever an MSI message shall be sent to the MES System, the message processor must be notified to do so. In the case of the direct mapping, a Trigger Item is configured. Whenever this trigger item is true, a new message is generated and sent. After the message was generated, the Trigger Item is automatically reset to false.

=== Group Mapping

Group mapping is used if there is a group of identical or exchangeable devices configured within the system. In order to qualify as 'exchangeable', the layout of the I/O Items (regarding MSI) must be identical, only the base path may differ (for example, they are located under a different connector).

In order to use group mapping, the Mapping Type has to be configured to "Group" which will change the available Options below.

First of all, the device which is to receive or send a message has to be identified. To do this, open the Device List table property.

Figure 6. Device List Table Property

The columns in the Device List table should be configured as follows:

DeviceName: Name of the device used in the message (if sent from MES to Shopfloor)
Device Path: this is the path of the device, all tags must be below this path
Trigger Item: This Trigger Item is checked and - if set to true - a message will be sent. After the generation of the message, the Trigger Item is reset automatically.

In the case of a bidirectional message, it is possible to automatically clear the trigger on reception of a new message, so that no overlapping communications can exist. This is activated with the configuration Trigger Auto Reset.

It is important that the name of a device sent from MES to Shopfloor must exactly match the DeviceName in this table, otherwise the Device will not be found and the message cannot be received correctly.

It is important that the name of a device sent from MES to Shopfloor matches the DeviceName in this table exactly, otherwise the device will not be found and the message can not be received correctly.

In addition to the list of the devices, it is important to configure how the parameters shall be mapped to the device in question. To do this, open the Group Mapping table property:

Figure 7. Group Mapping Table Property

ObjectName: name of the parameter in the TagList.
TagName: this is the second half of the path that will be addressed for that information. The full path is calculated as DevicePath .. "/" .. TagName. This allows for structured tag layouts, where tags are defined in the subfolder of the device folder.
DeviceSelector: this flag identifies which ObjectName shall be used as DeviceSelector; the first one found will be used. The content of the parameter defined by that ObjectName must match one of the DeviceNames in the Device List table!

Custom Script

The next mapping type is called 'custom script' and this mapping is completely done by custom scripts.

In order to use custom mapping, the Mapping Type needs to be set to "Custom" which will change the available Options below.

Figure 8. Mapping Type - Custom

There are two scripts, the first one being called the Input Script. This script shall return a function, which is executed whenever a message is received. The input parameter of this function is the content of the message in form of a Lua table. This script can return true or false.

A simple example of an input script like this:

local dataInPath = "/System/Core/integrationTest/MProC/DataIn"
local JSON = require('rapidjson')
local fun = function(content)
     local jsonData = JSON.encode(content)
     local res = syslib.setvalue(dataInPath, jsonData)
     return res
end
return fun

The second script is the Output Script. This script is executed every second to see if there is data available for sending. If no message shall be sent, this script needs to return nil. Otherwise it has to return the data matching the message configuration. An example of a simple output script, only returning data read from an IO-Item is:

local dataOutPath = "/System/Core/integrationTest/MProC/DataOut"
local JSON = require('rapidjson')
local fun = function(content)
       local jsonData = syslib.getvalue(dataOutPath)
       if jsonData then
             local data = JSON.decode(jsonData)
             syslib.setvalue(dataOutPath, "")
             return data
        else
               return
        end
end

The output table must be of the form:

{parameter=[{ name=ObjectName1, value=Value1},{name= ObjectName2, value=Value2}]}

Where "ObjectName1" and "ObjectName2" must match the object names defined in the Tag List table. Value1 and Value2 are the values assigned to these object names in the response. An example response would be:

{"parameter":[ {"name":"RecipeName","value":"Recipe1"},
               {"name":"OrderNumber","value":"orno_0101"},
               {"name":"MaterialName","value":"matname_0101"},
               {"name":"BatchID_basic","value":"Batch_b_01"},
               {"name":"MaterialNumber","value":"matno_0101"}
          ]}

Be aware that the content value1 and value2 must match the type defined in the Tag List table. This is automatically converted to string during XML encoding, which automatically complies with the interface definition of MSI Interface.

However, if problems should occur during this string conversion, the values can also be given as strings in the corresponding format.

E.g. Double being represented as "3.41" and bool being "true" or "false". In addition to the parameter section of the message, all other information needed to generate the message is taken from the configuration above. This includes qualifier information, MessageID etc.

Flexible Mapping

The flexible mapping is the first mapping type, which is use-case-specific and provides its own message format. The idea behind flex mapping is, that a MBR designer on MES level does not know anything about the internal structure of the system, but she or he wants to get the current values from a given device.

Figure 9. Configuration - Flexible Mapping

The flex mapping now does several things:

A message format is predefined. In order to activate this predefined format, select the operation mode "Update Taglist". This will create the required taglist and automatically switch back to the operation mode "Configuration" afterwards.
The mapping configuration includes a table, which automatically maps the combination of an EquipmentId and a Tag(name) to a path within the sysystem. EquipmentId and Tag should be configured according to the naming conventions within the MES system. The path can be configured to any item within the I/O-Model, the ISA95 Equipment Model or the KPI Model.

Figure 10. Tag List - Flexible Mapping

The mapping configuration is implemented as a configuration table and can be changed within data studio or imported from Excel. Exporting the configuration to Excel is also possible.

Figure 11. Mapping Table - Flexible Mapping

For performance reasons it is possible to request up to 50 different values within one message. In each message, the fields BatchId and EquipmentId must be filled. The fields Tag[1-50] are optional. In the response message, the Return[1-50] fields are filled according to the given Tag[1-50] fields. The data type of the Return fields is always string, and the values will be stringified prior to the transmission. Additional to the return values, a ReturnCode is provided, which indicates sucessfull, partly sucessfull or unsucessfull reads with the following return codes.

Code	Meaning
200 OK	execution was sucessfull.
206 Partial Content	data could not be read for all tags.
404 Not Found	EquipmentID missing.

Code

Meaning

200 OK

execution was sucessfull.

206 Partial Content

data could not be read for all tags.

404 Not Found

EquipmentID missing.

Historian Mapping

The historian mapping is the second mapping type, that is use case specific and provides it’s own message format. It’s main difference from the flexible mapping is, that not the current value is requested, but values or aggregates from a timerange in the past. The values can be read from the inmation internal historian or from an external historian. Currently only OSI-PI is available as external option.

Figure 12. Configuration - Historian Mapping

The historian mapping now does the following things:

A message format is predefined. In order to activate this predefined format, configure the operation mode "Update Taglist". This will create the required taglist and automatically switch back to the operation mode "Configuration" afterwards.
The mapping configuration includes a table, which automatically maps the combination of an EquipmentId and a tag(name) to a path and an historian type. The historian type defines whether the internal or an external historian is used. In oder to allow a successful mapping, each incoming message (request) must have a valid EquipmentId.
In the case of an external OSI-PI historian, the ip address and port of the PI-Bridge must be configured, as well as the name of the OSI-PI server.
A timeout for the historian request must be configured.

Figure 13. Tag List - Hisotrian Mapping

The mapping configuration is implemented as a configuration table and can be changed within DataStudio or imported from Excel. Exporting the configuration to Excel is also possible.

Figure 14. Mapping Table - Historian Mapping

The implemented message allows to query up to 50 different tags and it allows to specify the following Aggregation Methods for the data in the time range:

Method	Function
After	returns the value at the given path "after" StartDate
Average	returns the average value in the interval
Mean	returns the mean value of all measurements inside the interval
Before	returns the value before the interval
Interpolate	takes the nearest values ( before and after ) and linearly interpolates according to StartDate
Maximum	returns the maximum value in the interval
MaximumInside	returns the maximum value in the interval, without boundaries
Minimum	returns the minimum value in the interval
MinimumInside	returns the minimum value in the interval, without boundaries
Nearest	returns the value nearest to the StartDate of the interval
SingleValue	returns the a concatenated value composed of the single values in the interval

Method

Function

After

returns the value at the given path "after" StartDate

Average

returns the average value in the interval

Mean

returns the mean value of all measurements inside the interval

Before

returns the value before the interval

Interpolate

takes the nearest values ( before and after ) and linearly interpolates according to StartDate

Maximum

returns the maximum value in the interval

MaximumInside

returns the maximum value in the interval, without boundaries

Minimum

returns the minimum value in the interval

MinimumInside

returns the minimum value in the interval, without boundaries

Nearest

returns the value nearest to the StartDate of the interval

SingleValue

returns the a concatenated value composed of the single values in the interval

In each message, the fields BatchId, EquipmentId, StartDate and EndDate must be set. The BatchId as well as the EquipmentId are configured as "MES Qualifiers" and therefore identify the matching BO/BF and EBR within PAS-X. The StartDate and EndDate must be given according to the format "%d/%m/%Y %H:%M:%S". The fields Tag[1-50] and FuncParam[1-50] are optional, but for each given Tag the FuncParam must also be given. In the response message, the Return[1-50] fields are filled according to the matching Tag and FuncParam field.

The data type of the Return fields is always string, and the values will be stringified prior to the transmission. Additional to the return values, a ReturnCode is provided, which indicates sucessfull, partly sucessfull or unsucessfull reads with the following return codes.

Code	Meaning
200 OK	execution was sucessfull.
204 Not All Aggregates Defined	one or more agregate tags have invalid data.
206 Partial Content	data could not be read for all tags.
400 Bad Request	wrong timerange given.
404 Not Found	EquipmentID missing.

Code

Meaning

200 OK

execution was sucessfull.

204 Not All Aggregates Defined

one or more agregate tags have invalid data.

206 Partial Content

data could not be read for all tags.

400 Bad Request

wrong timerange given.

404 Not Found

EquipmentID missing.

The data type of the Return fields is always string and the values will be stringified prior to the transmission.

Different aggregates can be combined within a single message. It is possible, but not recommended to combine access to the internal historian and an external historian in a single message.

OSI-PI Connectivity

With the Historian Mapping it is not only possible to read data from the system’s own historian, but also from an OSI-PI historian. But the connection to the OSI-PI system has to be configured for this. First of all, a PIBridge must be installed on a connector of the system as described in the inmationPIBridge installation instructions. After the OSI-PI Bridge is installed, the required configurations have to be done within the Message Configuration, where the following fields must be configured:

Name	Description
Host Name or IP	the hostname or IP adresse, where the PIBridge service runs
Port	the TCP port for the PIBridge service
Timeout	the timeout for the PIBridge service
PI-Server	the name of the PI (DA) server

Name

Description

Host Name or IP

the hostname or IP adresse, where the PIBridge service runs

Port

the TCP port for the PIBridge service

Timeout

the timeout for the PIBridge service

PI-Server

the name of the PI (DA) server

The PI-Server must be configured on the machine where the inmationPIBridge runs.

Figure 15. OSI-PI Bridge - Historian Mapping

In order to access tags on the OSI-PI server, the tags have to be configured in the mapping table with the path, which is used by the OSI-PI server and the historian configured to OSI-PI. Be aware that a request to the OSI-PI system may take longer than an request to the system’s own historian, so please consider this for the choice of the timeout as well as for the size of the messages. It is not recommended to request system tags and osi-pi tags in the same message.

XML Generation

If we have configured a message successfully, following one of the possibilities described above, we still have to exchange the Message Configuration with the PAS-X MES system. Therefore a dedicated XML template is provided which is filled automatically by the system. If we switch the Processing Mode of the Message Configuration object to "Update XML-File" the XML Message Description is generated in the folder configured in the Message Broker object. In this generated Message Description (XML) the SystemID is taken from the Message Broker above the Message Configuration, while all other entries are generated from the settings within the Message Configuration.

The generated XML will be displayed in the Message Configuration object properties panel as follows:

Figure 16. Generated XML

XML File Location gives the full path of the generated Message Description XML. The XML Output can immediately be checked for consistency:

Figure 17. XML Output

The generated XML file has to be loaded into PAS-X in order to be usable within an MBR.

Message Configuration Generation

It is also possible to automatically generate the Tag List (in the case of a direct mapping) by configuring the Folder Settings table property.

Figure 18. Folder Settings

Each row of the table defines the path to a folder which shall be scanned for "Tags". By default all Tags are included in the folder and in subfolders. With Whitelist the Tags are limited to all Tags containing the given string in their name. Blacklist on the other hand excludes all Tags which contain the given string in their name. Whitelist and Blacklist are case sensitive.

In this example : "/System/Core/Batch Simulation/Machine1/Data" is included "/System/Core/Batch Simulation/Machine1/AbortData" is not included.

And additionally: "/System/Core/DemoItems/Setpoint 1" is included. "/System/Core/DemoItems/Setpoint Goods" is not included.

In order to generate a message configuration from the tags in the selected folder, switch the Processing Mode of the message configuration to "Update Taglist".

Since the Tags don’t carry any information regarding MES Identifiers or Shopfloor Identifiers, the generated Tag List will not have this information configured. Therefore it is advisable to check the generated configuration for completeness. The Direct Mapping is also created, but currently it is not updated, when the Tag List is updated.

Status Messages

The MSI interface is also capable of the generation of status messages. Since status messages are defined with a fixed layout by the MSI standard, a Message Description (XML) is not needed and only the content has to be configured. The only content of as status message is the status text. This text can either be predefined or be read from an path within the system. If no path is given or the path is not readable, the predefined status will be used. The status message is sent whenever the Trigger Item is set to true or a triggering script returns true. If the message was triggered by a Trigger Item, this item will be reset to false when the message has been generated. The Message Name is for documentation purposes only.

Figure 19. Status Message

Abort Messages

The MSI interface is also capable of generatng abort messages. Since status messages are defined by the MSI standard with a fixed layout, no Message Description (XML) is needed and only the content has to be configured. The content of as status message only consists of the ErrorCode an the ErrorTest. Both can either be predefined or read from a path within the system. The predefined ErrorCode and ErrorText are used if no associated path is given or if this path is not readable. The abort message is sent whenever the Trigger Item is set to true or the triggering script returns true. If the message was triggered by a Trigger Item, this item will be reset to false when the message has been generated. The Message Name is for documentation purpose only.

Figure 20. Abort Message

Another mechanism which triggers an abort message is the timeout of a bidirectional Order Parameter Message. In this case an abort message is sent, too, but with the ErrorCode and ErrorText being defined in the timeout options.

Figure 21. Timeout Message

Exception Messages

The MSI interface is also capable of generating exception messages. The layout of the exception message is predefined by the MSI standard and needs no further configuration. However, the exceptions within the exception message need to be created. Since many exceptions can occur during a short amount of time, the exceptions are not being read from tags but from a message queue. The ID of this message queue is predefined, but the object, to which this message queue is attached, can be configured in the Message Configuration.

Figure 22. Exception Message

In this example a Message Processor is configured as the exception provider and exceptions are being read from a message queue attached to the Message Processor. The following Lua code shows how exceptions can be created and placed in the message queue of the exception provider:

local msi = require('mbro-msi')
local exProviderObj = syslib.getobject("/System/Core/MSIMessageBroker/MSIMessageProcessor")
local exProviderId = exProviderObj:numid()
local ex_queue_id = syslib.msgqueue(exProviderId, msi.EXCEPTION_SLOT)

local exception = JSON.encode({
                        causedAt = "2020-11-28 12:20:00,000",
                        systemDescription = "inmation test system",
                        userDescription= "Exception",
                        exceptionComment = {{changeDate="2020-11-28 12:30:00,000",
                                            commentText="WTF",
                                            user= "me"
                                          },
                                          {changeDate="2020-11-28 12:40:00,000",
                                            commentText="Found it",
                                            user= "me"
                                          }
                                        }
    })
syslib.msgpush(ex_queue_id, exception)