OPP templating

As the OPP telegram specification becomes the standard for BCI IAS Services, it is expected from the stations to send their production data in this message format. However, legacy installations may not support this out of the box. In such cases, the gateway’s template-based OPP support can fill this gap. Templates can be added and modified without the need of code changes.

Template location

The template definitions are JSON files with a specific structure, stored in the following path in the binaries folder: "Payload\Opp\Templates"

Template structure and mapping options

Each template file contains the request and response definition of a single domain event and looks like the example provided below. The structure consists of four mandatory elements which are the following:

Template ID: This is an integer number that is used to uniquely identify the template in the template dictionary.
OPP specification version: Currently the following version monikers are recognized in the "version" property: V0_9, V1_0
Request template: The "request" block contains the template for the event request.
Response template: The "response" block would contain the template for the event response, if relevant.

{
  "1001": {
    "version": "V0_9",
    "request": {
      "spec": "https://bci.opp.com/schema/domains/shopfloor-management/error/group-of-parts-processed/v09",
      "type": "observation:shopfloor-management:group-of-parts-processed",
      "ts": "Variable|eventHeader.timeStamp|DateTime|format",
      "msgId": "Variable|eventHeader.eventId|String",
      "senderDetail": "Variable|LocationId,eventHeader.location.locationId|String",
      "content": {
        "partGroupInfo": {
          "resultDate": "Variable|eventHeader.timeStamp|DateTime|format",
          "typeNo": "Variable|workPart@typeNo|String",
          "processNo": "Constant|1|Int32",
          "typeVar": "Variable|resHead.TypeCurrent.TypeVar|String",
          "scalarArray": "Array|sample",
          "unmappedArray": "Array|flt",
          "mappedArray": [
            {
              "identifier": "Array|flt.DeviceNo|String",
              "nokBits": "Array|flt.FltNo|Int32",
              "resultState": "Array|flt.Text|Int32",
              "resultDate": "Array|flt.EntryDT|DateTime|format"
            }
          ]
        }
      }
    },
    "response": {
    }
  }
}

Example OPP template

Templating logic

The templating logic currently supports the following mapping options:

String constants: String constants can be simply added between double quotes. No special syntax is necessary.

Example:
```
"propertyName": "normal string value"
```
Non-string constants: To be able to convert the constant to the required type, the data type information is necessary. Thus, the following pattern should be used, where the logic would split the expression by the "|" characters and would use the first part "Constant" to identify the property type. The second part would be used as the value, and the third part would be used to convert the value to the expected type.

Example:
```
"propertyName": "Constant|1|Int32"
```
Simple variables: The simple variables use a similar approach as the constants, but here the first part of the expression contains the word "Variable", while the second part should contain the list of variable names as they could be found in the event description. The order of this alias list will be used when the variable is looked up in the event description. The first match will be returned and no further lookup will happen. In the following example, the logic would attempt to find "item.TypeNo" first, and if that failed, it would try looking up "workPart@typeNo".

Example:
```
"propertyName": "Variable|item.TypeNo,workPart@typeNo|String"
```
ResHead variables: In case of ResHead variables, the structure name also needs to be included with the variable name. Example:
```
"propertyName": "Variable|resHead.TypeCurrent.TypeVar|String"
```
Scalar arrays: The definition for scalar arrays requires only the word "Array" and the name of the scalar array variable as it can be found in the Event Description. In the example below, "sample" is the name of the array variable.

Example:
```
"propertyName": "Array|sample"
```
Non-mapped struct arrays: The logic supports the definition of non-mapped struct arrays, meaning the property names of the array items would match the array variable’s definition in the event description. So, in this case, only the name of the struct array variable needs to be provided, just like in the case of scalar arrays.

Example:
```
"propertyName": "Array|flt",
```
Mapped struct arrays: In case not everything is needed from the event description’s struct array variable, an array definition can be provided to the template which would describe how each item should be named in the generated telegram and which item to map to it from the source struct array.

Example:
```
"propertyName":
[
  {
    "identifier": "Array|flt.DeviceNo|String",
    "nokBits": "Array|flt.FltNo|Int32",
    "resultState": "Array|flt.Text|Int32",
    "resultDate": "Array|flt.EntryDT|DateTime|format"
  }
]
```

All of these mappings are supported inside nested objects as well.