OpcenterEXFN UserManual

Opcenter Execution Foundation 4.
User Manual
07/2021
PL20210506303162726
Guidelines
This manual contains notes of varying importance that should be read with care; i.e.:
Important:
Highlights key information on handling the product, the product itself or to a particular part of the documentation.
Note: Provides supplementary information regarding handling the product, the product itself or a specific part of
the documentation.
Trademarks
All names identified by ® are registered trademarks of Siemens AG.
The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes
could violate the rights of the owner.
Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and software
described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the
information in this publication is reviewed regularly and any necessary corrections are included in subsequent
editions.
Security information
Siemens provides products and solutions with industrial security functions that support the secure operation of
plants, systems, machines and networks. In order to protect plants, systems, machines and networks against
cyber threats, it is necessary to implement – and continuously maintain – a holistic, state-of-the-art industrial
security concept. Siemens’ products and solutions only form one element of such a concept.
Customer is responsible to prevent unauthorized access to its plants, systems, machines and networks. Systems,
machines and components should only be connected to the enterprise network or the internet if and to the extent
necessary and with appropriate security measures (e.g. use of firewalls and network segmentation) in place.
Additionally, Siemens’ guidance on appropriate security measures should be taken into account. For more
information about industrial security, please visit https://www.siemens.com/industrialsecurity.
Siemens’ products and solutions undergo continuous development to make them more secure. Siemens strongly
recommends to apply product updates as soon as available and to always use the latest product versions. Use of
product versions that are no longer supported, and failure to apply latest updates may increase customer’s
exposure to cyber threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS Feed under https://
www.siemens.com/industrialsecurity.
Siemens AG PL20210506303162726 Copyright © Siemens AG 2021

Digital Industries 20210719_115957 Technical data subject to change
Postfach 48 48
90026 NÜRNBERG
GERMANY
Table of Contents
1 Opcenter Execution Foundation App Overview ..............................................11
1.1 UI Common Functionalities................................................................................................... 13
1.2 Home Cards and Navigation.................................................................................................. 15
2 System Apps ......................................................................................................19
2.1 Application Log App............................................................................................................... 19
2.1.1 What is Application Log?...................................................................................................................................... 19
2.1.2 Viewing Application Log Messages...................................................................................................................... 21
2.1.2.1 Prerequisites ........................................................................................................................................................ 21
2.1.3 Application Log Maintenance.............................................................................................................................. 22
2.1.3.1 Configuring Maintenance Rule ............................................................................................................................ 23
2.2 APS Interface App................................................................................................................... 30
2.2.1 Views Related to the APS Interface App.............................................................................................................. 32
2.2.2 Quick Customization Related to the Views of the APS Interface App................................................................ 38
2.3 Audit Trail App........................................................................................................................ 38
2.3.1 Audit Trail ............................................................................................................................................................. 39
2.3.1.1 What is an Audit Trail Configuration? ................................................................................................................. 39
2.3.1.2 How To Enable the Audit Trail Configuration..................................................................................................... 40
2.3.1.3 How To Display Audit Trails in the Audit Trail App UI Screens .......................................................................... 43
2.3.1.4 How To Integrate Audit Trail for Custom Implementations .............................................................................. 45
2.3.2 Electronic Signature ............................................................................................................................................ 56
2.3.2.1 What is an Electronic Signature Scenario? ......................................................................................................... 56
2.3.2.2 Creating an Electronic Signature Scenario......................................................................................................... 57
2.4 Automation App ..................................................................................................................... 59
2.4.1 What Is the Automation Gateway? ...................................................................................................................... 59
2.4.2 What Are Automation Entities? ........................................................................................................................... 60
2.4.3 What Is the Lifecycle of the Automation Entities................................................................................................ 62
2.4.4 What is the Automation Gateway Redundancy Support?.................................................................................. 62
2.4.5 How to Manage Automation Nodes .................................................................................................................... 63
2.4.5.1 Configuring Automation Channels...................................................................................................................... 63
2.4.5.2 Configuring Automation Node Types and their Automation Parameters......................................................... 69
2.4.5.3 Configuring Automation Node Instances and Their Automation Parameters.................................................. 75
2.4.5.4 Activating Runtime Integration ........................................................................................................................... 83
2.4.5.5 Exporting Automation Node Master Data........................................................................................................... 85
2.4.5.6 Importing Automation Node Master Data for Automation Artifacts ................................................................. 85
Opcenter Execution Foundation 4.2 - User Manual iii

2.4.5.7 Migrating Automation Node Master Data ........................................................................................................... 90
2.4.5.8 Resetting the Automation Gateway Server environment .................................................................................. 91
2.4.5.9 Reverting the Automation Gateway Configuration............................................................................................ 91
2.4.5.10 Viewing and Modifying Automation Node Values at Runtime ........................................................................... 92
2.4.6 How to Monitor Automation Gateway Server..................................................................................................... 94
2.4.6.1 Monitoring Automation Nodes with AGW Node Monitor ................................................................................... 94
2.4.6.2 Exporting the Automation Node Configuration ................................................................................................. 98
2.4.6.3 How to Monitor Automation Gateway Server Runtime Traces.......................................................................... 99
2.5 Data Segregation App .......................................................................................................... 101
2.5.1 What is Data Segregation?................................................................................................................................. 101
2.5.2 Which Users and Entity Instances are involved in Data Segregation .............................................................. 102
2.5.3 Quick Start to Using Data Segregation ............................................................................................................. 104
2.5.4 How Data Segregation works at runtime.......................................................................................................... 106
2.5.4.1 Performing queries on runtime data ................................................................................................................ 107
2.5.5 What Data Segregation is Applied to ................................................................................................................ 107
2.5.6 How to Manage Segregation Tags..................................................................................................................... 110
2.5.6.1 Creating Segregation Tags ................................................................................................................................ 111
2.5.6.2 Assigning Segregation Tags to Entity Instances in Apps using Default Values ............................................... 111
2.5.6.3 Modifying the List of Segregation Tags Assigned to Entity Instances ............................................................. 113
2.5.6.4 Displaying Segregation Tag Logs ...................................................................................................................... 114
2.5.7 How to Use Data Segregation in Custom and Third-Party Integration Apps .................................................. 114
2.5.7.1 Handling Persons or Resources with Custom Apps ......................................................................................... 115
2.5.7.2 How to Implement Data Segregation in Third-Party Integration Apps/Functional Blocks............................ 116
2.5.7.3 Logging Operations on Data Segregation Tags ................................................................................................ 120
2.6 Signals App ........................................................................................................................... 121
2.6.1 What Are Signal Rules?....................................................................................................................................... 121
2.6.2 Predefined User Roles for Signal Rules ............................................................................................................. 123
2.6.3 Signal Rule Configuration and Runtime States ................................................................................................ 123
2.6.4 Signal Rule Supported Data Types.................................................................................................................... 126
2.6.5 How to Manage Signals Rules............................................................................................................................ 127
2.6.5.1 Creating Signal Rules ......................................................................................................................................... 128
2.6.5.2 Configuring Signal Rules.................................................................................................................................... 130
2.6.5.3 Executing Signal Rules....................................................................................................................................... 144
2.7 System App........................................................................................................................... 152
3 Manufacturing Apps........................................................................................153
3.1 Barcode App ......................................................................................................................... 153
iv Opcenter Execution Foundation 4.2 - User Manual

3.1.1 What are Barcode Rules? ................................................................................................................................... 153
3.1.2 What is the Barcode Service? ............................................................................................................................ 153
3.1.3 How to Manage Barcode Rules and Rule Parts................................................................................................. 154
3.1.3.1 Creating Barcode Rules ..................................................................................................................................... 155
3.1.3.2 Adding Rule Parts............................................................................................................................................... 155
3.1.3.3 Viewing Barcode History.................................................................................................................................... 157
3.1.3.4 Exporting and Importing Barcode Rules Data .................................................................................................. 157
3.1.4 How to Manage Barcode Parser ........................................................................................................................ 158
3.1.4.1 How to Include the Barcode Parser in a User Interface ................................................................................... 158
3.1.4.2 Configuring the Barcode Parser ........................................................................................................................ 162
3.2 Defect App ............................................................................................................................ 164
3.2.1 What are Failures and Quality Actions? ............................................................................................................ 164
3.2.2 How to Migrate existing Failures to the Defect App ......................................................................................... 165
3.2.3 How to Manage Failures and Quality Actions ................................................................................................... 166
3.2.3.1 Creating Failures ................................................................................................................................................ 168
3.2.3.2 Creating Sub-Failures ........................................................................................................................................ 168
3.2.3.3 Creating Quality Actions .................................................................................................................................... 169
3.2.3.4 Creating Quality Sub-Actions ............................................................................................................................ 169
3.2.3.5 Creating Attachments ........................................................................................................................................ 170
3.2.3.6 Assigning Failures and Sub-Failures to Quality Actions................................................................................... 171
3.2.3.7 Assigning Attachments to Failures.................................................................................................................... 171
3.2.3.8 Exporting and Importing Defect Data ............................................................................................................... 171
3.3 Equipment App .................................................................................................................... 173
3.3.1 What is Equipment? ........................................................................................................................................... 173
3.3.2 What is the Connection between Equipment and Automation Gateway ....................................................... 174
3.3.3 How to Configure the Plant ............................................................................................................................... 175
3.3.3.1 Defining Equipment Levels................................................................................................................................ 176
3.3.3.2 How to Define Equipment Types....................................................................................................................... 179
3.3.3.3 How to Define Equipment Configurations........................................................................................................ 182
3.3.3.4 How to Define Equipment Group Configurations............................................................................................. 187
3.3.3.5 How to Define Connections among Equipment Items..................................................................................... 189
3.3.3.6 How to Define the Physical Model of the Plant................................................................................................. 191
3.3.3.7 Exporting and Importing Equipment Data ....................................................................................................... 197
3.3.3.8 How to Configure the Association between Equipment and Automation Gateway ...................................... 200
3.3.4 How to Manage Equipment in the Runtime Environment ............................................................................... 202
3.3.4.1 Modifying the Status of Equipment State Machine.......................................................................................... 203
Opcenter Execution Foundation 4.2 - User Manual v

3.3.4.2 Modifying Equipment Property Values ............................................................................................................. 203
3.3.4.3 Modifying Attributes of Equipment Properties................................................................................................. 204
3.3.4.4 Manually Synchronizing Engineering and Runtime Environments ................................................................. 204
3.4 Label App.............................................................................................................................. 204
3.4.1 What is Label Management?.............................................................................................................................. 205
3.4.2 How to Configure Label Printing ....................................................................................................................... 205
3.4.2.1 How to Configure the Label Print Layout.......................................................................................................... 206
3.4.2.2 How to Configure Label Types........................................................................................................................... 207
3.4.2.3 How to Configure Printers ................................................................................................................................. 213
3.4.2.4 How to Raise Print Requests ............................................................................................................................. 217
3.4.3 How to Retrigger Print Requests ....................................................................................................................... 220
3.4.4 Exporting and Importing Label Type and Printer Data .................................................................................... 222
3.5 Material App ......................................................................................................................... 223
3.5.1 What is Material Management? ......................................................................................................................... 223
3.5.2 What are Material App Properties?.................................................................................................................... 223
3.5.3 How to Manage Engineering Materials ............................................................................................................. 225
3.5.3.1 Configuring Material Templates........................................................................................................................ 225
3.5.3.2 Configuring Material Groups ............................................................................................................................. 227
3.5.3.3 Configuring Materials......................................................................................................................................... 230
3.5.3.4 Exporting and Importing Material Data ............................................................................................................ 232
3.5.4 How to Manage Runtime Materials ................................................................................................................... 234
3.5.4.1 Configuring Material Lot Templates ................................................................................................................. 234
3.5.4.2 Configuring Material Lots .................................................................................................................................. 236
3.5.4.3 Configuring Material Tracking Unit Templates ................................................................................................ 241
3.5.4.4 Configuring Material Tracking Units ................................................................................................................. 243
3.5.4.5 Configuring Material Tracking Unit Aggregate Templates............................................................................... 247
3.5.4.6 Configuring Material Tracking Unit Aggregates ............................................................................................... 249
3.6 Personnel App ...................................................................................................................... 254
3.6.1 What is Personnel Management? ...................................................................................................................... 255
3.6.2 How To Manage Persons.................................................................................................................................... 256
3.6.2.1 Creating a Person............................................................................................................................................... 257
3.6.2.2 Assigning Segregation Tags to Persons ............................................................................................................ 260
3.6.2.3 Modifying Persons.............................................................................................................................................. 261
3.6.2.4 Deleting Persons ................................................................................................................................................ 262
3.6.3 How to Manage Person Groups ......................................................................................................................... 262
3.6.3.1 Creating a Person Group.................................................................................................................................... 263
vi Opcenter Execution Foundation 4.2 - User Manual

3.6.3.2 Assigning Persons to Person Groups................................................................................................................. 264
3.6.3.3 Assigning Segregation Tags to Person Groups ................................................................................................. 264
3.6.3.4 Modifying Person Groups .................................................................................................................................. 265
3.6.3.5 Deleting Person Groups ..................................................................................................................................... 266
3.6.4 Exporting and Importing Personnel Data ......................................................................................................... 266
3.7 Reference App ...................................................................................................................... 267
3.7.1 How to Manage UoMs ........................................................................................................................................ 267
3.7.1.1 Configuring UoM Dimensions............................................................................................................................ 268
3.7.1.2 Configuring UoMs............................................................................................................................................... 271
3.7.1.3 Exporting and Importing UoM Data .................................................................................................................. 275
3.7.2 How to Manage Entity Lifecycles with State Machines .................................................................................... 276
3.7.2.1 Configuring Status Definitions .......................................................................................................................... 277
3.7.2.2 Configuring Statuses.......................................................................................................................................... 279
3.7.2.3 Configuring Status Transition Definitions ........................................................................................................ 280
3.7.2.4 Configuring Status Behavior Definitions .......................................................................................................... 281
3.7.2.5 Configuring State Machines............................................................................................................................... 282
3.7.2.6 Exporting and Importing Entity Life Cycle and State Machine Data ............................................................... 286
3.7.3 How to Manage Autonumbering ....................................................................................................................... 287
3.7.3.1 Configuring Counters......................................................................................................................................... 288
3.7.3.2 Configuring Numbering Patterns ...................................................................................................................... 291
3.7.3.3 Configuring Autonumbering for Custom Entities............................................................................................. 297
3.7.3.4 Exporting and Importing Autonumbering Configuration Data........................................................................ 303
4 Process Apps ...................................................................................................304

4.1 Business Process Flow App.................................................................................................. 304
4.1.1 What are Business Process Flows? .................................................................................................................... 304
4.1.2 How to Manage Process Definitions.................................................................................................................. 305
4.1.2.1 Creating Process Templates.............................................................................................................................. 305
4.1.2.2 Creating Process Definitions ............................................................................................................................. 308
4.1.2.3 Creating Process Definition Models .................................................................................................................. 327
4.1.2.4 Exporting and Importing Process Definition Data............................................................................................ 350
4.1.3 How to Manage Work Processes ....................................................................................................................... 351
4.1.3.1 Creating and Executing Work Processes........................................................................................................... 352
4.1.3.2 Configuring Signal Rules with Start New Work Process Action ....................................................................... 353
4.1.3.3 Applying Filters to the Work Process List.......................................................................................................... 354
4.1.3.4 Monitoring Work Processes ............................................................................................................................... 354
4.1.3.5 Modifying the Status of a Work Process............................................................................................................ 359
Opcenter Execution Foundation 4.2 - User Manual vii

4.2 Task App ............................................................................................................................... 362
4.2.1 What Are Tasks? ................................................................................................................................................. 363
4.2.2 How to Engineer Tasks ...................................................................................................................................... 365
4.2.2.1 Creating Task Definitions................................................................................................................................... 366
4.2.2.2 Adding Task Definition Parameters .................................................................................................................. 368
4.2.2.3 Creating a New Revision of a Task Definition ................................................................................................... 369
4.2.2.4 How to Define Task Context Definitions ........................................................................................................... 369
4.2.2.5 Setting a Task Definition Revision to Current................................................................................................... 381
4.2.2.6 Exporting and Importing Task Data .................................................................................................................. 381
4.2.3 How to Manage Tasks at Runtime..................................................................................................................... 382
4.2.3.1 Creating Tasks .................................................................................................................................................... 383
4.2.3.2 Modifying Tasks and Task Parameters ............................................................................................................. 385
4.2.3.3 Managing Task States ........................................................................................................................................ 387
4.2.3.4 Repeating Tasks ................................................................................................................................................. 389
4.2.3.5 Applying Filters to Task Administration............................................................................................................ 389
4.2.4 How to Customize Task Management .............................................................................................................. 390
4.2.4.1 Creating Custom Task Types and Task Definitions .......................................................................................... 390
4.2.4.2 Creating Custom User Interfaces for Task Management ................................................................................. 392
4.2.4.3 Configuring the Task List View Component...................................................................................................... 393
4.2.4.4 Configuring the Task Info Component.............................................................................................................. 396
4.3 Work Instruction App ........................................................................................................... 397
4.3.1 Work Instruction................................................................................................................................................. 398
4.3.1.1 What are Work Instructions? ............................................................................................................................. 398
4.3.1.2 How to Manage Work Instruction Definitions................................................................................................... 398
4.3.1.3 How to Manage Work Instructions .................................................................................................................... 423
4.3.1.4 How to Promote a Work Instruction Definition to Task Definition.................................................................. 426
4.3.2 Quality Execution ............................................................................................................................................... 430
4.3.2.1 What is Quality Execution? ................................................................................................................................ 431
4.3.2.2 How to Configure Quality Execution ................................................................................................................. 432
4.3.2.3 How to Integrate and Use Quality Execution.................................................................................................... 448
5 How To Export and Import Data.....................................................................465

5.1 Exporting Data from the Runtime Database....................................................................... 465
5.2 Modifying the Exported Data............................................................................................... 467
5.3 Importing Data to the Runtime Database........................................................................... 475
5.4 Deleting Export Import Operation Data from the System Database................................. 478
viii Opcenter Execution Foundation 4.2 - User Manual

6 How To Manage Time To Live for Client Cache .............................................480
Opcenter Execution Foundation 4.2 - User Manual ix

ID OpcenterEXFN_UserManual
Title User Manual
Product Title Opcenter Execution Foundation
Version Title 4.2
Product Version OpcenterEXFN_4.2.0.0
Category Runtime
Summary Provides detailed information on how to use the Opcenter Execution

Foundation web user interface
Audience Operator, Supervisor, Support Engineer
Revision PL20210506303162726
State Published
Author Siemens AG
Language en-US
10 Opcenter Execution Foundation 4.2 - User Manual

Opcenter Execution Foundation App Overview
1 Opcenter Execution Foundation App Overview

Opcenter Execution Foundation® (Opcenter EX FN) can be installed with various Apps, which are identified by the
Foundation Apps option within the product setup.
This option installs all the predefined Opcenter EX FN Functional Blocks, the Opcenter EX FN Apps and Extension
Apps, which can be functionally grouped as follows (listed alphabetically):
• System Apps
• Application Log App
• APS Interface App
• Audit Trail App
• Automation App
• Data Segregation App
• Signals App
• System App
• Manufacturing Apps
• Barcode App
• Defect App (with QEMigration Extension App)
• Equipment App (with OPCUAConnect Extension App)
• Label App
• Material App
• Personnel App
• Reference App
• Process Apps
• BPFlow App
• Task App
• Work Instruction App (with WITask Extension App)
What are Opcenter EX FN Apps

Opcenter EX FN provides a set of Apps that make the data model available on the Opcenter EX FN Service Layer and
provides a set of predefined web pages for managing predefined data models.
If you have extended the data model by developing custom Functional Blocks, you can develop new custom Apps to
meet business requirements as described in the Opcenter Execution Foundation Development and Configuration
Guide.
If the Foundation Apps option has been selected during the product installation, the following Apps are provided
within zip files in %ProgramData%Siemens\SimaticIT\Unified\Engineering\Packages\Projects.
In Solution Studio, during the Solution configuration, you can select and install the following Apps:
App Name Topic Referenced Functional Blocks
Application Log Application Logs related to • Siemens.SimaticIT.ALG_MS

installed Apps, Functional • Siemens.SimaticIT.ALG_OP
Blocks and Extension Apps
Audit Trail Audit Trail and Electronic • Siemens.SimaticIT.ES_SD

Signature • Siemens.SimaticIT.UDM_RF
• Siemens.SimaticIT.ES_MS
Opcenter Execution Foundation 4.2 - User Manual 11

Automation Automation Gateway • Siemens.SimaticIT.ATN_MS

• Siemens.SimaticIT.ATN_OP
• Siemens.SimaticIT.UDM_RF
• Siemens.SimaticIT.AGW_MS
Barcode Barcode Rules Management • Siemens.OpcenterEX.FN.BRC_MS

• Siemens.OpcenterEX.FN.BRC_OP
BPFlow • Business Process Flows • Siemens.SimaticIT.BPF_MS

• Work Processes • Siemens.SimaticIT.BPF_OP
• Siemens.SimaticIT.TSK_MS
• Siemens.SimaticIT.TSK_OP
• Siemens.SimaticIT.EQU_MS
• Siemens.SimaticIT.EQU_OP
Data Segregation Data Segregation • Siemens.SimaticIT.DSG_SD
Defect Failure and Quality Action • Siemens.OpcenterEX.FN.DEF_MS

Management • Siemens.SimaticIT.UDM_RF
Equipment Equipment • Siemens.SimaticIT.UDM_RF

Label Label Management • Siemens.SimaticIT.LBM_MS

• Siemens.SimaticIT.LBM_OP
Material • Material Templates • Siemens.SimaticIT.MAT_MS

• Material Groups • Siemens.SimaticIT.MAT_OP
• Materials • Siemens.SimaticIT.UDM_RF
OPCUAConnect Connection between • Siemens.SimaticIT.OPCUAConnect_MS

Equipment and shop-floor • Siemens.SimaticIT.OPCUAConnect_OP
(Extension of
devices via Automation
Equipment App)
Gateway
Personnel Personnel and users • Siemens.SimaticIT.PRM_MS

• Siemens.SimaticIT.DSG_SD
QEMigration Migration of existing Failures • Siemens.OpcenterEX.FN.QEMigration_MS

from Work Instruction App • Siemens.OpcenterEX.FN.DEF_MS
(Extension of Defect
to Defect App • Siemens.SimaticIT.CHR_MS
App)

UI Common Functionalities
Reference • Units of Measure • Siemens.SimaticIT.UDM_RF

• State Machines
Signals Signals • Siemens.SimaticIT.SGN_MS

• Siemens.SimaticIT.SGN_SD
System Manages base entities and • Siemens.SimaticIT.SITUASys

functionalities
Task Tasks • Siemens.SimaticIT.UDM_RF

WITask Management of Task • Siemens.SimaticIT.EQU_MS

Definitions and Task • Siemens.SimaticIT.EQU_OP
(Extension of Work
Instances of Work • Siemens.SimaticIT.ES_MS
Instruction App)
Instruction Task type. • Siemens.SimaticIT.ES_SD
• Siemens.SimaticIT.WI_MS
• Siemens.SimaticIT.WI_OP
• Siemens.SimaticIT.WI_TSK_MS
• Siemens.SimaticIT.WI_TSK_OP
• Siemens.SimaticIT.CHR_MS
• Siemens.SimaticIT.CHR_OP
Work Instruction • Work Instructions • Siemens.SimaticIT.UDM_RF

• Quality Execution • Siemens.SimaticIT.WI_MS
• Siemens.SimaticIT.WI_OP
• Siemens.SimaticIT.ES_SD
• Siemens.SimaticIT.ES_MS
• Siemens.SimaticIT.CHR_MS
• Siemens.SimaticIT.CHR_OP
Since Apps are autonomous and self-contained applications, each App can be potentially installed independently of
the others, but if you do so bear in mind that not all required web pages may be available (for example, if you install
the Task App without selecting the Reference App, the web pages for entering State Machines will not be available,
unless you have developed and installed your own custom App).
1.1 UI Common Functionalities

Opcenter EX FN UI Screens provide the following common functionalities.

UI Common Functionalities
Function Icon Description
Filter To specify filtering criteria on the displayed fields.
Mode To select the required display style, which can be either Table or
List.
Sort By To select a field you want to sort by, in ascending or descending

order.
Group By To group the items by a desired field.
Search by Id To find a specific item.
Segregation The icon is displayed after selecting an entity instance. It allows

Tags you to modify the list of segregation tags previously created and
assigned to entity instances.
User To customize the current view by setting user preferences. You can
Preference choose column visibility, column order or tile property visibility
and the applied settings will be saved as default for the logged on
user.
Download To download the records that are listed in the table in the csv file
as csv format.
Back To move back to the previous screen.
Help To view the help content related to the current screen. The icon is
always visible and behaves differently according to the following
circumstances:
• If either the help code or the page title is available along with
documentation, the system will display a modal popup with
help documentation.
• If either the help code or the page title is available but there is
no documentation loaded in the Documentation Center, the
system will display a warning popup with the following
message: No help available for <TITLE>.
• If either the help code or the page title is not available and
there is no documentation loaded in the Documentation
Center, the system will display a warning popup with the
following message: No help available.

Home Cards and Navigation
Function Icon Description
Select All To select all the rows when the display Mode is Table.
While Select All checkbox is selected, rows that would be newly
added and the rows that are loaded by scrolling in server side
pagination will be selected automatically.
 This is the default setting. To implement the behavior, you

must remove any custom settings if available with respect
to the selecting records.
Refresh To Refresh the UI application.

If there are any modification for the UI application from Solution
Studio, then the cached content will be discarded and will be
replaced with the new files fetched from the server.
 A convention on field names is applied for which in most of the screens the Id field corresponds to
the NId table property.
While selecting text from a row, selection of the row will be toggled. If text is long and some part of the text
is replaced by an ellipsis, respective column must be expanded to select hidden text.
1.2 Home Cards and Navigation

While configuring the UI Application you can choose how to navigate at runtime to the UI Screens included in the UI
Application.
The UI Screens included in the UI Application can be accessed through the navigation sidebar, which is placed on
the left of the screens, as described in the procedures contained in the current manual.
The sidebar can be either category-based or parent module-based.
Moreover, you can also enable the home cards navigation. With this configuration, you can access UI screens
starting from a home card. You can choose one of the following home page types:
• Single page, listing all home cards and the associated screen's home tile in the same page.
• Multi page, listing only the home cards. When clicking on a home card, the associated screens are displayed.
• Custom, displaying a dedicated screen set as home page.
You can use the following options to configure the Home Page of a Runtime UI Application and the Sidebar
navigation menu.
While configuring the UI Application, you can choose one of the following runtime navigation modes, which either
present cards and tiles on the Home page or offer navigation menus on the side.
Home Page - Single Page with Quick Search option

This option allows you to visualize the landing page of the UI application as a single page with quick search
functionality.
All the configured home cards will be available in the landing page.

When you click on a home card, the configured home tiles will be displayed in the same page by means of an in-
page scroll-down action.
The navigation menu will be based on the categories and the quick search will be configured to search by home
tiles.
Home Page - Multi Page option

This option allows you to visualize the landing page of the UI application as a multi page.
All the configured home cards will be available in the landing page.
When you click on a home card, the configured home tiles will be displayed in another page and the navigation
menu will be based either on the included UI Modules or on the custom folders.
Home Page - Custom option

This option allows you to visualize the landing page of the UI application with a custom configuration.
The landing page will be one of the screens that you will select from the assigned modules.

As far as the sidebar navigation is concerned, Home card based categorization will not be applicable with this
option and the navigation menu will be based either on the included UI Modules or on the custom folders.
Navigation Sidebar Menu - Per Top Menu

This option allows you to visualize the navigation menu at runtime according to the configured categories (Home
Cards).
Navigation Sidebar Menu - Per Menu Item

This option allows you to visualize the navigation menu at runtime according to the associated UI Modules or
custom folders.

For more information on the available cards and on how to configure the home page, see Creating a UI Application
in the Opcenter Execution Foundation Development and Configuration Guide.
Multi language support

The contents of the home page and the navigation sidebar can be translated in any of the supported languages
based on the language you select during the login.
The translation is retrieved from the resource key mentioned in the header property, which can be added in Project
Studio or in the Model-Driven UI Editor .
If you update the title for any Screen or Module in Solution Studio, then this title has the priority and it will not be
translated into different languages at runtime.
This multi language support for Screens and Modules is supported only for Standard and Model-Driven Modules and
Screens. Mashup Modules and Screens will not be considered for title translation at runtime.

System Apps
Application Log App
2 System Apps
The Opcenter EX FN System Apps are:
• Application Log App
• APS Interface App
• Audit Trail App
• Automation App
• Data Segregation App
• Signals App
• System App
2.1 Application Log App

The Application Log App provides the functionality to log and view application messages such as Errors/Warnings
etc for any Functional Block/App/Extension App in runtime environment. The messages work as an evidence of all
the operations that have been carried out on a specific entity during the execution of manufacturing commands.
The Application Log App references the ALG_MS and ALG_OP Functional Blocks. For detailed information on the
artifacts contained in this Functional Block, see the Reference Documentation of the respective Functional Block.
For a general understanding of Functional Blocks, refer to Overview of Functional Blocks section of the Opcenter
Execution Foundation Development and Configuration Guide.
What can I do with the Application Log App?

• Useful conceptual information and the functionality in a nutshell is provided in What is Application Log?
• Procedural information regarding how to view logged application messages is provided in How to View
Application Log Messages?
• Procedural information regarding how to maintain application log messages is provided in How to configure
Application Log for maintenance?
2.1.1 What is Application Log?

The Application Log provides a mechanism for analyzing the system behavior during the execution of
manufacturing commands, through relevant application messages. The messages serve as an evidence of all the
operations that have been carried out on a specific entity.
Each Functional Block, App or Extension App can be packaged with an xml file (whose structure is system-defined),
containing the definition of all the relevant application messages. The system integrator refers the defined
messages inside command handlers of a model project by means of platform APIs and events, for displaying in
runtime environment.
The messages defined in the xml file can be Informational, Verbose, Warning, Error or Critical.
The default language configuration for Application Log messages is English. However, you can define the messages
in multiple languages depending on your locale. The system supports Chinese, French and German languages.
Application Log configuration workflow

In Project Studio:
1. Add the application log xml file to the installer project.
2. Refer the defined messages using Message ID in command handlers through ApplicationLog platform API.
3. Define application log messages in the xml file.
4. Build Installer project to package the xml file.

System Apps
Application Log App
For more information, see How To Manage Application Logs in Opcenter Execution Foundation Development and
Configuration Guide.
In Solution Studio:
1. Build and deploy the solution, then update the database to store packaged messages in the engineering
repository.
2. Install the Application Log App and associate its UI modules.
For more information on Solution Studio deploy procedures, see How to Deploy a Manufacturing Solution in
Opcenter Execution Foundation Development and Configuration Guide.
In the UI Application, access the Application Log page to view the logged messages.
Differences between Application Log and Trace Viewer

To trace logs you can also use Trace Viewer. There are differences between the two logging applications. Take a
look at them in a glance before choosing the most suitable way.
Trace Viewer Application Log Description
Traces all actions Traces only application level Trace Viewer logs all the actions carried out by
messages the platform (such as command execution,
authentication, queries on the database), while
Application Log traces only application level
messages.
Is more development Is more end-user oriented Trace Viewer is more suitable for advanced
oriented troubleshooting issues since it is highly verbose
and technical. Moreover it can contain logs
generated by the business logic, in terms of
command/event handlers, if the code uses them.
On the other hand Application Log is more
functional and end-user oriented. Consequently,
its messages are also more readable, and they
can be translated.
Stores logs in a database Stores logs in a database Both applications can store logs in a database,
but database maintenance and database maintenance but while Application Log can apply standard
is custom is standard provided maintenance procedures to clean old messages,
for Trace Viewer the database maintenance is
custom.

System Apps
Application Log App
Trace Viewer Application Log Description
Logs can be filtered and Logs can be filtered by level, In Trace Viewer, logs are classified in levels (from
sorted out by level and business command and verbose to critical), and in providers (representing
provider source Functional Block or the "component" which has generated a certain
App log). Levels and providers can be used to filter
messages, both in view mode and in storage
mode (to avoid that logs let the database grow in
uncontrolled way). In Application Log, logs can be
defined as different levels (from verbose to
critical as in Trace Viewer), return the name of the
business command that generated them, as well
as the "owners" of the commands (typically
Functional Blocks, Apps or Extension Apps).
For more information on Trace Viewer, see Logging and Analyzing Application Traces with Trace Viewer in Opcenter
2.1.2 Viewing Application Log Messages

You can access the Application Log page to view the application log messages persisted by the system, provided
you have defined and packaged the messages in Project Studio.
The page when launched lists all the messages. It embeds an extensive filtering mechanism that helps you retrieve
the most relevant application log messages. You can open each record to view further details regarding the
message. Select a record and click to open the Log Details pane.
2.1.2.1 Prerequisites
• Application log messages are defined and packaged for every Functional Block/App/Extension App for which
you wish to log messages.
• All the defined messages are logged to the runtime database by means of the Application Log platform API.
• All the required Apps and the Application Log App are installed and the related UI Modules are associated to
your UI Application, for which you wish to view the application log messages.
• All standard operations such as building the packages, deploying the solution, updating the database (if
needed) and starting the host services have been executed.
 Please refer to respective sections of Managing the Application Log File in the Opcenter Execution
Foundation Development and Configuration Guide for more information on how to accomplish
prerequisites and to view application log messages in different languages.
Accessing the Page

Do either of the following to navigate to Application Log page:
• Click the Application Log home tile.

• Click Application Log in the side menu bar and click Application Log.
Allowed Operations

System Apps
Application Log App
The Application Log page provides common UI functionalities to view application log messages. The filter
functionality lets you build a combination of multiple clauses to retrieve the most relevant application log
messages.
Application Log message display fields

The Application Log page displays application messages with following fields:
Field Name Description
RootCommand (CorrelationId) The value that aggregates the commands that generated the
application log messages. This value is a combination of
RootCommand and CorrelationId.
Root Command The short name of the root command of the commands that
generated the application log messages.
Command The short name of the command that generated the application
log messages.
Level The type of application log messages such as Critical, Verbose,

Informational, Error or Warning.
Owner The name of Functional Block, App or Extension App that owns
the application log messages.
Timestamp (UTC) The system time at which application log messages are
generated.
Log Details fields

The Log Details pane displays the following additional fields along with the above fields for a selected message:
Field Description
Short Message A short text of application log message that has been logged in runtime
environment.
Long Message A long text of application log message that has been logged in runtime
environment. A long text contains more verbosity than a short text for a
message.
Additional Operations to manage filters

The page also lets you save a filter, edit and save it as a new filter and clear all filters.
2.1.3 Application Log Maintenance

The Application Log App provides a screen to configure a Rule, which consists of a Cleaning Condition and a
Schedule to maintain system efficiency by cleaning Application Log messages and make the Application Log data
available for long-term querying.

System Apps
Application Log App
This configuration allows you to select application log messages as candidates to be processed by Data
Maintenance engine from Solution Studio. When a configuration with a default cleaning condition
All_ToBeCleaned_Entities is created for Data Maintenance from Solution Studio, the system will automatically
delete the candidate rows selected from the Application Log Maintenance from the runtime database. See What is
Maintenance in Opcenter Execution Foundation Development and Configuration Guide for more information on
Maintenance.
2.1.3.1 Configuring Maintenance Rule

In this page, you can define a Rule which will determine which Application Log messages will be physically removed
from the live database at runtime.
Workflow
A Rule can be created and configured by the following steps, explained further in the page
1. Create a Rule
2. Create a Condition Setting for the Maintenance Rule
3. (Optional) Create a Cleaning Schedule for the Maintenance Rule
A Maintenance Rule for application log can be scheduled for recurrent executions and can also run manually on
demand. However there can be only one execution of a Rule at any point of time. Executions spanning more than 12
hours will be ignored by the system to facilitate upcoming executions and the details of such executions will not be
updated in the overview tab of Application Log Maintenance Rule.
Prerequisites
Application log messages to be cleaned, based on the Rules configured in the Maintenance Rule screen
also requires a Data Maintenance configuration with the default cleaning condition All_ToBeCleaned_Entities to
be created and activated in Solution Studio.
 See What is Maintenance in Opcenter Execution Foundation Development and Configuration Guide for more
information on Maintenance in Solution Studio.
Accessing the Page

Do either of the following to navigate to Application Log page:
• Click the Application Log home tile.

• Click Application Log in the side menu bar and click Application Log.
Application Log Maintenance Rule display fields

The Application Log Maintenance Rule page displays Rule with the following fields in the Overview tab:
Id The Natural Key Identifier of the Rule.
Name The name assigned to the Rule.

System Apps
Application Log App
Description Additional information on the Rule.
Scheduled Indicates if the Rule is scheduled or not.
Status Indicates the current status of the Rule.
Last Run Indicates the date and time of the previous run.
Duration Indicates the duration of the previous run.
Number of Rows Indicates the number of rows selected to be cleaned in the previous run.
Result Indicates the status of the last run. Is one of the following: Failure, Success.
Next Run Indicates the scheduled date and time of the next execution of the rule.
Available operations on Rule

To manage your Application Log Maintenance Rule you can execute the following operations in the Rules screen:
Operation Description
Create a new Application Log Maintenance Rule To create a new Rule.
Update a Application Log Maintenance Rule To modify a Rule by changing the Name and
Description.
Delete a Application Log Maintenance Rule To delete a Rule.
Enable Application Log Maintenance Rule Schedule To enable schedule.
Disable Application Log Maintenance Rule Schedule To disable schedule.
Run a Application Log Maintenance Rule Manually To manually run a Rule.
Reload a Application Log Maintenance Rule To reload a Rule.
Creating a new Rule

1. In the Application Log Maintenance Rule page, click Create New to open the Create New Rule side panel.
2. In the Create New Rule panel, provide the following information
Parameter Description
Id The logical identifier assigned to the Rule. Once the Rule is created the field Id cannot
be modified.

System Apps
Application Log App
Name (Optional) The name assigned to the Rule.
Description (Optional) Details of the Rule.

3. Save changes.
Updating a Rule
1. In the Application Log Maintenance Rule page, select the rule you want to edit and click .
2. In the Update Rule side panel, modify the Name and/or Description, if needed.
3. Save changes.
Deleting a Rule
In the Application Log Maintenance Rule page, select the rule you want to delete and click .
Enabling Schedule on a Rule

In the Application Log Maintenance Rule page, select the rule you want to enable schedule and click .
See Configuring Schedule for more details on how to create a recurrent schedule for a Rule.
 A recurrent execution of a Rule will be skipped if there is any on going execution at the scheduled time.
Disabling Schedule on a Rule

In the Application Log Maintenance Rule page, select the rule you want to disable schedule and click .
 Upon Disabling a Schedule, the status of the Rule Execution will be set to Disabled and the Next Run field
will be reset until the Rule is again enabled for scheduled executions.
Run a Rule manually

In the Application Log Maintenance Rule page, select the rule you want to run manually and click .
 Run Now cannot be performed on a Rule if there is any on going execution, one has to wait until the
execution is completed.
Reloading a Rule
In the Application Log Maintenance Rule page, select the rule you want to reload and click .
Audit Trail of a Rule

System Apps
Application Log App
 Audit Trail data is available if the Audit Trail App is deployed and properly configured. For instructions,
see the Audit Trail App documentation.
To display the Audit Trail of a Application Log Maintenance Rule, select the Rule and then navigate to the Audit Trail
tab.
The Audit Trail tab shows the list of all changes performed on the selected Rule.
To see more details about each Audit Trail entry, click the arrow to the left of each row. This expands the details
of the respective Audit Trail entry.
2.1.3.1.1 Configuring Condition Setting

In this page, you can add a Condition Setting to a Rule which will determine which Application Log messages will
be physically removed from the live database at runtime.
Prerequisites
Rule must be created. See Configuring Rule for more details.
Condition Settings display fields

The Application Log Maintenance Rule page displays Rule with the following fields in the Overview:
Id The Natural Key Identifier of the Condition Setting.
Name The name assigned to the Condition Setting.
Description Additional information on the Condition Setting.
Expression Indicates the condition clauses selected.
Available operations on Condition Settings

To manage your Condition Setting you can execute the following operations in the Condition Settings tab
Creating a new Condition Setting To create a new Condition Setting.
Update a Condition Setting To modify a Condition Setting by changing the Name, Description and
Condition Clauses.
Deleting a Condition Setting To delete a Condition Setting.
Creating a Condition Setting

1. Select the Rule for which you require to add a Condition Setting.
2. In the Application Log Maintenance Rule page, click the Condition Settings tab.

System Apps
Application Log App
3. In the Condition Settings tab, click to open the Add Condition Setting side panel.
4. In the Add Condition Setting side panel, provide the following information
Id The logical identifier assigned to the Condition Setting. Once the Condition Setting
is created the field Id cannot be modified.
Name (Optional) The name assigned to the Condition Setting.
Description (Optional) Details of the Condition Setting.
Condition Clauses Conditions to determine the application log messages that should be cleaned.
Maximum of 10 clauses are allowed. See Defining Condition Clauses for more
information.
5. Save changes
Updating a Condition Setting

2. In the Condition Settings tab click to open Edit Condition Setting side panel.
3. In the Edit Condition Setting side panel, Name, Description and/or Condition Clauses, if needed.
4. Save changes.
Deleting a Condition Setting condition

2. In the Condition Settings tab, click .
Defining or changing a condition clauses

In Add Condition Setting or Edit Condition Setting side panel, it is possible to define the cleaning clause.
Every row in the lower part of the page represents a clause, i.e. an elementary true/false comparison between a
system field of an entity and a set value.
Clauses can be grouped together to define the priority of the operator.
The whole expression will be used at runtime to remove Application log messages from the live database.
Select the field filter you want to use from the Field drop-down list:
1. Timestamp to determine the Application Log messages whose Timestamp is older than the selected value.
Allowed values for Timestamp ranges from 2 hours to 365 days.
2. Level to determine the Application Log messages whose Level matches the selected value. All the severity levels
of Application Log messages are available for selection.
 When the Level field is configured with the operator< or <= the Application Log messages with severity
lower than the selected Level will be considered for cleaning. For example "Level < Warning" means the
application log messages with Informational and Verbose levels will be considered for cleaning.
If you want to group clauses, click for each filter clause you want to group, and then select And or Or for the
first clause in the group.

System Apps
Application Log App
2.1.3.1.2 Configuring Schedule

In this page, you can define Schedule for a Rule, which will determine when Application Log messages will
be physically removed from the live database at runtime in a recurrent manner.
Prerequisites
Rule must be created. See Configuring Rule for more details.
Schedule display fields

The Application Log Maintenance Rule page displays Rule with the following fields in the Overview:
Id The Natural Key Identifier of the Schedule.
Name The name assigned to the Schedule.
Description Additional information on the Schedule.
Start Date Indicates when the Rule is scheduled to start.
End Date Indicates when the Rule is scheduled to stop.
Time Zone Info Indicates the timezone in which the Schedule is configured.
Recurrence Type Indicates the type of Recurrence (hourly, daily or weekly).
Recurrence Indicates the number of hours (hourly recurrence type) or days (daily recurrence type).
Active Days Indicates the selected days (weekly recurrence type).
Available operations on Schedule

To manage your Maintenance Rule you can execute the following operations in the Schedule screen:
Create a new Schedule To create a new Schedule.
Update a Schedule To modify a Schedule by changing the Name,Description,Start

Date,End Date,Timezone Info,Recurrence Type and Recurrence or
Active Days.
Delete a Schedule To delete a Schedule.
Creating a new schedule

1. Select the Rule for which you require to add a Schedule
2. In the Application Log Maintenance Rule page, click the Schedule tab.

System Apps
Application Log App
3. In the Schedule tab, click Create New to open Add Schedule side panel.
4. In the Add Schedule side panel, provide the following information
Id The logical identifier assigned to the Schedule. Once the Schedule is

created the field Id cannot be modified.
Name (Optional) The name assigned to the Schedule.
Description (Optional) Details of the Schedule.
Start Date The fixed date and time when the Rule is Scheduled to start. By
default the current date and time will be selected.
End Date (Optional) The fixed date and time when the schedule must expire.
Timezone (Optional) The timezone in which the schedule is configured
Schedule Mode The type of recurrence configured for the schedule. Three options-
Hourly Schedule, Daily Schedule and Weekly Schedule are provided.
By default Hourly Schedule is selected.
It Recurs Every The recurrence value of the Schedule according to the chosen
Schedule Mode as per number of days/hours or as specific week days.
5. Save changes.
 When you create a periodic schedule for a rule, you should take the following limitation into account:
• The start time of a Schedule must be at least two minutes ahead of the time when Enable Schedule will
be performed, otherwise enabling a schedule will fail.
 Daylight Saving Time

When the time zone of a maintenance schedule is set, DST settings will apply. Please consider the
following edge cases:
• during spring forward transition to Daylight Saving Time, schedules that are configured to trigger at a
time of the day that does not exist due to the shift will be skipped completely
• during fall back transition, schedules that are configured to trigger at a time of the day that exists twice
will be fired only the first time
Updating a schedule
2. In the Schedule tab, click to open the Edit Schedule side panel.
3. In the Edit Schedule side panel, modify Name and/or Description if needed.
4. Modify Start Date, End Date, Timezone, Schedule Mode and the recurrence value according to the selected
schedule mode if needed.
5. Save changes.

System Apps
APS Interface App
Deleting a schedule
2. In the schedules tab, click .
2.2 APS Interface App

Opcenter Execution Foundation facilitates the integration with Opcenter Advanced Planning & Scheduling by
means of the APS Interface App.
The APS Interface App integrates products based on Opcenter Execution Foundation directly with Opcenter APS.
Consequently, you no longer need to use Opcenter Connect MOM to set up this kind of integration scenario.
The APS Interface App serves uniquely as an interface which must be implemented by an Extension App to provide
the required business logic.
The APS Interface App exposes several entities:

• that share the available resources of the runtime environment and the Work Order Operations to execute;
• that allow Opcenter APS to schedule the Work Order Operations, planning runtime equipment, plus the start
and end times of each Work Order Operation.
You can access these entities by means of database views. Opcenter APS does not provide these views as they are
expected to be implemented byOpcenter EX FN-based products.
The APS Interface App also includes three commands that do not contain any specific business logic except for
logging in Trace Viewer when they are executed.
These commands should be extended in an Extension App by means of Post-Actions, used update the data model
with scheduling information.

System Apps
APS Interface App
These commands can be also used to detect interactions with Opcenter APS:
• when Opcenter APS starts updating data related to the scheduling, such as Work Order Operations and their
respective runtime equipment,
• when scheduling has been done,
• when the scheduling activity has been cancelled.
 By default:
• The runtime environment resources are retrieved by Opcenter APS when it starts.
• Opcenter APS must be restarted to retrieve the latest state of the available resources of the runtime
environment.
The APS Interface references the APSInterface_OP Functional Block.
 • For detailed information on the artifacts contained in this Functional Block, see the APSInterface_OP
Reference Guide.
• For detailed information about the Entities mapping the views, see the APSInterface App Reference
Guide.
• For a general understanding of Functional Blocks, refer to the Overview of Functional Blocks section of
the Opcenter Execution Foundation Development and Configuration Guide.
Workflow
In order to use the APS Interface App, a System Integrator must take the following steps:
1. Create the views (required for the Entities of the the APS Interface App) within the data model.
 The products based on Opcenter Execution Foundation provide the relevant script(s) to generate these
views.
This documentation does not provide such a script. It only provides basic information about what
these views must contain in terms of fields and their respective format.
2. Create an APS Role:

a. Create a new Role to be dedicated to the integration with Opcenter APS.
See Creating Roles of the Opcenter Execution Foundation Development and Configuration Guide.
b. Assign the rights to use the APS Interface App features to this new Role:
See Assigning Rights to Roles of the Opcenter Execution Foundation Development and Configuration Guide.

System Apps
APS Interface App
• Read action for all its Entities

• Invoke action for all its commands.
3. Create a valid certificate.
See Generating a valid certificate and its private key of the Opcenter Execution Foundation Development and
Configuration Guide, for details.
4. Associate the new certificate with the Role dedicated to the APS Integration.
See Importing the Certificate into the Opcenter EX FN Solution of the Opcenter Execution Foundation Development
and Configuration Guide, for details.
5. Install and configure Opcenter APS.
6. Bind the views created for the APS Interface App with Opcenter APS.
 We recommend that you contact the experts of Opcenter APS in order to perform this step.
Consider the creation of a package to perform the necessary bindings between the views and the data
model used by Opcenter APS.
7. Create an Extended App based on the APS Interface base App.

8. Within the this Extension App, create the Post-Actions for the commands of the APS Interface App and add the
custom business logic and respective logging messages in the Post-Action handlers.
9. Add the newly-created Extension App to a Solution.
Next step
In order to quickly customize the exposed data to Opcenter APS, see Quick Customization Related to the Views of
the APS Interface App.
2.2.1 Views Related to the APS Interface App

The APS Interface App relies on views that must be created within the data model. The APS Interface App provides
Entities that reflect the content of these views.
This documentation does not explain how to create the views. It only provides the basic information relative to
each view: the field names and their respective data type for the database.
 We recommend that products based on Opcenter Execution Foundation implement the creation of the
views within their setup procedures.
To get a better understanding about the meaning of each view field, please refer to the Reference Guide of the APS
Interface App. The view fields are used to defined the properties of the Entities. The property names coincide with
the names of the view fields.
 Refer to the APSInterface App Reference Guide for details.
List of views:
• APSOperationRelation
• APSOperationResource
• APSOrder
• APSOrderStatus
• APSOrderOperation
• APSOrderOperationStatus
• APSResource
• APSResourceGroup

System Apps
APS Interface App
• APSResourceGroupMatrix
 In order to quickly customize the exposed data to Opcenter APS, see chapter Quick Customization Related
to the Views of the APS Interface App.
APSOperationRelation view
Field Type
Id INT
DependencyType INT
OpderNId NVARCHAR(MAX)
OperationNId NVARCHAR(MAX)
OperationStatus NVARCHAR(MAX)
PredessorOperationNId NVARCHAR(MAX)
Type NVARCHAR(1)
APSOperationResource view
Field Type
Id INT
OperationNId NVARCHAR(MAX)
OpderNId NVARCHAR(MAX)
ResourceNId NVARCHAR(MAX)
Sequence INT
Type NVARCHAR(1)
APSOrder view
Field Type
Id INT
DueDate DATETIMEOFFSET(7))

System Apps
APS Interface App
Field Type
OrderNId NVARCHAR(MAX)
OrderNote NVARCHAR(MAX)
Priority INT
ProductionType INT
Quantity DECIMAL(18,3)
ProductName NVARCHAR(MAX)
ProductNid NVARCHAR(MAX)
OrderStatus NVARCHAR(MAX)
Type NVARCHAR(1)
CustomField1 NVARCHAR(MAX)
APSOrderStatus View
Field Type
Id INT
NId NVARCHAR(50)
Description NVARCHAR(50)

System Apps
APS Interface App
Field Type
Color INT
StateMachineNID NVARCHAR(MAX)
APSOrderOperation view
Field Type
Id INT
PlannedEndTime DATETIMEOFFSET(7))
ActualEndTime DATETIMEOFFSET(7))
PlannedResourceNId NVARCHAR(MAX)
ActualResourceNId NVARCHAR(MAX)
ResourceGroupNId NVARCHAR(MAX)
PlannedStartTime DATETIMEOFFSET(7))
ActualStartTime DATETIMEOFFSET(7))
Locked INT
OperationName NVARCHAR(MAX)
OperationNid NVARCHAR(MAX)
OperationSequence INT
OrderNId NVARCHAR(MAX)
ProcessRate DECIMAL(18,3)
ProcessTime INT
ProcessTimeType INT
Type NVARCHAR(1)

System Apps
APS Interface App
Field Type
APSOrderOperationStatus view
Field Type
Id INT
NId NVARCHAR(50)
Description NVARCHAR(50)
Color IN
StateMachineNID NVARCHAR(MAX)
APSResource view
Field Type
Id INT
ResourceName NVARCHAR(MAX)
ResourceLevel NVARCHAR(MAX)
ResourceType NVARCHAR(MAX)

System Apps
APS Interface App
Field Type
APSResourceGroup view
Field Type
Id INT
ResourceGroupName NVARCHAR(MAX)
ResourceCategory NVARCHAR(MAX)
ResourceType NVARCHAR(MAX)

System Apps
Audit Trail App
Field Type
APSResourceGroupMatrix view
Field Type
Id INT
2.2.2 Quick Customization Related to the Views of the APS Interface App
For System Integrators, Opcenter Execution Foundation facilitates the addition of data exposed to Opcenter
Advanced Planning & Scheduling regarding Entities provided by the APS Interface App.
These Entities depend on views.
 Beware that the creation of these views is the responsibility of the System Integrator.
For several of these the Entities, there are eleven Properties dedicated to facilitate customization. These Properties
are named and numbered CustomField1, CustomField2, CustomField3, ..., CustomField10.
The views that provide theses custom fields are:
• APSOrder
• APSOrderOperation
• APSResource
• APSResourceGroup
Prerequisites
The Views mapped by the APS Interface App have been created by the System Integrator.
Workflow
1. Identify the code source that creates the APSOrder, APSOrderOperation, APSResource,
and APSResourceGroup. views.
2. Customize the code source of these views in order to populate the query fields with relevant data required by
your integration.
3. Customize the binding within Opcenter Advanced Planning & Scheduling for these custom fields. Please context
an Opcenter APS for further information if you need assistance.
2.3 Audit Trail App

The Audit Trail App delivers both Audit Trail functionalities as well as Electronic Signature functionalities.
The Audit Trail App references the following Functional Blocks:
• UDM_RF

System Apps
Audit Trail App
• ES_SD
• ES_MS
For detailed information on the artifacts contained in these Functional Blocks, see the Reference Documentation of
the Functional Block.
What can I do with the Audit Trail App?

• Useful conceptual information is provided in:
• What is an Audit Trail Configuration?
• What is an Electronic Signature Scenario?
• Configuration workflows and procedures are provided in:
• How To Enable the Audit Trail Configuration
• Creating an Electronic Signature Scenario
• Custom integration guidelines are provided in:
• How To Integrate Audit Trail for Custom Implementations
• How to Integrate Electronic Signature in Custom Applications in the Opcenter Execution
Foundation Development and Configuration Guide).
2.3.1 Audit Trail

The Audit Trail App provides pages, which are visible in Solution Studio, where you can configure a set of audit trail
relevant entities in order to trace relevant information about runtime operations executed on the selected relevant
entity instances.
You can then display these information through dedicated audit trail records in the Audit Trail App UI screen or
perform subscriptions in order to associate the received audit trail information with custom business logic.
2.3.1.1 What is an Audit Trail Configuration?

An audit trail in Opcenter EX FN is a security-relevant set of records, which provide evidence of all the operations
that have been carried out on a specific entity instance. If you can guarantee detailed historical information about
data changes, you can assure qualitative data and you are more likely to adhere to quality regulations.
The Opcenter EX FN Audit Trail App allows you to trace relevant information about operations executed on entity
instances and display these information through dedicated audit trail records.
Each time your application creates, modifies or deletes an entity instance that was previously defined as audit trail
relevant, the system stores all the change-related information, such as which was the executed operation, who
performed the operation, when and where the operation occurred.
All the entities that need to be tracked with audit trail data make part of the audit trail configuration. The audit trail
configuration can be only one per Solution, it is configured in Solution Studio, it can be disabled/enabled at any
time and it can be applied in hot deployment mode, without stopping the running Manufacturing Solution.
Audit trail data is protected and it cannot be accessed by unauthorized users unless they have been configured
within the proper user roles, with the required permissions.
What Audit Trail is applied to

When you choose an entity and insert it in an audit trail configuration, the system will automatically handle as audit
trail relevant also some other related entities depending on the existing relationships, as described in the following
table:

System Apps
Audit Trail App
Entity Model Audit trail attribute propagation
Entities in composition You can set the audit trail attribute only on the parent entity
and the system automatically makes all the composition parts
to audit trail relevant.
Derived entities (physical extension) You can set the audit trail attribute only on the root
entity and the system automatically propagates the audit trail
to all the derived entities.
Facets (logical extension) You can set the audit trail attribute only on the parent
to all its facets.
Entities in relationships There is no automatic propagation of the audit trail attribute.

Each entity must be autonomously selected.
2.3.1.2 How To Enable the Audit Trail Configuration

To trace audit trail records you must first configure the audit trail relevant entities and then enable the
configuration.
Workflow
1. Add the Audit Trail App to the Solution.
2. Configure the audit trail relevant entities.
3. Configure the audit trail access rights.
4. Enable the configuration at runtime.
2.3.1.2.1 Adding the Audit Trail App to the Solution

All the functionalities and the Solution Studio pages related to the audit trail configuration and deployment are
available after you add the Audit Trail App to the Manufacturing Solution.
For the procedure of adding an App to the Solution, see the Adding a New App to a Solution section in the Opcenter
If you want to uninstall the Audit Trail App from your Solution, and you have already configured an audit trail
configuration, you must first delete the audit trail configuration before you can uninstall the Audit Trail app.
2.3.1.2.2 Configuring Audit Trail Relevant Entities

To configure audit trail relevant data, you must have first added the Audit Trail App to the Solution (otherwise,
audit trail related functionalities will not be accessible). Then, you can create the audit trail configuration in
the Audit Trail Configuration page of Solution Studio.
The audit trail configuration contains all the entity types for which you want to track the audit trail information. The
entity types you can choose belong to the data models (writing models) of the Functional Blocks that are
referenced by the Apps of your Solution.

System Apps
Audit Trail App
According to the selected entity types and their relationships within the data model, the system will automatically
apply the audit trail to some related model objects, as described below in the Audit trail behavior for related entity
types section.
The audit trail configuration is saved in the Engineering Repository and there can only be one configuration for the
Solution.
Available operations on audit trail configuration

To manage your audit trail configuration you can execute the following operations in the Audit Trail Configuration
page:
Create a new configuration from scratch To create a new configuration and enable it.
Import a previously exported configuration To import a previously exported configuration.
Export a configuration To export a configuration if your audit trail configuration

contains at least one entity.
Modify a configuration To modify a configuration by changing name, description

or any entity assignment.
Delete a configuration To delete a configuration.
Enable or disable the configuration. To change the configuration status.

If enabled, the configuration is added to the solution
package and is ready to be deployed.
Creating a new configuration from scratch

1. In the Solution Studio Audit Trail Configuration page, click Create New.
2. In the Create New Audit Trail Configuration pane, enter a name and description to identify the configuration.
Special characters cannot be used.
3. Select the entities to be included in the audit trail configuration. According to the data model relationships, the
system will automatically handle as audit trail relevant other related entities as described in the following table:
Entities in composition You can set the audit trail attribute only on the parent entity
and the system automatically makes all the composition
parts to audit trail relevant.
Derived entities (physical extension) You can set the audit trail attribute only on the root
to all the derived entities.

System Apps
Audit Trail App
Facets (logical extension) You can set the audit trail attribute only on the parent
to all its facets.
Entities in relationships There is no automatic propagation of the audit trail attribute.

Each entity must be autonomously selected.
 To make the selection easier, you can search by entities or by entity domains. In case of extended
entities, you can also search by parts, facets or extended entities and the system will return the
associated base entity, enriched with the information on related parts, facets or extended entities (this
information can be accessed by clicking on the arrow icon placed next to the returned entity).
4. If you want to make this configuration ready to be deployed, select the Enable check box. The configuration is
not applied now, but it will be ready for tracking records after the Solution deployment (see Enabling the
Configuration at Runtime).
5. Save changes.
Importing a previously exported configuration

1. In the Audit Trail Configuration page, click .
2. Proceed as follows:
• If you do not have any audit trail configuration, enter a name and a description for the configuration your
about to create (special characters cannot be used), select the file/s to be imported, and select the
Enable check box to make this configuration ready to be deployed.
• If you already have a configuration, select either Override or Append (to either overwrite the existing
configuration or to 'add' the imported configuration/s to the existing one) and select the file/s to be
imported.
Exporting a configuration
In the Audit Trail Configuration page, click .
The output file name and the target directory cannot be modified. If you export the same configuration twice, the
previously exported file will be overwritten.
 Security Note
Bear in mind that after you have exported an audit trail configuration, strict measures should be taken to
guarantee that the exported information is correctly and securely stored until it is re-imported.
Modifying a configuration
1. In the Audit Trail Configuration page, click .
2. Modify name or description if needed.
3. Select new entities or unselect any previously assigned entities to modify the entity assignment of the
configuration.
4. Save changes.
5. If you want to enable (or disable) the configuration, see Enabling the Configuration at Runtime.

System Apps
Audit Trail App
Deleting a configuration
In the Audit Trail Configuration page, click .
If your audit trail configuration is running and you only want to temporarily stop it, you should better use the
disable functionality (see Enabling the Configuration at Runtime).
If your audit trail configuration is running and you delete it, the system goes on recording audit trails until you apply
the configuration.
2.3.1.2.3 Configuring Audit Trail Access Rights

You must assign specific access rights to authorize the users that are allowed to read audit trail records. This can be
achieved by assigning specific permissions to the required user roles.
In particular, you must assign reading permissions to the AuditTrailRecord entity for the user roles you need at
runtime, as described in How to Configure Accounts of the Opcenter Execution Foundation Development and
2.3.1.2.4 Enabling the Configuration at Runtime

To start (or stop) tracking the audit trail records at runtime, you must enable (or disable) the audit trail
configuration as follows:
• if you are creating a new audit trail configuration, enable the configuration in the New Audit Trail
Configuration page.
• if you are modifying an already existing configuration, open the Audit Trail Configuration page and click the
button to change the configuration status on the command bar.
In both cases, if you want to activate the behavior at runtime, you must build and deploy the Solution (see How to
Manage a Manufacturing Solution in Solution Studio in the Opcenter Execution Foundation Development and
Configuration Guide).
2.3.1.3 How To Display Audit Trails in the Audit Trail App UI Screens
You can display audit trail records by using the Audit Trail App UI Screen as follows.
Workflow
1. Add the UI Screen to the UI Application in Solution Studio.
2. Deploy the Solution with the UI Application.
3. Display audit trail records.
2.3.1.3.1 Adding the Audit Trail UI Module to the UI Application

To view audit trail data by means of the Audit Trail App UI Screen, you must add the Audit Trail Management UI
Module to your UI Application, as described at page Selecting UI Modules in the Opcenter Execution
Foundation Development and Configuration Guide.
2.3.1.3.2 Deploying the Solution with the UI Application

To deploy the UI Application containing the Audit Trail Management UI Module, execute the standard operations
of:
• building the packages,
• deploying the solution,

System Apps
Audit Trail App
• updating the database (if needed),

• starting the host services.
as described at section How to Deploy a Manufacturing Solution in the Opcenter Execution Foundation Development
and Configuration Guide.
2.3.1.3.3 Displaying Audit Trail Records in the Audit Trail Management UI

Module
After you have deployed the Manufacturing Solution and the UI Application with the Audit Trail Management
module, you can access the Audit Trail UI screen to view the audit trails recorded for the required operations.
The page embeds a search functionality on all the most audit trail relevant information and displays the results in a
table view.
Each record can be expanded to show the modification details.
Accessing the page

Click Audit Trail Management in the side menu bar and click Audit Trail.
Available operations
Sorting results You can sort results by choosing the field on which you want to apply the ordering
criteria (in ascending or descending order).
Searching By clicking on the icon placed on the top of the screen, you can enter search
criteria in the provided filters in order to search by the most relevant information
(operation time stamp, user name, action type, entity type name, entity element id,
executed command). You can only search by root entities, consequently:
• In case of extended entities, you can search either by the base entity or by the
extension entity.
• In case of composition parts or facets, you can only search by the base entity.
By clicking on the icon placed next to each retrieved record, the system
automatically fills in the search criteria with the Id (Guid) of the selected item and
makes it easier to search for all the items that are related to the selected one.
Expanding record You can expand each record to view the property details, such as the old value and the
details new value of either a simple property or a complex property or a navigation property,
or any associated data segregation tags.
The changes applied to the values of properties of large dimensions (such as blob
types or max length strings), in terms of old value and new value, are not displayed.
If the record you expand belongs to a root entity, the information on the child entities
will be displayed below, in the Show More section.
 The returned information reflects the description provided for the

AuditTrailRecord entity.

System Apps
Audit Trail App
2.3.1.4 How To Integrate Audit Trail for Custom Implementations

If you need to perform custom implementations, you can integrate Audit Trail functionalities as follows:
• You can use the Audit Trail widget (provided by Opcenter EX FN UI Framework) inside custom UI Screens.
• You can subscribe to the AuditTrailRecordCreated event to retrieve audit trail information and apply a proper
business logic.
2.3.1.4.1 How To Use the Audit Trail Component in Custom UI Screens

If you need to implement custom UI pages and display audit trail records, the Opcenter Execution
Foundation Platform provides a widget that can be embedded in custom UI screens developed in standard UI
Modules in Project Studio.
To implement standard UI Modules and Screens refer to Code-Based Development of UI Components and UI Modules
in the Opcenter Execution Foundation Development and Configuration Guide.
For the widget reference documentation, see the siemens.simaticit.common.widgets.auditTrail section in the
Opcenter Execution Foundation UI Framework Reference Guide.
2.3.1.4.2 How to Retrieve Audit Trail Information and Apply Custom Logic
To retrieve audit trail information and apply the required business logic, you can subscribe a custom event handler
to the AuditTrailRecordCreated event.
You can also directly query the AuditTrailRecord entity, although a query is already implemented in the Audit Trail
UI Component, which can be directly embedded inside custom UIs.
You can promote the AuditTrailRecordCreated event to Signal in Project Studio, and modify the Signal Rule in the
Signal App to invoke the required logic when the event is triggered. You cannot directly use the AuditTrailRecord
entity as source block in the Signal Rule.
This page contains information about the AuditTrailRecord entity and the AuditTrailRecordCreated event.
Handling the AuditTrailRecordCreated event through custom Event Handlers

The AuditTrailRecordCreated event is available in all the three Functional Block domains (Reference Data, Master
Data and Operational Data), contained inside the SystemData.Foundation project.
It allows you to subscribe in Solution Studio, via Event Subscription, to the changes occurred in
the AuditTrailRecord entity and develop your business logic in custom Event Handlers (as well as via predefined
Event Subscriptions in Project Studio).
Each AuditTrailRecordCreated event is fired at the end of a successful transaction, and returns information about
the modified entity instance.
The AuditTrailRecordCreated event is available as a referenced system event inside the model project of
Functional Blocks, Apps and Extension Apps. The model assembly reference required to handle the
AuditTrailRecordCreated (i.e. the Siemens.SimaticIT.SystemData.Foundation.Events.dll assembly which can
be found in %SITUnifiedSystemRoot%bin) is automatically inserted in the handler project, but if required it can
be inserted manually.
By implementing a custom event handler and then subscribing this handler to the AuditTrailRecordCreated, you
can associate any logic with the changes made to the audit trail relevant entities.
To handle the AuditTrailRecordCreated through an event handler you have to go through the following steps,
described in the Opcenter Execution Foundation Development and Configuration Guide:
1. Create a custom event handler (see Creating Event Handlers).
2. Import the custom handler (see Importing Event Handlers).

System Apps
Audit Trail App
3. Implement the custom event handler (see Implementing Command and Event Handlers).
4. Subscribe the handler to the AuditTrailRecordCreated (see Configuring Event Subscriptions).
Alternatively, you can also create a subscription to the AuditTrailRecordCreated and implement custom logic in an
external application that uses the IUnifiedSdkLean public interface (see Developing Third-Party Applications
Integrated with Opcenter Execution Foundation).
You cannot fire the AuditTrailRecordCreated: an authorization error will be returned at runtime
(ArgumentException).
 See page AuditTrailRecord Entity and AuditTrailRecordCreated Event for the details on the parameters
returned by the AuditTrailRecordCreated so that you can properly use it inside your code.
2.3.1.4.2.1 AuditTrailRecord Entity and AuditTrailRecordCreated Event

For each audit trail relevant entity that has been created, modified, deleted, frozen/unfrozen, locked/unlocked or
marked for cleaning inside a transaction and that is notified via CommittedEvent (see Handling the
CommittedEvent in the Opcenter Execution Foundation Development and Configuration Guide), the system inserts a
record inside the AuditTrailRecord data structure.
Each time a record is added to the AuditTrailRecord data structure, the system fires
the AuditTrailRecordCreated event, containing the same record information.
For reference information on the AuditTrailRecordCreated event parameters and AuditTrailRecord entity
properties, see the SystemData.Foundation reference documentation.
For information about maintenance of AuditTrailRecord database table, see Using Maintenance Stored Procedure
AuditTrailRecord data structure

Entity Attribute Description
RootEntityId Unique identifier of the Root Entity instance that was assigned to the
audit trail configuration.
RootEntityName Logical key of the Root Entity instance, obtained from the
concatenation of its logical keys.
RootEntityType Full name of the Root Entity Type that was assigned to the audit trail
configuration.
ChangedEntityId Unique identifier of the Entity instance that actually changed.
ChangedEntityName Logical key of the Entity instance that actually changed, obtained from
the concatenation of its logical keys.
ChangedEntityType Full name of the Entity instance that actually changed.

In case of derived entities, this is the name of the extended entity type
(while the RootEntityType indicates the base entity).
RootCommand Name of the Root Command that originated the change.

System Apps
Audit Trail App
Action Type of change executed in the transaction. Possible values are Added,
Modified, Deleted.
In case of freeze/unfreeze, lock/unlock or mark for cleaning operations,
more detailed information is contained in the ChangedEntity attribute
(see examples below).
In case of different values related to electronic signature management,
see ElectronicSignatureId element below in this table.
UserName Full name of the user who performed the change.
UpdatedOn Timestamp of the submit operation.
Environment The environment where the change occurred. It is defined during the
environment configuration phase (seeOpcenter Execution Foundation
Installation Guide).
ComputerName (For future implementation) The name of the computer where the
change occurred.
ChangedEntity JSON representation of the changes applied to the Entity instance (or
facet instance), without the representation of the values of the large
properties. See example below.
ChangedLargeProperties JSON representation of the changes applied to the large properties of

the Entity instance (or facet instance). See example below.
CorrelationId The value of the CorrelationId, which aggregates the Audit Trail
records generated during the execution chain.
Domain Entity domain.
Entity domain Incremental Id that represents the order by which the record was
inserted.
ElectronicSignatureId Identifier of the Electronic Signature runtime entity.

If this element is populated, the Audit Trail record has been generated
for an entity verified by Electronic Signature and the entity properties
assume the following values:
• ElectronicSignatureId refers to the inserted Signature
• Action is either Signature Approved or Signature Rejected
• Root Command is empty
• ChangedEntity and ChangedLargeProperties are empty JSON
structures
TransactionId Transaction Identifier.

System Apps
Audit Trail App
AssociatedRows An integer that identifies the main record inside a set of Audit Trail
records and represents the number of the associated records.
For example, in case of three entities in composition with a parent
entity and two parts, the AssociatedRows property of the record
corresponding to the parent entity would be AssociateRows = 3.
ChangedEntity JSON description

The ChangedEntity JSON object contains the following elements according to the action.
• Create action on an entity:
Element Description
Id Unique identifier of the Entity instance that actually changed.
EntityType Full name of the Entity instance that actually changed.
LogicalKeyProperties The list of the scalar properties that make up the logical key,
represented by a sequence of nodes where each node contains
the property name and the property value.
The logical key values will not be represented in the scalar/
complex/navigation structures.

System Apps
Audit Trail App
Element Description
ChangedScalarProperties For each simple entity property (or facet property), the
following elements:
• Name, containing the property name
• OldValue, containing the value before the change (always
set to null in a create action)
• NewValue, containing the newly inserted value.
In case of large properties, this element returns only the Name
element (and not OldValue and NewValue). To retrieve the
changed values, refer to the ChangedLargeProperties property
below.
Only for the following operations:
• freeze/unfreeze,
• lock/unlock,
• mark for cleaning,
the Type element is present and set to System, and for these
operations, the Name element is set to IsFrozen, IsLocked,
ToBeCleaned (see examples below) with the related values
(true or false) indicated in the OldValue or NewValue element.
ChangedComplexProperties The name of the modified complex types and for type, the list of
the modified simple properties expressed by the same elements
as the ChangedScalarProperties node.
ChangedForwardNavigationProperties The element contains the OldValue and the NewValue nodes
containing, respectively, the old values and the new values for
the Id and the logical key of the entity you are referencing.
For each OneToMany relationship, the node returns the
information related to the 'Many' side of the relationship.
In case of facets, this element returns the id of the base entity
(the entity to which the facet refers).
ChangedBackwardNavigationProperties The element returns the information related to the parent

entities in a Many-To-Many relationship. The OldValue and the
NewValue elements contain the list of the referenced entities
represented by Id and logical key.
This element also returns information about related facets
(facets will be identified by the following properties: Entity
Type set to the facet name and Id set to the facet id, as shown
below in the section dedicated to facets).
DataSegregationTags This element returns the list of the associated data segregation
tags.
• Update action on an entity

System Apps
Audit Trail App
• Update action on an entity by assigning data segregation tags:
The JSON contains the same elements as the JSON for the create action (see table above).
 Some of the update commands used by the Opcenter EX FN Apps overwrite all entity properties with the
entity original properties even in case of a single property change. In such cases, the AuditTrailRecord will
contain the list of the modified properties with OldValue and NewValue set to the same values.
• Delete action

System Apps
Audit Trail App
The JSON contains the same elements as the JSON for the create but the returned information is limited to:
• Id, EntityType, UpdatedOn and LogicalKeyProperties. All other elements are always empty.
ChangedEntity JSON description in case of operations on facets

If you add a facet to an entity (or if you modify an existing facet), the audit trail information will be traced as follows:
• An audit trail record will report the modified entity containing a new entry in
the ChangedBackwardNavigationProperties, with the Id and the name of the added facet.
• A second audit trail record will report the information related to the added facet, with
the ChangedScalarProperties containing the facet values (Name and NewValue) and
the ChangedForwardNavigationProperty containing the Id of the base entity).

System Apps
Audit Trail App
ChangedEntity JSON description in case of operations on composition parts

If you add two entities in composition, the audit trail information will be traced in two records as follows:
• An audit trail record will report the information related to the parent entity as described for standard entities
and, in the ChangedBackwardNavigationProperties, the Id and the property values for the entity in
composition.
• A second audit trail record will report the information related to the child entity, and in
the ChangedForwardNavigationProperty, the Id of the base entity.
Both elements identify the composition part entity by returning the IsComposition property set to true.

System Apps
Audit Trail App
ChangedEntity JSON description in case of operations on extended entities

The ChangedEntity JSON object returns the same information as for a base entity (while RootEntityType
and ChangedEntityType return the name of the base entity type and the derived entity type, respectively).
ChangedEntity JSON description in case of large properties

If the change occurred on the values of 'large' property types, these values are not returned by the
ChangedScalarProperties JSON element (see ChangedLargeProperties JSON example below):
ChangedEntity JSON description in case of Freeze, Lock, Mark for Cleaning

operations on entities
The ChangedScalarProperties JSON element returns information about changes executed on the following
system properties: IsFrozen, IsLocked, ToBeCleaned).
In the following example, the IsFrozen property has been set to true (i.e. freeze entity):

System Apps
Audit Trail App
In the following example, the IsLocked property has been set to false (i.e. unlock entity):
In the following example, the ToBeCleaned property has been set to true (mark for cleaning):
ChangedLargeProperties JSON description

System Apps
Audit Trail App
The ChangedLargeProperties JSON object contains the same structure as the ChangedEntity property JSON, but
it only returns values for the following 'large' property types:
• blob
• string decorated with the MaxLength attribute
Large properties can be contained both inside the base entities (also inside value types) and inside the facets.
AuditTrailRecordCreated event data structure

The event input data structure is composed by a list of parameters which map all the information of
the AuditTrailRecord entity (except for the TransactionId).
Event Parameter Description
RootEntityId Unique identifier of the Root Entity instance that was assigned to the audit
trail configuration.
RootEntityName Logical key of the Root Entity instance, obtained from the concatenation
of its logical keys.
RootEntityType Full name of the Root Entity Type that was assigned to the audit trail
configuration.
ChangedEntityId Unique identifier of the Entity instance that actually changed.
 For composite entities or facets, this Id refers to the child-entity

or to the facet, while in case of simple entities or related entities,
this Id coincides with the RootEntityId.
ChangedEntityName Logical key of the Entity instance that actually changed, obtained from the
concatenation of its logical keys.
ChangedEntityType Full name of the Entity instance that actually changed.
RootCommand Name of the Root Command that originated the change.
Action Type of change. Possible values are Create, Edit, Delete.

System Apps
Audit Trail App
Event Parameter Description
UserName Full name of the user who performed the change.
Environment The environment where the change occurred. It is defined during the
environment configuration phase (see Opcenter Execution
Foundation Installation Guide).
ComputerName (For future implementation) The name of the computer where the change
occurred.
ChangedEntity JSON representation of the changes applied to the Entity instance (or
facet instance), without the representation of the values of the large
properties.
HasLargeProperties Boolean. If this value is true, it means that 'large' properties have been
changed. To retrieve their values, you must perform a query to retrieve
the corresponding AuditTrailRecord instance and read data from the
ChangedLargeProperties property.
CorrelationId The value of the CorrelationId, which aggregates the Audit Trail records
generated during the execution chain.
Ordering Incremental Id that represents the order by which the record was inserted.
2.3.2 Electronic Signature

The Audit Trail App provides a UI page useful to create the Electronic Signature Scenarios and configure the related
Signatures as well as a set of functionalities that can be used to integrate the Electronic Signature functionality
inside custom Apps.
Bear in mind that the integration of the Electronic Signature functionalities inside a custom App is mandatory if you
want to use the Electronic Signature functionalities at runtime in your Manufacturing Solution and the
configuration of the Scenario with its Signatures is not sufficient to achieve the complete scenario.
 For an overview on the functionality start reading What is an Electronic Signature Scenario? and proceed
with Creating an Electronic Signature Scenario. Then refer to How to Integrate Electronic Signature in
Custom Applications section in the Opcenter Execution Foundation Development and Configuration
Guide for the integration guidelines.
2.3.2.1 What is an Electronic Signature Scenario?

An Electronic Signature is a set of data associated to the personal credentials of a user and implies the same legal
standing as when providing a handwritten signature.

System Apps
Audit Trail App
In Opcenter EX FN, this set of data is stored by means of the user name and the related password.
Electronic Signatures are inserted by typing in the required credentials and are used at runtime to verify that a
certain authorized user has checked and validated an operation before proceeding with any other actions.
For example, if an operation requires the consumption of a certain material, the quality process may require that a
certain user certifies that the material consumption has been carried out properly before the operation can be
completed.
The procedure of validating the operation is performed by inserting the Electronic Signatures that are required for
that operation, according to the configuration provided in the Electronic Signature Scenario.
The Electronic Signature Scenario is the configuration of the Electronic Signatures that need to be collected at
runtime for a certain operation. There can be more different Electronic Signature Scenarios for all the needed
operations.
In each Electronic Signature Scenario, you must configure each signature by defining whether the signer is either a
specific user, or a user belonging to a certain Opcenter EX FN business role, or a logged on user. Additionally, you
can also define the reason for which the signature is required.
At runtime, User Management Component verifies that the user credentials are correct, and if they are correct, the
Audit Trail App validates the Electronic Signatures.
To start configuring the Electronic Signature scenarios see Creating an Electronic Signature Scenario and refer to
How to Integrate Electronic Signature in Custom Applications section in the Opcenter Execution
Foundation Development and Configuration Guide for integration guidelines.
2.3.2.2 Creating an Electronic Signature Scenario

Before you can use Electronic Signature functionalities, you must configure the required Electronic Signature
Scenarios and the related Signatures.
Once the configuration is completed, we suggest you freeze the Electronic Signature Scenarios in order to prevent
unauthorized users from modifying the configurations.
If properly configured in Solution Studio, Audit Trail data is available for Electronic Signature Scenarios that have
been defined as Audit Trail relevant.
After you have configured the Electronic Signature Scenarios (and if the integration in a custom App has been
implemented), Electronic Signature configurations are ready to be used without the need to explicitly enable them.
 For integration guidelines, see How to Integrate Electronic Signature in Custom Applications in the Opcenter
The engineering functionalities of the Audit Trail App described in this section use the data model and the
commands available in the ES_MS Functional Block (see ES_MS Functional Block in the Opcenter Execution
Procedure
1. Do either of the following to open the Scenario Configurations page:
• Click the Scenario Configurations home tile.
• Click Electronic Signature Manager in the side menu bar and click Scenario Configurations.
2. In the Scenario Configurations page click .
3. Enter an ID, a name and a description to identify the configuration.
4. Click Save.

System Apps
Audit Trail App
Adding Electronic Signatures to an existing Scenario

1. In the Scenario Configurations page, select a Scenario Configuration and click to open the Scenario
Configuration page.
2. In the Scenario Configuration page, select the Scenario Configuration you want to associate signatures to.
3. Click the Signatures tab and click .
4. Set the required signature attributes:
Attribute Description
Type Can be either of the following:

• Specific User, to associate a specific UMC user
• Business Role, to associate a specific Opcenter EX FN role.
Signer According to the selected type, an item selected from the provided list of UMC users or
Opcenter EX FN roles.
Reason Additional information describing why the signature is required.
The If selected, it will be mandatory to provide a comment together with the signature.
comment is
mandatory
5. Click Save. The new Signature is displayed in the Signatures tab.
Available Operations on Electronic Signature Scenarios

On the existing Electronic Signature Scenarios you can then perform the following operations, by selecting the
Scenario Configuration and clicking the proper icon.
To modify Name and Description of the existing Scenario

Edit Scenario Configuration
Configuration.
To freeze/unfreeze the scenario configuration. Note that

/ Freeze/Unfreeze Scenario
frozen instances can be queried and deleted from the
Configuration
database, but they cannot be updated. See Managing Life
Cycle Attributes of Entity Instances in Opcenter Execution
To permanently remove a Scenario Configuration.

Delete Scenario Configuration
To export selected entities and instances in an export package

Export
that can be downloaded locally and imported
afterwards. See How To Export and Import Data.
Displaying Audit Trail data of an Electronic Signature Scenario

System Apps
Automation App
Audit Trail data is available if the Scenario Configuration entity is properly included in the Audit Trail configuration
as documented in How To Enable the Audit Trail Configuration.
To consult the Audit Trail of an Electronic Signature Scenario:
1. In the Scenario Configurations page, select a Scenario Configuration and click to open the Scenario
Configuration page.
2. In the Scenario Configuration page, select the desired Scenario Configuration item.
3. Click the Audit Trail tab to see the list of all changes performed on the selected Scenario Configuration.
4. To see the details about each Audit Trail entry, click the arrow to the left of each row.
2.4 Automation App

The Automation App provides pages where it is possible to configure automation nodes in a user-friendly
environment.
The Automation App references the following Functional Blocks:
• UDM_RF
• ATN_OP
• ATN_MS
• AGW_MS (this Functional Block is not documented as it is only for internal use)
What can I do with the Automation App?

• Useful conceptual information is provided in:
• What is the Automation Gateway
• What Are Automation Entities?
• What Is the Lifecycle of the Automation Entities
• Configuration workflows and procedures are provided in How to Manage Automation Nodes.
• Guidelines on how to manage synchronous writing can be found at Best Practices for Automation Writing
Operations in the Opcenter Execution Foundation Development and Configuration Guide.
• Information on how to perform read and write operations at How to Read and Write on Automation Node
Parameter Values Operations in the Opcenter Execution Foundation Development and Configuration Guide.
2.4.1 What Is the Automation Gateway?

Automation is the term used to refer to low-level control systems identified by OPC servers, which are used in plants
for monitoring, supervisory control and automated control of the production process. To communicate with these
control systems, Opcenter EX FN uses the HMI RTIL Platform, which is a set of processes and services, installed with
Opcenter EX FN, that read data from the control systems and make it available for upper level applications.
In this document the HMI RTIL Platform is referred to as the Automation Gateway Server.
Automation Gateway Server relies on the following main components:
• Event Manager, which is the central manager process that hosts the process image (in HMI RTIL Platform, the
process image contains the values and the status of the activated nodes). Event Manager handles any messages
requesting or changing values within the process image, and it provides notifications on value changes to any
subscribed client applications.

System Apps
Automation App
• Data Manager, which is the central data management process that handles runtime configuration data and core
services (e.g Name and Localization services, the Tag Persistency).
• Common Plant Model (CPM), which is the process that manages automation nodes at runtime.
• REDU Manager, which controls all redundancy relevant actions. It communicates with the peer server and based
on its own and the peer error states it manages the system status and initiates a switch-over.
• DIST Manager, which establishes the connection with the other systems, exchanges identifications on all
systems, transmits messages between the systems.
• OPC Driver, which manages the communication with the OPC Server.
• OPC UA Service, which is a web service providing both the capability to browse the name space of the OPC
Servers and the possibility to check the connection during the configuration of the OPC UA channels.
The Automation Gateway Server and the related ports must be properly enabled and configured in the Opcenter
Execution Foundation Configuration Tool, either with the procedure described in Configuring the Engineering
Host or in Modifying the Environment Configurations of the Opcenter Execution Foundation Installation Guide.
Opcenter EX FN Unified Domain Model provides you with a specific data model, the Automation Gateway data
model, which allows you to interface with the automation layer.
The Automation data model relies on a set of entities (Automation Node Types and Automation Node Instances)
that can be used to model automation data sources, such as plant machines and tools, and a set of properties
(Automation Parameters) that must be configured to communicate with the control systems. This engineering layer
is represented by the Automation Gateway App.
When the engineering configuration in the Automation data model is finalized, you can activate this configuration
on the Automation Gateway Server. This operation aligns the engineering configuration of the Automation Gateway
App with the Operational Data domain, activates the automation node configurations to the Automation Gateway
Server, which includes the configuration files for a specific HMI RTIL Platform service (CPM) that manages the
automation nodes at runtime, and their connections with the configured OPC servers or PLC. The activation
procedure is achieved through a set of distributed, event-driven operations that either succeed or fail consistently.
If they fail, you can correct the engineering configuration and then force a reset.
2.4.2 What Are Automation Entities?

Automation entities are the entities used to configure and activate the automation layer integration in the
Automation App.
They are Automation Types, Automation Instances and Automation Channels, generated in the Master Data domain
and then activated to the Automation Gateway Server.

System Apps
Automation App
• Automation Node Types. Node types represent structured sets of data that can be connected to the
automation layer. These data structures can represent abstract equipment types, machines, tools, or any other
automation data grouping. They contain automation parameters.
• Automation Node Instances. These instances, based on Automation Node Types, map real-world plant objects,
such as machines, tools or sensors. Their main function is to model these plant objects and enable data
exchange with the field. Any changes made to Automation Node Types will be propagated to all related
Automation Node Instances.
• Automation Channels. These entities are used to define the channels through which the Automation Node
Instances will connect to the automation layer. A Channel represents a connection to a specific OPC Server or a
specific PLC and therefore identify the OPC driver to be used to establish the connection.
All these entities are activated to the Automation Gateway Server and are used to configure the data acquisition
files.
Moreover, Automation Node Instances are also copied to the Opcenter EX FN Operational Data domain in order to
be available for the other runtime entities that require a link to automation nodes.
Thanks to this separation between Automation Node Instances in the Master Data domain, and Automation Nodes
in the Operational Data domain, it is possible to make changes to the engineering configuration without stopping
runtime Automation Gateway Server.
What are the Automation Parameters

In order to integrate with the automation layer, the Automation data model applies a type/instance pattern.
The Automation Node Types contain the base properties, while the Automation Node Instances map the
automation layer tags connected through automation channel.
According to the type/instance pattern, the changes applied to the Automation Node Type properties are
automatically propagated to all the related Automation Node Instances.
The key element of the automation layer integration is the Automation Parameter.
Automation Parameters are Opcenter EX FN entities that specify the data acquisition channel (i.e. OPC, configured
in the Automation Channel entities), a set of address parameters that connect to tags in the source device (i.e.the
OPC server), the acquisition cycle interval as well as the smoothing mode.

System Apps
Automation App
The values retrieved from the source device tags are runtime values. They are not saved in the Opcenter EX
FN database, but in the Automation Gateway Server. It is consequently necessary to use specific APIs to perform
read and write operations on this data.
2.4.3 What Is the Lifecycle of the Automation Entities

In order to correctly align the configuration in Automation App and the Automation Gateway Server configuration,
the Automation Channels, Automation Node Types and Automation Node Instances apply a specific status
machine. You should be aware of this lifecycle in order to better understand the operations of approving and
activating entities, which are required after changes.
The statuses are:
• To Be Approved, the entity has not been approved yet and so it will not be activated to the Automation
Gateway Server.
• Approved, the entity is ready to be activated to the Automation Gateway Server.
• Dismissed, the entity has been deleted after it was already activated to the Automation Gateway Server. In this
scenario, the entity is temporarily put in the Dismissed status and it will be effectively deleted from the Master
Data domain and from the Automation Gateway Server (and also from the Operational Data, if applicable) only
after you have activated the configuration to the Automation Gateway Server.
• Pending, the entity is in the process of being activated to the Automation Gateway Server.
• Activated, the entity has been activated to the Automation Gateway Server.
2.4.4 What is the Automation Gateway Redundancy Support?

The OPC UA standard defines two main modes for Redundancy support: the Transparent and the Non-Transparent
mode.
Opcenter Execution Foundation supports both redundancy modes.
If the OPC UA Server is configured in the Transparent mode, the OPC UA Server exposes one single endpoint and it
internally manages the redundancy, which is actually is hidden from the client perspective. So the client, i.e. in our
case Opcenter EX FN, is not aware of how many servers there are in the redundancy set and if there is a switch from
one server to another, the client is not aware of it.
Compared to the Transparent mode, the Non-Transparent redundancy mode works in the opposite way, as it is
'visible' to the client. In this configuration mode, the client manages the connections to two different OPC UA
servers and it is the client that monitors the state of the connection with the active server. If there is an issue in the
communication with the active server, it switches to the second available OPC UA endpoint.
Non-Transparent Redundancy (NTR) support

Opcenter EX FN currently supports the hot(a) NTR mode.
Hot Servers are up and running and connected to the OPC UA Servers in parallel. Each server is autonomously
collecting data from the underlying system. Hot(a) means that a client is acquiring data only from the active OPC
UA server.
We recommend the usage of the source timestamp with NTR functionality.
HMI RTIL Platform makes use of the timestamps, provided by the periphery device and created locally, to reduce
the number of re-notified events during the redundancy switch and failover. OPC UA Client provides the
TimestampsToReturn configuration attribute, therefore you can configure the timestamp strategy which will be
associated with value changes. Using the periphery time introduces risk of data loss if non-centralized time sources
are used. If it is the case, usage of local time (TimestampsToReturn = 3(None)) is recommended. If the periphery

System Apps
Automation App
time is used, it is always recommended to keep the time settings of the HMI Station and periphery devices as close
as possible.
2.4.5 How to Manage Automation Nodes

The Automation App provides engineering pages, where you can manage Automation Nodes, which allow you to
communicate with the automation layer.
 To initialize the Automation App data, you cannot use the dbinit.xml file because it does not perform data
checks but you must follow the configuration workflow indicated below.
The integration scenario with the automation layer can be configured by executing the following steps.
Configuration workflow
1. Configure and approve the Automation Channels.
2. Configure and approve the Automation Node Types and add their Automation Parameters.
3. Configure and approve the Automation Node Instances and their Automation Parameters.
4. Activate Runtime Integration.
For each of the Automation entities (Channels, Types and Instances) you can choose which type of view you want to
see, by clicking the button Automation View Type in the relevant page and selecting from the drop-down menu
either of the following views:
• Current: the most recent details of the selected Automation entity
• Activated on Server: the latest details of the selected Automation entity activated on the Automation Gateway
Server.
 At the end of this configuration, you can create a custom App and implement UI pages for displaying and
setting Automation Parameter attributes. For more information, see How to Read and Write on Automation
Node Parameter Values in the Opcenter Execution Foundation Development and Configuration Guide.
2.4.5.1 Configuring Automation Channels

Automation Channels, through which Automation Node Instances connect to the field, must be configured and
approved before you create the Automation Node Type and Automation Node Instance.
Workflow
The steps required to configure an Automation Channel are as follows:
1. Create the OPC UA Automation Channel.
2. Approve the Automation Channel so it can then be activated to the Automation Gateway Server.
If you want to tune up the OPC UA driver runtime behavior, you can manually modify the OPC UA driver
configuration file.

System Apps
Automation App
 Security Configurations
If you want to configure a secure Automation Channel, see Hardening Automation Gateway Server in the
Opcenter Execution Foundation Security Concept.
For the OPC UA Automation Channel you can choose which type of view you want
Automation View
Type to see, by clicking Automation View Type in the relevant page and selecting
from the drop-down menu either of the following views:
• Current: the most recent details of the selected Automation Channel
• Activated on Server: the latest details of the selected Automation Channel
activated on the Automation Gateway Server.
In the Automation Channel page, you can see the list of addresses for the selected
Check Connection
Automation Channel and retrieve information about the connection status of the
Status
selected channel.
Approve To activate Automation Channels to the Automation Gateway Server, you must
complete the configuration and approve the Automation Channels.
Add Automation Channels are entities whose attributes are required to configure OPC
UA server connections in the Automation App.
The channel consequently makes it possible to connect an Automation Node
Instance to the field. To add a new Automation Channel , do as follows:
1. Click Automation Gateway Management in the side menu bar and click
Automation Channel.
2. In the Automation Channel page, click to set the attributes of the OPC UA
channel
Edit Automation Channels can be modified. You can change any previously defined
attributes except for the Channel Id and the Status.

System Apps
Automation App
Automation Channels can be deleted if they are not referenced in any Automation
Delete
Parameters defined in the Automation Node Instance and when they are not in
Pending or Dismissed status.
If you delete an Automation Channel that has already been activated to the
Automation Gateway Server, the entity will be temporarily put in Dismissed status.
It is effectively deleted from the Master Data domain and from the Automation
Gateway Server only after you have activated the runtime integration.
2.4.5.1.1 Creating Automation Channels for OPC UA Server Connection

Automation Channels are entities whose attributes are required to configure an OPC UA server connection in the
Automation App.
The Automation Channel makes it possible to connect an Automation Node Instance to the field.
Automation Channels support both the OPC UA Transparent and the OPC UA Non-Transparent Redundancy (NTR).
For more information, see What is the Automation Gateway Redundancy Support?
 For details on server endpoint and security-related parameters, refer to OPC Unified Architecture
specifications, in particular:
• Part 1: Overview and Concepts
• Part 2: Security Model
• Part 4: Services.
Procedure
1. Click Automation Gateway Management in the side menu bar and click Automation Channel.
2. In the Automation Channel page, click to add an OPC Channel.
3. Set the following attributes:
/Section
Connecti The type of connection, automatically set to OPCUA. Once the Automation Channel is created,
on Type the Connection Type value cannot be modified.
Id The unique identifier assigned to the Automation Channel. Once the Automation Channel is
created, the Id value cannot be modified. The only characters supported are alphanumeric
characters and underscore (_).
Name (Optional) The name assigned to the Automation Channel. The only characters supported are
alphanumeric characters and underscore (_).
Address 1 The URL address of the OPC UA server endpoint to be used for establishing the connection. For
example: opc.tcp://localhost:48010.

System Apps
Automation App
/Section
Enable By enabling or disabling this toggle button option, it is possible to enable/disable the OPC UA
Server server redundancy support, and configure an additional endpoint (i.e. Address 2, below). For
Redunda more information, see What is the Automation Gateway Redundancy Support?
ncy
Failover
 If you have migrated the Solution from any version prior to 4.2, the toggle button will
Mode be automatically disabled.
Address 2 Alternative URL address of the OPC UA Server to be used for redundancy, available only if the
Enable Server Redundancy Failover Mode option is enabled.
Identity The types of user authentication supported by the OPC UA server are:
Token
• Anonymous, without any authentication.
Type
• Username/Password, providing the credentials of an authenticated user.
User For the User Name/Password authentication type, you must insert the credentials that will be
Name required to authenticate on the OPC UA server.
and
Password
Security The security policy to be used to establish a secure channel with the OPC UA server. The
Policy possible options are:
• Basic128Rsa15
• Basic256
• Basic256Sha256
• None disables any security policy.
 Managing certificates
Depending on the OPC UA Server security policy in use, another procedure could be
required on the OPC UA server side in order to trust the client certificates on the
server.
In case of a redundant configuration, you must repeat the same trust procedure on
the redundant server.
By default, at the end of the Opcenter EX FN setup, the client certificate and its private
key are generated and saved, respectively, on each Foundation host, in the following
folders:
• %ProgramData%\Siemens\Automation\Device-Certificate-
Store\own\certs\OPCEXFN_WCCILopcua.der, and
• %ProgramData%\Siemens\Automation\Device-Certificate-
Store\own\private\OPCEXFN_WCCILopcua.key.pem
To renew the certificates you must run the AgwPostSetupConf.exe program, which
can be found in %SITUnifiedSystemRoot%bin, by passing the following argument
-p=UAFProject.

System Apps
Automation App
/Section
Message In case of a Security Policy different from None, you must choose how to establish a secure
Security channel with the OPC UA server. The possible options are:
Mode
• Sign
• SignAndEncrypt
• None disables any security mode.
Reconnec The time interval, in seconds, to establish a connection to the server. Default value is 0.
t Time (s)
TimeSta One of the possible timestamp recording modes:

mp Mode
• Client timestamp, to retrieve the timestamp of the OPCUA client.
• Source timestamp, to retrieve the timestamp from the field device (PLC).
• Server timestamp, to retrieve the timestamp from the OPCUA server.
• Source or Server timestamp, to retrieve the timestamp either from the source, if
available, or from the server.
Server
1. If you have applied a security policy (i.e. Security Policy different from None), click next
Actions
to the configured connection Address to retrieve the related OPC UA server certificate.
2. To test the connection reliability to the OPC UA server, click next to the configured
connection Address: a message will inform you about the result of the connection availability,
but it can be ignored to continue the creation process.
4. Save the changes.
 Connection remarks
• Bear in mind that there is a maximum number of Automation Node Instance Parameters that can be
activated. To retrieve more detailed information, see Checking the OPC UA Automation Channel
Status.
• When you check the connection, if you have applied a security policy (i.e. different from None), you
must have already acquired the certificate of the OPC UA server. Depending on the OPC UA Server
security policy in use, an analogous procedure could be required on the OPC UA server side in order to
trust the client certificates on the server. The OPC UA client certificate and private key used for the
check connection are the same configured for the channel (see details in table above).
2.4.5.1.2 Approving Automation Channels

Once you have completed their configuration, Automation Channels must be approved.
The status of each Automation Channel is visible in the grid on the Automation Channel page.
The Approve button is visible when:
• the Automation Channel has just been created,
• the Automation Channel has been modified.

System Apps
Automation App
If you have modified an Automation Channel that has been referenced in an Automation Node Instance, the
changes will be propagated to the Automation Node Instance. However, approval of the Automation Node Instance
will not be necessary again.
Prerequisites
If the Automation Channel is configured with Non-Transparent Redundancy, the addresses and the security
certificates must have been correctly inserted (otherwise the approval will fail).
Procedure
1. Click Automation Gateway Management in the side menu bar and click Automation Channel.
2. In the Automation Channel page, select the Automation Channel you want to approve and click Approve.
3. Confirm the operation to set the status of the configuration to Approved.
4. Once configured and approved, you can activate your Automation Channels to the Automation Gateway Server.
2.4.5.1.3 Modifying the OPC UA Driver Advanced Settings

You can change the configuration of some entries for OPC UA Client in the driver configuration file.
 The changes take effects only after restarting the AGW Server (for example using the Opcenter EX FN AGW
Node Monitor tool).
Procedure
1. Open the config.level file, which can be found in the following folder:
%SITUnifiedSystemRoot%Automation\config.
2. According to the provided description, you can only modify the following subset of entries in the [opcua] file
section:
Key Default Range Description

value
maxRequestQueueSize 1000 0– Defines the size of the request queue

for an OPC UA server.
65535
ignoreServerMaintenance Key Key commented or If uncommented and set to 1,

commented 1 the Maintenance value of the
ServiceLevel attribute, returned
during the connection with the OPC UA
server, is ignored.
2.4.5.1.4 Checking the OPC UA Automation Channel Status

In the Automation Channel page, you can view the list of the Automation Channels.
For each selected OPC UA Automation Channel, if you click the icon, you can see the list of addresses and
retrieve a message containing several information, such as:
• the status of the connection with the OPC UA Server
• the number of the Automation Node Instance Parameters which is ready to be activated

System Apps
Automation App
• the maximum number of Automation Node Instance Parameters supported by the OPC UA Server for the
selected Automation Channel.
Bare in mind that Address 2 is disabled if not previously configured.
Should you reach the maximum allowed number, you can change the current configuration in order to redistribute
the exceeding number of Automation Node Instance Parameters to other Automation Channels.
 Automation Node Instance Parameters maximum number

The maximum number for Automation Node Instance Parameters depends on the OPC UA Server provider
and it is not editable by the end user.
If this number, which is created for each channel, is greater than the maximum number set by the OPC UA
Server provider, the following error message is shown: "Number of Automation Node Instance Parameters
to activate = <> exceeds the maximum number supported on the selected channel = <>.".
Instead, if the constructor does not specify the maximum number of tags supported for each single
channel, when a check connection is performed, an error message is shown as follows: "The OPCUA Server
does not provide the maximum number of supported Automation Node Instance Parameters per channel. The
configuration might not work at runtime."
2.4.5.2 Configuring Automation Node Types and their Automation

Parameters
The Automation Node Type represents the base type of the Automation Node Instances.
Workflow
The configuration steps required to configure an Automation Node Type are as follows:
1. Create the Automation Node Types.
2. Specify the Automation Parameters (i.e. properties used to connect to the automation layer).
3. Approve the Automation Node Type so it can then be activated in the Automation Gateway Server, and to render
the related Automation Node Instances ready for approval.
Available Operations

System Apps
Automation App
For each of the Automation Node Types you can choose which type of view you want to
Automation
View Type see, by clicking in the relevant page and selecting from the drop-down menu either
of the following views:
• Current: the most recent details of the selected Automation Node Type
• Activated on Server: the latest details of the selected Automation Note Type
Approve To activate Automation Node Types, you must complete the configuration and approve
the Automation Node Types.
Add Automation Node Types are data structures in the Automation App that represent
abstract equipment types, machines, tools, or any other automation data grouping.
Automation Node Types have Automation Parameters, which contain the connection
information required to execute read and write operations on automation data.
You can either import Automation Node Types from an existing configuration or create
Automation Node Types from scratch.
Edit Automation Node Types can be modified if they are not in Pending or Dismissed status.
If you modify an Automation Node Type, which is in Approved or Activated status, all
the related Automaton Node Instances are automatically set in To Be Approved status
and need to be approved again.
Automation Node Types can be deleted if they are not in Pending or Dismissed status.
Delete
If you delete an Automation Node Type, any Automation Node Instances linked to it will
also be deleted.
When you delete an Automation Node Type that has already been activated in
the Automation Gateway server, the Automation Node Type will be temporarily put
in Dismissed status. The Automation Node Type is effectively deleted from the Master
Data domain and from the Automation Gateway Server after you have activated the
runtime integration.
Revert You can revert the configuration of a specific Automation Node Type in the Automation
Gateway to its last activated configuration to the Automation Gateway Server, as long
as the selected entity has been activated at least once.
If the revert operation completes successfully, all the modifications applied to the
selected Automation Node Type since the last activation will be deleted and replaced
with the details in the last activated configuration of the Automation Gateway.
2.4.5.2.1 Creating Automation Node Types

Automation Node Types are data structures in the Automation Gateway App that represent abstract equipment
types, machines, tools, or any other automation data grouping.

System Apps
Automation App
Automation Node Types have Automation Parameters, which contain the connection information required to
execute read and write operations on automation data.
You can either create Automation Node Types from scratch (as described in this page), or import Automation Node
Types from an existing configuration.
Procedure
1. Click Automation Gateway Management in the side menu bar and click Automation Node Type.
2. In the Automation Node Type page, click .
Id The unique identifier assigned to the Automation Node Type. Once

the Automation Node Type is created, the Id value cannot be
modified. The only characters supported are alphanumeric characters
and underscore (_).
Name (Optional) The name assigned to the Automation Node Type. The only
characters supported are alphanumeric characters and underscore
(_).
Description (Optional) Additional information on the Automation Node Type.

4. Click Save.
2.4.5.2.2 Adding Automation Parameters to Automation Node Types

Automation Parameters are properties that can be added to Automation Node Types in the Automation App.
They are saved in the Opcenter EX FN database as standard entity properties.
During the creation phase, you can specify only a subset of the Automation Parameter attributes. Specific binding
attributes for the Automation Parameters must be specified in the Automation Node Instance.
The Automation Node Type Parameter attributes (Data Type and Is an Array) are inherited by the related
Automation Node Instances. Their values cannot be overwritten within the Automation Node Instance Parameter
configuration.
 Any changes applied to the Automation Parameters of an Automation Node Type will be propagated to the
related Automation Node Instances, which will need to be approved again.
Procedure
1. In the Automation Node Type page, select the Automation Node Type.
2. In the Parameters tab, click .
3. Set the following Automation Parameter attributes:

System Apps
Automation App
Id The unique identifier assigned to the Automation Parameter, for example

Speed. Once the Automation Parameter is created, the Id value cannot be
modified. The only characters supported are alphanumeric characters and
underscore (_).
 If the Automation Node Type Parameter will be used as source for

the Signal App, the value of its Natural identifier can
contain uppercase and lowercase letters, digits and
'_' (underscore). The starting character can be uppercase and
lowercase letter or '_' (underscore). It cannot match with C#
keywords. For a list of keywords, see Reserved Keywords in
Opcenter Execution Foundation Development and Configuration
Guide.
Is an Array If selected, the Automation Parameter will be an Array.
Data Type The data type of the Automation Parameter. For the possible data types, see
Automation Parameter Data Types. Depending on the Data Type you
select, the options of the Smoothing Mode of the Automation Node
Instance, will be enabled or disabled. Once the Automation Parameter is
created, the Data Type cannot be modified.
4. Click Save. The Automation Node Type Parameter is created.
2.4.5.2.3 Automation Parameter Data Types

The following tables provide the Automation Gateway Server supported data types, with the corresponding C#
types and OPC supported types, and the possible related conversions.
Automation Gateway Server Data Types

System Apps
Automation App
(*) The Project Studio column indicates types that must be used in Opcenter EX FN and in the Apps that use
Opcenter EX FN.
(*1) All DateTime values are written on the Automation Gateway Server in UTC format. There are two types of
DateTime values, which either represent the Timestamp of the Automation Parameter value or the DateTime of the
Automation Parameter value itself (if defined as a DateTime data type).
The Timestamp is always expressed in UTC format and cannot be changed by the user as it represents the time
when the value was written on the Automation Gateway Server. The DateTime of the Automation Parameter value
is also written in UTC format, even if the method that was used to write it (AutomationWrite) expressed the
DateTime in a local time format.
(*2) If the parameter value is set to a value of decimal type, you must perform an explicit cast to avoid a “type
mismatch exception” when the AutomationWrite() method is called at runtime. As in the following code example:
Var MyEq;
// some code to get MyEq
// the following line of code shows how to set the value of a parameter of type
"Real" with the value of an argument of type "decimal"
MyEq.Parameters["RealParameter"].value =
decimal.ToSingle(MyCommand.decimal_argument);
(*3) You can use compatible types inside reading operations without any adjustments while inside writing
operations you should always assign the required values to the range of the target type because the compatible
types exceed the value they must represent.
(*4) The supported value range changes to the value range of the type Decimal in the following cases:
• When the Automation Parameter is configured in the Automation Source property of the rule;
• When the value of the Automation Node Parameter is assigned to a command or entity property.
Automation Gateway Server conversions

System Apps
Automation App
The value of an Automation Parameter can be set to a value of the same type or to a value of a compatible type. The
following table summarizes the compatibility between the types:
You can apply conversions on any of the Automation Gateway Server data types with some limitations, documented
in the following table.
The abscissa of the table contains the conversion target type while the ordinate contains the type you are trying to
convert. For all the required conversions, a check on the dimension is performed and in certain cases an error is
returned (for example, if you try to convert an Int16 to a Double).
The table uses the following conventions:
• R: The conversion is performed if the value does not exceed the destination type range (e.g. if a Byte ranges from
0 to 255, you cannot convert 256 from Integer to Byte);
• I: Implicit (C-style) conversion;
• T: If the value is greater than 0, the function returns True. Otherwise it returns False.
Contents for Automation Parameter Data Type Conversions
The conversion of a LReal type to Integer (Int, DInt, LInt) applies the following rounding functions:
• if the decimal ranges from 1 to 4, the integer is rounded down (e.g. 1.39 is rounded to 1)
• if the decimal ranges from 5 to 9, the integer is rounded up (e.g. 1.51 us rounded to 2)
If the LReal is converted to Byte, only the integer part is converted (while the decimals are lost).
2.4.5.2.4 Approving Automation Node Types

Once you have configured the Automation Node Type, you must approve it before you can activate it to the
Automation Gateway Server.
The status of each Automation Node Type is visible in the Overview tab.
Automation Node Types must be approved if:

System Apps
Automation App
• the Automation Node Type has just been created or modified,

• its Automation Parameters have been added, modified or deleted (in this case, also the Automation Node
Instances must be approved as well).
Procedure
1. Click Automation Gateway Management in the side menu bar and click Automation Node Type.
2. In the Automation Node Type page, in the Overview tab, do either of the following:
• select the Automation Node Type you want to approve, click and then either of the following:
• Type, to approve just the selected Automation Node Type
• Type and Instances, to approve the selected Automation Node Type together with all its
• do not select any Automation Node Types and click the following:
• Approve all Automation Node Types and Instances, to approve all the Automation Node
Types in To Be Approved status, together with all their Automation Node Instances.
3. Confirm the operation to set the status of the configuration to Approved.
Result
The status of the approved entities is set to Approved.
If some entities are not approved they remain in status To Be Approved and a warning message is displayed.
For detailed information on the failure reasons, refer to the Trace Viewer.
2.4.5.3 Configuring Automation Node Instances and Their Automation

Parameters
You can create Automation Node Instances starting from existing Automation Node Types from which they will
inherit the Automation Parameters. This is irrespective of whether the Automation Node Types have been approved
or not.
Workflow
The configuration steps required to configure an Automation Node Instance are as follows:
1. Create the Automation Node Instances.
2. Set the Automation Parameter Attributes to establish the connection with the automation layer.
3. Approve the Automation Node Instance so it can then be activated in the Automation Gateway Server.

System Apps
Automation App
For each of the Automation Node Instances you can choose which type of view you want
Automation
View Type to see, by clicking Automation View Type in the relevant page and selecting from
the drop-down menu either of the following views:
• Current: the most recent details of the selected Automation Node Instance
• Activated on Server: the latest details of the selected Automation Node Instance
Approve Once you have configured the Automation Node Instance, you must to approve it before
you can activate it to the Automation Gateway Server.
The status of each Automation Node Instance is visible in the Overview tab.
Add Automation Node Instances, based on Automation Node Types, map and model real-
world plant objects, enabling data exchange with the field.
Any changes made to Automation Node Types will be propagated to all related
You can either create an Automation Node Instance from scratch or copy an existing one,
which can be in any status. The new Automation Node Instance will be in to Be
Approved status.
Edit You can modify Automation Node Instances if they are not
in Pending or Dismissed status.
You can delete Automation Node Instances if they are not

Delete
in Pending or Dismissed status.
When you delete an Automation Node Instance that has already been activated to
the Automation Gateway Server, the Automation Node Instance will be temporarily put
in Dismissed status. The Automation Node Instance will be effectively deleted from the
Master Data domain and from the Automation Gateway Server only after you have
activated the runtime integration.
Revert You can revert the configuration of a specific Automation Node Instance in the
Automation Gateway to its last activated configuration to the Automation Gateway
Server, as long as the selected entity has been activated at least once.
If the revert operation completes successfully, all the modifications applied to the
selected Automation Node Instance since the last activation will be deleted and replaced
with the details in the last activated configuration of the Automation Gateway.
2.4.5.3.1 Creating Automation Node Instances

Automation Node Instances, based on Automation Node Types, map and model real-world plant objects,
enabling data exchange with the field.
Any changes made to Automation Node Types will be propagated to all related Automation Node Instances.

System Apps
Automation App
You can either create an Automation Node Instance from scratch or copy an existing Automation Node Instance,
which can be in any status. The new Automation Node Instance will be in To Be Approved status.
 The Automation Channel is managed in Automation Node Instance instead of managing it for each
Automation Node Instance Parameter. Consequently, all parameters will be bound to the same
Automation Channel.
While changing the Channel Id in the Edit Automation Node Instance screen, you can maintain or delete the
binding details of the parameters by managing the Maintain Parameter Binding Details checkbox.
Creating an Automation Node Instance from scratch

1. Click Automation Gateway Management in the side menu bar and click Automation Node Instance.
2. In the Automation Node Instance page, click .
Automation Node Type The Automation Node Type associated to the Automation Node
Instance. Once the Automation Node Instance is created,
the Automation Node Type cannot be modified.
Id The unique identifier assigned to the Automation Node Instance.

Once the Automation Node Instance is created, the Id value
cannot be modified. The only supported characters are
alphanumeric and underscore (_).
Name (Optional) The name assigned to the Automation Node Instance.

The only characters supported are alphanumeric characters and
underscore (_).
Description (Optional) Additional information on the Automation Node

Instance.
Channel Id (Optional) The unique identifier of the Automation Channel used

to communicate with the automation layer.
4. Click Save.
Copying an Automation Node Instance

2. In the Automation Node Instance page, select the Automation Node Instance you want to copy and click .
3. In the Copy Automation Node Instance panel, the source Automation Node Instance and the Automation Node
Type to which it is associated are displayed, enter a unique identifier to identify the new Automation Node
Instance.
4. Modify the name and description for your new Automation Node Instance if required.
5. Click Save. The new Automation Node Instance will be set to To be Approved status.

System Apps
Automation App
2.4.5.3.2 Setting Automation Parameter Attributes for Automation Node

Instances
After Automation Parameters have been added to Automation Node Types, you must configure specific Automation
Parameter attributes in the Automation Node Instances. Automation Parameter attributes are required to connect
the Automation Node Instance to the field. For OPC UA Channels this operation can be performed either from
scratch, as described below, or in assisted mode.
The Automation Node Instance Parameter inherits a set of attributes (Data Type and the Scalar or Array parameter
type) from the related Automation Node Type and these attributes cannot be overwritten.
 Automation Node Instance Parameters are designed to override their corresponding Automation Node
Type parameters.
Consequently if no override operations are performed, no Automation Node Instance Parameters are
created.
Acquisition Mode and Smoothing Mode

Some of these Automation Node Instance attributes relate to the Acquisition Mode and Smoothing Mode:
• The Acquisition Mode allows you to choose ways where values are acquired from the automation layer. This can
be every time a value changes (On Change) or on a continuous basis (Cyclic Continuous). In latter case, the
frequency of acquisition is then set by selecting one of the proposed values for the Acquisition Cycle attribute.
• Smoothing acts like a server-side filter, which reduces the number of notifications sent to subscribers when
values change. Smoothing configured for an Automation Node Parameter is valid only for values read from
peripheral addresses. No smoothing is applied to values sent to peripheral addresses for write operations.
Procedure
1. In the Automation Node Instance page, select the Automation Node Instance for which you want to set the
Automation Parameter attributes.
2. In the Parameters tab, select the required Automation Parameter and click .
3. In the Edit Automation Node Instance Parameter panel, set the required attributes (described in the following
table) . Click Save.
Id The unique identifier assigned to the Automation Parameter. This

field is read-only.
Is an Array If selected, the Automation Parameter will be an Array. This field is

read-only.
Data Type The data type of the Automation Parameter. This field is read-only.
Channel Id The unique identifier of the Automation Channel is used to

communicate with the automation layer. This field is read-only.

System Apps
Automation App
Address Type (Only for OPC UA Automation Channel Type) The type of the address
used to specify an item in the address space of an OPC UA server. The
available options are:
• NodeId
• BrowsePath
Address The address of the data item to connect to, for OPC UA Channels it is
the identifier of an item in the address space of an OPC UA server.
Acquisition Mode The mode in which the acquisition will take place. The available
options are:
• CyclicContinuous: the required data is retrieved at intervals
selected under Acquisition Cycle Id.
• OnChange: the required data is retrieved whenever any changes
occur. If selected, the Acquisition Cycle Id attribute is disabled.
Acquisition Cycle Id (Only for the CyclicContinuous Acquisition Mode) The unique
identifier of the Acquisition Cycle. The required data is retrieved at
the intervals set by this attribute. The possible options are:
• 100 milliseconds
• 1 second
• 2 seconds
• 5 seconds
• 10 seconds
• 1 minute
• 10 minutes
• 15 minutes
Smoothing Mode How smoothing rules will be applied. The possible options are:
• None, no smoothing mode will be applied.
• Value, if the original value changes by more than the specified
Delta Value, then the value is not smoothed, but is saved as the
original value. This is enabled only for numeric Data Type.
Depending on the Data Type you selected in the related Automation
Node Type, these attributes will either be enabled or disabled.
Delta Value The value to be applied for value-dependent smoothing. If you

select None as Smoothing Mode, this attribute is disabled.
Viewing Automation Parameter attributes

To view the attributes of an Automation Parameter, select the Automation Parameter and click .

System Apps
Automation App
2.4.5.3.2.1 OPC UA Address Configuration Details

During the configuration of the Automation Node Instance you set the address type used to specify an item in the
address space of an OPC UA server. The following values are supported:
• Node Id
• Browse Path
The mapping between the OPC data types and the Automation Gateway Server data types is documented below.
Node ID
In OPC UA, every entity in the address space is a node. To uniquely identify a Node, each node has a NodeId, which
is always made up of three elements: NamespaceIndex, IdentifierType and Identifier.
The format of the string is:
ns=<NamespaceIndex>;<IdentifierType>=<Identifier>
Field Description
NamespaceIndex Integer index that identifies the namespace. If the index is 0, then the
following clause is entirely omitted:
ns=0;
IdentifierType The format and data type of the Identifier. The possible values are:
• i: NUMERIC (UInteger)
• s: STRING (String)
• g: GUID (Guid)
• b: OPAQUE (ByteString)
Identifier The identifier for a node in the address space of an OPC UA server. It is
encoded as string. The identifier is formatted using the XML data type
mapping for the identifier type.
Note that the identifier may contain any non-null UTF8 characters
including whitespace.
Examples:
ns=2;s=MyValue
where the namespace index is 2, the identifier type is string.
i=2045
where the namespace index is 0 (therefore it is omitted) and the identifier type is numeric.
Browse Path

System Apps
Automation App
The browse path is typically a sequence of Browse Names separated by / (forward slash). The Browse Name is a
qualified name with the following structure:
[<NamespaceIndex>:]<String>
Field Description
NamespaceIndex (Optional) Integer index that identifies the namespace. This is the index
of the namespace in the local Server’s namespace array. If the
namespace prefix is omitted, then the namespace index 0 is used.
String The text portion of the qualified name.

Example:
"/Factory/2:East/2:Boiler1/2:FC1001/2:Measurement"
The & sign character is the escape character. It is used to specify reserved characters that appear within a Browse
Name. A reserved character is escaped by inserting the & in front of it.
Examples of Browse Names with escaped characters are:
Received browse path name Resolves to
“&/Name_1” “/Name_1”
“&.Name_2” “.Name_2”
“&:Name_3” “:Name_3”
“&&Name_4” “&Name_4”
 For details on the Browse Path BFN definition, refer to OPC Unified Architecture specifications, in
particular to Part 4: Services specification (Annex A2).
2.4.5.3.2.2 Setting Automation Parameter Attributes for OPC UA Automation

Node Instances
After creating the automation node instances, it is necessary to set the automation parameter attributes to
establish connection with the OPC UA server. This operation can be performed either from scratch, or in assisted
mode, as described below.
Procedure
1. In the Automation Node Instance page, enable the assisted mode activating the Smart Binding button.
2. The Automation Parameters tab on the left side of the page displays a tree list with the existing instances
grouped by type, click the checkbox corresponding to the parameter of interest: the Configuration panel on the
right side of the page displays information regarding the parameter on the Current tab.
 The Automation Parameters are highlighted in bold when bound with the OPC UA attribute, and vice-
versa.

System Apps
Automation App
3. Select the Automation Node Instance followed by the unique identifier of the Automation Channel (used to
communicate with the automation layer) from Channel Id drop-down box, and manage the Maintain
Parameter Binding Details checkbox to maintain or delete the binding detail of the parameters. Click .
Upon saving the Channel information, the Channel Id of the selected Instance parameters will be updated.
4. Open the tree list available below the drop-down list box, and select the check box corresponding to the OPC UA
attribute to be linked to the parameter: the Configuration panel opens automatically; the Binding tab with all
the binding information to be saved in the future is displayed.
5. If necessary, modify the provided values. For detailed information on available parameters, see Setting
Automation Parameter Attributes for Automation Node Instances.
 Saving operations
The saving operations can be performed in two ways:
• In the Channels panel, mouse over the OPC UA attribute and click the adjacent icon that
appears: the selected configuration contains the binding information of the OPC UA attribute
saved with the default values.
• In the Channels panel, click the checkbox of the desired node to display the Binding tab with
its details, optionally edit the default values and then click Save to confirm.
6. Select any Automation Parameter bound with the OPC UA attribute, the system automatically opens the OPC UA
tree list; the bounded OPC UA attribute is selected and displays the number of Automation Parameters that are
bounded with the OPC UA attribute along with button.
 If the selected Automation Parameter is bound with an OPC UA attribute which has aliases, then the
first occurrence of that OPC UA attribute is selected automatically.
7. Click to view the list of Automation Parameters (displayed in the format: {{Automation Node Instance
Id}}.{{Parameter Id}}) bound with OPC UA attribute, and click on any of the listed Automation Parameters
to view them in the Automation Parameter tree list.
Applying filters to the Automation Node Types

When many Automation Node Types have been created, it may be useful to filter the list according to specific
criteria. To do so, perform the following operations:
1. In the Automation Parameters panel, select one of the following fields:
• Node Type
• Node Type Parameter
• Node Instance
2. Enter the filter value in the adjacent box .
3. Click the filter funnel icon next to the textbox: by default, the tree list displays 50 results. If needed, enter
the desired number in the Number of Instances shown box and click .
2.4.5.3.3 Approving Automation Node Instances

Once you have configured the Automation Node Instance, you must approve it before you can activate it to the
The status of each Automation Node Instance is visible in the Overview tab.
Prerequisites

System Apps
Automation App
• The Automation Node Type, which is related to the current Automation Node Instance, must have been already
approved.
• The Automation Node Instance has just been created or it has been modified.
• The Automation Node Type, which is related to the current Automation Node Instance, or its Automation
Parameters have been added/modified/deleted.
Procedure
2. In the Automation Node Instance page, in the Overview tab, do either of the following:
• select the Automation Node Instance you want to approve, and click to approve the selected
Automation Node Instance.
• do not select any Automation Node Instance and click to approve all Automation Node Instances
that are in To Be Approved status.
3. Confirm the operation.
Result
The status of the approved entities is set to Approved.
If some entities are not approved they remain in status To Be Approved and a warning message is displayed.
For detailed information on the failure reasons, refer to the Trace Viewer.
2.4.5.4 Activating Runtime Integration

The activate operation deploys all the configurations carried out in the Automation App to the Operational Data
domain and downloads them in the Automation Gateway Server.
Once the Automation Nodes have been deployed to the Operational Data domain, they can be referenced by
custom operational entities in order to perform specific custom business logic.
To correctly execute the activate operation, you must first activate the Automation Channels and then the
Automation Node Types and Instances.
According to the configuration that was previously downloaded, the system could perform two types of activation:
• Delta activation, regarding only the changed items,
• Full activation, regarding all items.
Delta vs Full activation

When you perform an activation of either the Automation Channels or the Automation Node configuration, the
system first tries to carry out a Delta download. 'Delta' means that the system reads the engineering configuration
which is currently approved in the Automation App, compares it to the configuration that is currently available on
the Automation Gateway Server and then downloads only the modified items onto the Automation Gateway
Server.

System Apps
Automation App
If the Delta activation fails, you can perform a Full activation. The Delta could fail for example because the driver
cannot correctly manage particular changes of the Automation Node configuration. For example, if you swap the
Node Ids of two Automation Node Parameters. For example this is due to a limitation of the current version of the
OPC UA driver and will be addressed to a future version.
When the Delta activation fails, you are notified of the failure and the Automation App asks you if you want to
proceed with a Full activation, which should solve the problem and successfully complete the operation. 'Full'
means that all the configurations carried out in the Automation App are activated on the Automation Gateway
Server, regardless of what was previously downloaded.
 If you reactivate a node instance after assigning at least one of its parameters to another channel type, the
system automatically performs a Full download without notifying you.
Allowed operations
While the activate operation is still in progress, the entities in To Be Approved status can be modified as well as
new entities can be created.
Prerequisites
• All the Automation Channels and Automation Node Types that you want to activate must be in
either Approved or Dismissed status, otherwise if they are in To be Approved status they will be ignored during
the activation procedure.
• The Automation Node Instances that you want to activate must be either in Approved or Dismissed status,
otherwise if they are in To Be Approved status they will be ignored during the activation procedure.
• The Automation Channels must be activated before you can activate the Automation Node Instances to which
they refer.
 If there is at least one Automation Node Type with its Automation Node Instances previously activated, if
you modify the Automation Node Type and approve it but you do not approve its Automation Node
Instances (they are still in To Be Approved status) the activation fails, and you must re-approve the
Automation Node Instances before proceeding.
Activating the Automation Channels

If you have created new Automation Channels or if you have modified them:
1. Click Automation Gateway Management in the side menu bar and click Home.
2. In the Automation Gateway Management page, click .
3. From the drop-down list select Channels and then confirm the operation.
Activating the Automation Configuration (Automation Node Types and Instances)

2. In the Automation Gateway Management page, click .
3. From the drop-down list select Types and Instances and confirm the operation.

System Apps
Automation App
 If an operation on the Automation Gateway Server is still in progress, an error message is displayed. Wait
until the operation has completed and then repeat the activation.
Result
The ActivateFinished event and the ActivateFinishedSignal signal (see ATN_MS Functional Block in the Opcenter
Execution Foundation Development and Configuration Guide).
are fired to notify that the operation has been executed.
 Signal Rules
If you have activated any configuration changes that could create inconsistencies with the deployed Signal
Rules, Signal Rules will fail and you must re-align them with the activated Automation configuration.
2.4.5.5 Exporting Automation Node Master Data

You can export the configuration data of your automation nodes in a CSV format file, which contains:
• Automation Channels
• Automation Node Types with their automation parameters
• Automation Node Instances with their automation parameters.
You can only export the Automation Channels, Automation Node Types and Automation Node Instances which
are in the following statuses: Approved, Activated or Pending.
Procedure
2. In the Automation Gateway Management page, click and confirm the operation to export the current
configuration.
3. Click Save. The exported file will be saved in the download folder which is configured in the settings of your
browser and will be named AutomationConfiguration_yymmddhhmm.csv.
 Bear in mind that if you export array parameters of string data type with default or initial values containing
semicolon as element value of an array, these semicolons will be replaced with the character %3B during
the export operation.
2.4.5.6 Importing Automation Node Master Data for Automation Artifacts

You can import a configuration file in CSV format as long as it conforms to the required format. It must contain:
• Automation Channels
• Automation Node Types with their automation parameters
• Automation Node Instances with their automation parameters.
Automation Gateway Server is case-sensitive. You must always use the same case that you used while configuring
the Automation Node entities.
When you try to import a file containing a new Automation configuration, various checks are performed to ensure
that the imported file contains consistent data. If any errors occur during the import checks, the system executes a

System Apps
Automation App
rollback, without persisting the changes. All the invalid entries are logged by the Trace Viewer. For more details,
see Logging and Analyzing Application Traces with Trace Viewer in the Opcenter Execution Foundation Development
and Configuration Guide.
After the import, all the imported entities are set to Approved (except for a specific configuration which requires to
manually enter authentication credentials, as described below in the page). Consequently, after the import, you will
need to activate the new configuration.
 Import CSV file generated prior version 4.0

• Automation Channel:
• Importing Automation Channel of S7 type is not supported.
• Automation Node Type and Parameters: If the Automation Type Parameter contains a value for any
of the below listed properties; the value is removed and the status of corresponding Automation Node
Type is set To be Approved. Consequently, the status of all the Automation Node Instances associated
with the same Automation Node Type is set To be Approved.
• IsStatic
• IsInternal
• IsPersistent
• MinValue
• MaxValue
• MaxLength
• ParameterValue (for scalar parameter type)
• ParameterValues (for array parameter type)
• Automation Node Instance and Parameters:
• If the Automation Node Instance Parameter is bound with the Automation Channel of S7 type,
the parameter is not imported.
• If the Automation Node Instance Parameter is configured as static or internal, the parameter is
not imported.
• If the parameters of an Automation Node Instance are bound with different Automation
Channels, no parameters are imported.
• If the Automation Node Instance Parameter contains a value for ParameterValue,
ParameterValues or DeltaTime properties, the value is removed.
• If the Automation Node Instance Parameter contains a value for the SmoothingMode property
which excludes None or Value, it is set to None automatically.
In all the cases, the status of corresponding Automation Node Instance is set To be Approved.
Any change performed automatically by the Import procedure can be viewed in the Trace Viewer.
 To prevent unauthorized users from tampering with the exported packages, strict measures should be
taken to guarantee that the exported information is correctly and securely stored until it is re-imported.
Available import operations

You can import artifacts in two modes

System Apps
Automation App
Import with Reset This operation imports the new configuration by first removing the
existing configuration and then importing the new one. This
operation also resets the server configuration and therefore you
will need to activate the configuration of channels and then the
configuration of types and instances. The activation will be full.
Import with Replace This operation first reverts the master data configuration to the last
activated configuration and then imports the new
configuration. This import type does not directly delete any model
objects that are in Active state, but sets them to
Dismissed (Dismissed objects can always be reactivated, if
needed). Objects that have never been activated are deleted.
In the Import with Replace operation, the revert phase performs a
check on the status of the master data objects:
• If the entities are in Approved, To Be Approved or Dismissed
status, the system reverts them to the last activated version.
• If the entities are in Active state, their version is not reverted.
After the revert, the import operation compares the master data
objects with the import file information and then:
• If an entity exists in the data model but is not within the import
file, this entity is set to Dismissed.
• If an entity exists both in the master data configuration and in
the file, a new version of the entity is created and it is set to
Approved.
• If an entity does not exist in the master data configuration, but
it exists in the file, the new entity is created and set to
Approved.
• If an entity is in Pending, the system returns a warning
message which suggests you to perform a Reset.

System Apps
Automation App
Import operation on Automation Both import options apply to Automation Channels. Nevertheless
Channels the following constraints must be taken into account:
Automation Channels can be imported only from version 2.2.
Consequently:
• If the configuration file does not contain the
#AutomationChannels section (i.e. the file was either exported
from SIMATIC IT UAF 2.1 or it was manually created in
compatibility with SIMATIC IT UAF 2.1), the Channels that are
present in your configuration will not be deleted, regardless of
the import type performed.
• If the import file contains the #AutomationChannels section:
• in case of Import with Reset operation, the system
overwrites the existing data model with the import file
information. If the section is empty, the existing
Automation Channels will be deleted.
• in case of Import with Replace operation, the
Automation Channels will be reverted and then
overwritten as the other entities. If the section is empty,
the system will revert the Channels to the last activated
version and then will set them to Dismissed.
• If you import with replace a new configuration which does not
contain Automation Channels, but your existing configuration
already contained Channels that were previously associated to
Automation Node Instances and activated, you need to reset
the environment to successfully complete the import
operation.
 Only for configurations that include OPCUA automation

channels:
• To import a configuration with Username\Password
IdentityTokenType, specify the username in the CSV
file but do not enter the password. Then, after the
import, complete the Channel configuration
by editing the just imported Channel in the
Automation Channel page and insert the required
password. Then, approve and activate the Channel (at
the end of the import of this configuration type, the
Automation Channel is in To Be Approved).
• If the Automation Channel you are importing via file
already exists in your configuration, with the same
IdentityTokeType, and the same user name, the
existing password is maintained. If the imported user
name is different, the password is removed from the
configuration and it must be manually entered in the
Automation Channel page.

System Apps
Automation App
• If the Automation Channel you are importing is
configured with Security Policy and Message
Security Mode different from None and without any
Certificates either for the Address 1 or Address 2 (if
Server Redundancy Failover Mode is enabled),
when the Import operation is completed, the
Automation Channel is in To Be Approved. Complete
the Channel configuration by editing the just
imported Channel in the Automation Channel page
and retrieving the needed certificate(s).
• If Address 2 is missing, the configuration will be
imported assuming that Server Redundancy
Failover Mode is disabled.
Procedure
2. In the Automation Gateway Management page, click and then choose one of the following:
• Import with Reset
• Import with Replace
3. In the Import Configuration panel, browse to the CSV configuration file you want to import.
4. Click Import.
Configuration file structure description

The configuration file is divided into sections, one for each of the following automation entities: Automation
Channels, Automation Node Types, Automation Node Type Parameters, Automation Node Instances and
Automation Node Instance Parameters.
The beginning of the section is defined by the hash (#) character at the beginning of the row, such as
#AutomationNodeType. All the values are enclosed within double quotes (").
The next row of the section gives the header title of the columns relevant to the configuration of that section. In
particular, the AutomationNodeTypeRef property is reported in each section as it is the Id of the Automation Node
Type which links the related automation instances and AutomationNodeInstanceRef is reported in the section
AutomationNodeInstanceParameter as it is the Id of the Automation Node Instance which links the related
Automation Node Instance Parameters.
The subsequent rows detail the actual values of the properties for each of the entities belonging to the individual
sections.
The comma (,) character is used as the separator and values are enclosed within double quotes ("). If your value
contains double quotes, you must duplicate the double quotes as escape sequence, for example to write "Filler 1
"Enhanced"" you must write "Filler 1 ""Enhanced""".
LReal and Real (floating point) parameter values can use either a comma (,) or a dot (.) as the decimal separator.
The thousands separator is not accepted.
For boolean parameters, the allowed values are True or False.

System Apps
Automation App
 In case of string arrays with semicolon separators between the values you must replace it with
the character %3B to import parameter values.
Example of configuration file in CSV format
"#AutomationChannels"
"Id","Name","ConnectionType","IdentityTokenType","Address","Address2",
"SecurityPolicy","MessageSecurityMode","ReconnectTime","TimeStampMode","UserName",
"ServerCertificate","ServerCertificate2","ServerRedundancyFailoverMode"
"OPCUAChannel1","OPCUAChannel1","OPCUA","Anonymous","opc.tcp://host1:48010","opc.tcp;
//host2:48010","None","None","0","Server","","","","HotA"
"#AutomationNodeTypes"
"Id","Name","Description"
"ANT1","ANT1","ANT1"
"#AutomationNodeTypeParameters"
"AutomationNodeTypeRef","Id","DataType","ParameterType"
"ANT1","ArrayInt","Int","Array"
"ANT1","ScalarInt","Int","Scalar"
"#AutomationNodeInstances"
"AutomationNodeTypeRef","Id","Name","Description","ChannelNId"
"ANT1","NodeInst1","NodeInst1","NodeInst1","OPCUAChannel1"
"#AutomationNodeInstanceParameters"
"AutomationNodeInstanceRef","Id","ChannelNId","AddressType","Address",
"AcquisitionMode","AcquisitionCycleNId","SmoothingMode","DeltaValue"
"NodeInst1","ArrayInt","OPCUAChannel1","NodeId","ns=2;s=Demo.Static.Arrays.Int16",
"OnChange","","None",""
"NodeInst1","ScalarInt","OPCUAChannel1","NodeId","ns=2;s=Demo.Static.Scalar.Int16",
"OnChange","","None",""
2.4.5.7 Migrating Automation Node Master Data

When you are migrating to Opcenter Execution Foundation 4.0, you have to migrate the Automation Gateway
Configuration defined in the prior version by clicking Migrate button. Once the migration is completed, this
button is not displayed.
As some of the Automation Gateway Entity related properties are obsolete (see Obsolete Functionalities in the
Opcenter Execution Foundation Release Notes, Automation Gateway section, for the complete list), some
information are lost during migration. To save the original data, the system allows you to export the configuration
before migration.
Procedure
1. Click Automation Gateway Management in the side menu bar and click Automation Gateway
Administration.
2. In the Automation Gateway Administration page, click . You are prompted with an alert message
for Export and Migrate, Migrate Only and Cancel buttons.

System Apps
Automation App
3. Click Export and Migrate to export the existing configuration into the CSV file and then migrate it. The exported
file will be saved in the download folder (configured in the settings of your browser) and will
be named AutomationConfigurationBeforeMigrate_yymmddhhmm.csv.
 • The Delta Time property of the Automation Node Instance Parameter will not be exported with
the other configuration as it is removed while migrating to Opcenter Execution Foundation 4.0.
• In case the export is not necessary, a warning message is displayed to Abort or Continue the
migration process.
4. Click Migrate Only to migrate the existing configuration without exporting the data.
2.4.5.8 Resetting the Automation Gateway Server environment

You can reset the configuration of the Automation Gateway Server when there are inconsistencies between the
Automation Gateway and Automation Gateway Server, such as when data is not correctly activated, upon an
activation action the status of your entities remains Pending and therefore you are not able to modify them within
the Automation Gateway.
If the reset operation completes successfully, then:
• all the entities in the Automation Gateway that were in Pending status are reverted to their previous Approved
or Dismissed status.
• the Automation Gateway Server will completely reset the current configuration when the
next Activate command is requested by the Automation Gateway, and consequently you have to activate the
Automation Channels and then the Automation Node Types and Instances.
Procedure
2. In the Automation Gateway Management page, click and confirm the operation.
3. To use the configuration at runtime, re-activate the entire configuration (i.e. Automation Channels first and then
the Automation configuration). If the Reset operation is still in progress on the Automation Gateway Server, an
error message is displayed, and you must wait until this operation has completed before re-activating the
configuration.
2.4.5.9 Reverting the Automation Gateway Configuration

You can revert the configuration of a specific Automation Node Type or Automation Node Instance in the
Automation Gateway to its last activated configuration to the Automation Gateway Server, as long as the selected
entity has been activated at least once.
If the revert operation completes successfully, all the modifications applied to the selected Automation Node Type
or Automation Node Instance since the last activation will be deleted and replaced with the details in the last
activated configuration of the Automation Gateway Server.

System Apps
Automation App
 • If you do a revert on an Automation Node Type, all its related Automation Parameters, Automation
Node Instances and their Automation Parameters will also be affected (reverted to the last activated
configuration).
• If you select an Automation Node Type that has already been activated, but which has a new
Automation Node Instance created after the last activation, once you do a revert of this Automation
Node Type then the new Automation Node Instance will be deleted.
• If you select an Automation Node Type or Automation Node Instance, which has a new Automation
Parameter created after the last activation, once you do a revert the new Automation Parameter will be
deleted.
• If you do a revert on an Automation Node Instance, the related Automation Node Type is not affected.
• If you do a revert on an activated Automation Node Instance and the related activated Automation
Node Type has been modified since the last activation, an error occurs.
Reverting an Automation Node Type

1. Click Automation Gateway Management in the side menu bar.
2. Click Automation Node Type, and in the Automation Node Type page, in the Overview tab, select the required
Automation Node Type.
3. Click Revert and confirm the operation. The configuration of the selected Automation Node Type will be
reverted to its last activated configuration.
Reverting an Automation Node Instance

1. Click Automation Gateway Management in the side menu bar.
2. Click Automation Node Instance, and in the Automation Node Instance page, in the Overview tab, select the
required Automation Node Instance.
3. Click Revert and confirm the operation. The configuration of the selected Automation Node Instance will be
reverted to its last activated configuration.
2.4.5.10 Viewing and Modifying Automation Node Values at Runtime

In the Automation Node Viewer page you can view the current value of the parameters of an Automation Node and
therefore check if the connection with the external automation system is working correctly. You can only view the
Automation Nodes that have been activated on the Automation Gateway Server.
From this page you can also modify the values of the Automation Parameters.
Prerequisite
The Automation Node Types and Automation Node Instances have been activated to the Automation Gateway
Server.
Viewing Automation Node Parameter Values
 Refreshing Automation Parameter values

You can always manually refresh the parameter values to ensure they are up-to-date by clicking
Refresh. This could be advisable before reading the runtime values.
If you want to view the current value of an Automation Node Parameter:

System Apps
Automation App
1. Click Automation Gateway Management in the side menu bar and click Automation Node Viewer.
2. In the Automation Node page, in the left-hand pane select the activated Automation Node you are interested
in.
3. In the Parameters tab, the following attributes of the selected Automation Node Parameter are displayed:
• Name: the name you assigned to the Automation Node Type Parameter.
• Is an Array: the type of the parameter (Scalar if not selected).
• Parameter Value: the current value of the selected Automation Parameter.
• TimeStamp: the time corresponding to the last value change, always expressed in local format.
• Quality Status: the overall condition (severity) under which a parameter value was generated, and thereby the
information can be used as an indicator of the usability of the value. The possible values are: Bad, Uncertain
and Good.
• Quality SubStatus: the detailed condition under which the parameter value was generated.
 For the description of the Quality Statuses (Bad, Good, Uncertain) and the Quality Substatuses, which are
associated with each Automation Parameter value, see AutomationQualityStatus Enumeration and
AutomationQualitySubStatus Enumeration in the Opcenter Execution Foundation Platform Reference Online
Help. In particular, use the code in brackets which refers to the Quality Substatus (for example
"QcsBConfigError") to search for the complete description in the Platform Reference Online Help.
Viewing the Automation Node Configuration

1. In the Automation Node page, in the left-hand pane, select the Automation Node you are interested in.
2. Click the Configuration tab. All the parameters for the specified Automation Node are listed with their most
relevant attributes, such as Channel ID, Address, Acquisition Mode, Acquisition Cycle Id, Smoothing Mode, Delta
Value and Delta Time.
 If you import a master data configuration, you will not be able to view the imported configuration in the
Configuration tab until the configuration has been activated onto the Automation Gateway Server.
Modifying the value of an Automation Node Parameter

1. In the Automation Node page, in the left-hand pane, select the Automation Node you are interested in.
2. In the Parameters tab, click next to the Automation Node Parameter you want to modify, and in the
displayed text box write the new value according to the specified data type. If you want to cancel the just
inserted value, click .
3. Click Send values to Automation Gateway Server.
 Although the WriteAutomationNodeParameters command is meant for internal use and should not be
invoked from custom UIs, you can view it in the list of the public Commands in Solution Studio and
consequently assign it to user roles, in order to control which users or groups have access to the writing
capability. For details on how to configure user roles, see Configuring Roles in the Opcenter Execution

System Apps
Automation App
2.4.6 How to Monitor Automation Gateway Server

You can use the following monitoring applications for analysis and diagnostics purposes:
• Monitoring Automation Gateway Server Runtime Traces
• Monitoring Automation Nodes with AGW Node Monitor
• Exporting the Automation Node Configuration
• Monitoring the Automation Gateway Server Status (documented in the Opcenter Execution
2.4.6.1 Monitoring Automation Nodes with AGW Node Monitor

You can use the Opcenter Execution Foundation - Automation Gateway Nodes Monitor tool to view several
information, such as:
• the Automation Nodes (corresponding to the Automation Node Instances that you have configured so far in the
Automation App and downloaded to the Automation Gateway Server), retrieve the related parameter values
and the value quality information.
• the Automation Channels and their status. For each Channel, the monitor displays a popup window containing
the channel name, the type and the OPC UA information such as the server URL, the channel security
configuration, the reconnection timeout and the connection status.
This tool can be used in the engineering phase to directly test the connectivity between the Automation Gateway
Server and the external automation sources, without the need of developing additional web pages (and
consequently by-passing any other Opcenter Execution Foundation layer).
Data is organized in three areas:
• a Nodes area, where you can choose the Automation Nodes,
• a Parameters area, where you can read the Automation Parameters and the related engineering information,
• a Monitored Parameters area, where you can read Automation Parameter values and the related runtime
information.
Prerequisites
 The tool runs only on an Opcenter Execution Foundation host.
Procedure
1. From <setup drive>:\Program Files\Siemens\SimaticIT\Unified\bin, run the SimaticIT.Agw.Nodes.exe file with
administrator rights.
2. Select an Automation Node from the Nodes list on the left. The related Automation Parameters are displayed on
the left.
3. Select the Automation Parameters and start monitoring them or execute any other required operation (see list
below).

System Apps
Automation App
Sorting and filtering Automation Nodes In the Node List, you can sort items by Node Name or Type by
means of the button, in ascending or descending order, or
search for a specific item.
Reloading the Automation Nodes If the tool was open while you were activating the runtime
integration, you must reload the Automation Nodes to view the
configuration changes in the Nodes area by means of the
button.
Reading the Automation Node engineering In the <Parameter name>Parameters area, the tool displays
configuration the Automation Parameters of the selected Automation Node
and the related engineering information.
For each Parameter, it shows the Parameter name and type,
the data type, the Channel Id and the Address (if configured),
whether the Parameter is Static, and, in case of cyclic
acquisition, it also displays the current cycle id.
Monitoring an Automation Parameter You must monitor an Automation Parameter to retrieve its
value.
To do so, you must select the required Automation Parameter
in the <Parameter name>Parameters area and click the
button. For each monitored Parameter, the tool adds a row in
the Monitored Parameters area below, and displays the
related runtime information.
To stop monitoring an Automation Parameter, click the
corresponding button.

System Apps
Automation App
Retrieving the Automation Parameter value In the Monitored Parameters area, the tool displays the
monitored Automation Parameters and the related runtime
information.
For each Parameter, it shows the value, the data type, the
timestamp (expressed in local format), the data quality
information (status and substatus) , the Parameter internal ID
and the Subscription status.
Nodes and Automation Parameters are identified by internal
IDs. These IDs are useful to identify entities in the HMI RTIL
Platform Trace Viewer.
 For the description of the Quality Statuses (Bad, Good,

Uncertain) and the Quality Substatuses, which are
associated with each Automation Parameter value,
see AutomationQualityStatus Enumeration and
AutomationQualitySubStatus Enumeration in the
Opcenter Execution Foundation Platform Reference
Online Help. In particular, use the code in brackets
which refers to the Quality Substatus (for example
"QcsBConfigError") to search for the complete
description in the Platform Reference Online Help.

System Apps
Automation App
Writing the Automation Parameter value In the Monitored Parameters area, you can modify the value
of the monitored Automation Parameter.
To do so, click on the value, modify it and then press ENTER to
confirm the change.
If you want to cancel the change, click anywhere outside the
cell instead of pressing ENTER.
 If you want to work with an Array value:

1. In the Monitored Parameters area, click on the
value to open the Node Parameter Value dialog
box.
2. In the Node Parameter Value dialog box, you
can:
• Add a value: Click to insert a new row
at the bottom of the table
• Modify a value: Click on the corresponding
cell and enter the new value
• Remove a value: Click to delete the
corresponding row
• Refresh: Click to update the items to
the latest available parameter value
• Undo: Click to revert the items to the
previous parameter values
3. Click Save to update the array values with the
modified ones, otherwise click Cancel to preserve
the initial values displayed in the Monitored
Parameters area.
Exporting/Importing the monitored You can export the configuration of the monitored Automation
configuration Parameters to a json file by clicking or you can import a
previously exported configuration by clicking and
browsing to the saved file.
If you import a second configuration without removing the
previously monitored Parameters, the imported items are
added to the existing ones.
If the imported configuration is not aligned with the current
configuration, a warning is displayed and the existing
Parameters are added to the grid.

System Apps
Automation App
Viewing channel information For each Automation Parameter connected with the field, you
can click on the icon under the Channel Id column of the
Parameters area and a popup window with the channel
configuration will be displayed.
If you have enabled Failover Redundancy, in bold you will see
the server where the publishing is active.
 The Disconnected status could be also returned if the

certificate trust procedure had not been carried out
completely (see Configuring the Automation Gateway
Server with AGWConf Tool in the Opcenter Execution
2.4.6.2 Exporting the Automation Node Configuration

After you have activated the Automation Node configuration, you can check if the configuration that has been
downloaded to the Automation Gateway Server is aligned with the Automation Node configuration you have
carried out so far.
For diagnostic purposes, Opcenter EX FN provides you with a command line utility which exports the Automation
Gateway Server engineering configuration (Automation Node Types and Automation Node Instances) to a JSON file,
as well as the runtime configuration (Automation Nodes downloaded to the Automation Gateway Server).
Prerequisites
You are on the Opcenter EX FN Engineering host (as the SITUAAutomationUtil.exe utility runs only on the
Engineering host).
Procedure
1. Open a command prompt as Administrator and navigate to the Opcenter EX FN binary folder
(%SITUnifiedSystemRoot%bin).
2. Run the SITUAAutomationUtil.exe utility and invoke the export command by setting the following input
parameters:
Input Parameter Description
mode=[VALUE] (Mandatory) Specifies the configuration type you want to export:

• eng
• runtime

System Apps
Automation App
Input Parameter Description
path=[VALUE] (Optional) The path of the folder where the

<yyyymmdd>_<hhmmss>_AutomationUtilExport.json file will be saved.
If you do not specify the path, the file will be created in the following
default folder: %ProgramData%
\Siemens\SimaticIT\Unified\Deploy\Automation\Project.
Example
SITUAAutomationUtil.exe -command=export -mode=eng -path=FolderPath
2.4.6.3 How to Monitor Automation Gateway Server Runtime Traces

The HMI RTIL Platform Trace Viewer is a GUI application that allows you to monitor traces in real time sent from the
You can enable/disable trace severities as well as filter by traces and export them to text files.
Prerequisites
The user that runs the HMI RTIL Platform Trace Viewer must belong to the RTIL Tracing Users Windows group.
This user must be manually added to the mentioned local group, on each host where you need to launch the HMI
RTIL Platform Trace Viewer. After modifying the user group, restart the host to make changes effective.
Launching Starts the RTILTraceViewer.

RTILTraceViewer
Configuring trace Configures traces and settings.

settings
Persisting traces Persists traces.
Enabling autoscroll Enables or disables the auto-scroll functionality.
Clearing traces Clears traces.
Starting profile Starts the profile loader.

loader
Setting profiles Sets the profiles.
Launching RTILtraceViewer

System Apps
Automation App
From the %SITUnifiedSystemRoot%Automation\bin folder of either an Opcenter EX FN host or an Automation

Gateway Server host, run the RTILtraceViewer.exe file.
Configuring trace settings and filters

From the viewer, select the Edit > Trace Profile command.
In the Profile dialog box you can inspect all the registered modules, enable/disable trace severities.
Modules are structured by Host (corresponding to the machine where the project is running), System
(corresponding to the project itself), Application (corresponding to the executable running) and SubSystem
(corresponding to a component inside the application).
To enable/disable severities, select an item and use the severity buttons in the Profile dialog box (to open it,
choose Edit > Trace Profile). Note that only one button can be selected at a time and by enabling a severity level,
all the higher levels will be automatically enabled. For example if you select Info, the system automatically enables
Warning, Error and Fatal. The Trace Viewer allows you to set a severity on specific Modules as well as on all higher
levels. If you select higher levels, the severity will then be applied to all Modules below the selected element. If you
disable traces in the viewer by excluding for example a certain severity level, the traces are not actually generated
by the source applications. You can save the profile settings in order to display predefined tracing viewer sessions
without reconfigure them from scratch (see paragraph Setting profiles below).
Filters allow you to hide traces that do not match the specified filters. You can configure filters either from
the Filter menu or by right-clicking a column header and choosing the required settings.
Persisting traces
From the Trace Viewer, select the File > Save As Text command to save the traces from the Trace Viewer into a text
file or CSV file.
Enabling the auto-scroll functionality

By default, the Trace Viewer always scrolls to the bottom when new traces are read. If you select the View >
Autoscroll command, you can enable or disable the automatic scrolling.
Clearing traces
From the Trace Viewer, select the Edit > Clear traces command to remove all traces from the viewer.
Starting the profile loader

The Profile Loader allows you to load a previously configured and saved profile (i.e a set of trace configurations).
The profile loader can be started manually or automatically each time the viewer starts.
To manually start the profile loader, select the Tools > Profile Loader command from the Trace Viewer.
The profile is only applied on applications which are started after the profile loader was started.
These applications must be in the same user session too (e.g. not running as services).
Setting profiles
When the system starts for the first time, settings defined in the trace configuration will be used by default. For
example: Info, Warning, Error and Fatal messages will be shown.
To modify these settings, select Edit > Trace Profile from the Trace Viewer to open the Trace Profile dialog box.

System Apps
Data Segregation App
If you want to use the same settings several times, you can save them from the Trace Viewer into a local file and
then load them when needed.
To do this, in the Profile dialog box, click the Save Profile button to save settings in a local XML file and then click
Load Profile to load the saved configuration.
The XML file contains the description of the applied settings.
Additional Trace Viewer settings, such as custom colors, column widths and so on will be added to this file as well.
2.5 Data Segregation App

The Data Segregation App provides pages where it is possible to create and configure segregation tags in a user-
friendly environment.
Segregation tags are an essential part of the Data Segregation feature, which makes it possible to limit user data
access.
The App references the DSG_SD Functional Block. For detailed information on the artifacts contained in this
Functional Block, see the Reference Documentation of the Functional Block.
For a general understanding of Functional Blocks, see Overview of Functional Blocks in the Opcenter Execution
 Opcenter Execution Foundation adopts the CQRS pattern principle (Command Query Responsibility
Segregation), based on the separation of reading and writing channels. From version 2.3, Opcenter EX FN
implements data views based on session tags for reading channel requests. Consequently, interactive
users, logged on via Opcenter EX FN authentication server token, are able to retrieve only data tagged with
the same set of tags registered in the session tags. Tags are assigned to user by means of a personnel app.
When an interactive user logs in, tags assigned to the user are registered in the session tags. Tag-based
views are not applied to the retrieval of data from commands, events and signal rules from version 2.3 of
SIMATIC IT UAF.
What can I do in the Data Segregation App?

• Conceptual information are provided in What is Data Segregation?
• Information on the involved users and entity instances are provided in Which Users and Entity Instances are
involved in Data Segregation.
• An high-level quick start to enable and use Data Segregation is provided in Quick Start to Using Data
Segregation. Here, an example of scenario is also provided.
• Information on how Data Segregation works at runtime are described in How Data Segregation works at
runtime.
• Information on how and when Data Segregation is applied to entity instances are described in What Data
Segregation is Applied to.
• The procedures to create and assign segregation tags are described in How to Manage Segregation Tags.
• The procedure to configure custom and third-party integration apps to use Data Segregation are described
in How to Use Data Segregation in Custom and Third-Party Integration Apps.
• The contents of the Functional Block references by the Data Segregation App is explained in DSG_SD Functional
Block of the Opcenter Execution Foundation Development and Configuration Guide.
2.5.1 What is Data Segregation?

Data Segregation allows system integrators to limit data access to certain users by categorizing the required data
types and associating these categories to the required users.

System Apps
Data Segregation in Opcenter EX FN implements data views based on segregation tags for reading channel
requests. Interactive users, logged on via Opcenter EX FN Authorization Server (as described at page Managing
Client Authorization in the Opcenter Execution Foundation Development and Configuration Guide), are able to retrieve
only data tagged with the same set of segregation tags. This is achieved by assigning session tags to users. This
assignment can be implemented:
• by the Personnel App
• by Custom apps: they may also be part of the same solution, can manage generic resources, such as equipment,
and associate them with users.
When a user creates a new instance of an entity, the session tags associated with his/her assigned Person (or
resource) can then be assigned to the new instance. In this way Data Segregation can be gradually applied to all
new instances.
When an interactive user logs on to query data, segregation tags assigned to the user are registered as the session
tags. Tag-based views are not applied to the retrieval of data from commands, events and signal rules.
 Users must be logged on via Opcenter EX FN authorization server token.
2.5.2 Which Users and Entity Instances are involved in Data Segregation
Which Users are involved in Data Segregation
The users involved in Data Segregation functionality are:
• the SysAdmin user (for general information see How to Configure Accounts of the Opcenter Execution
Foundation Development and Configuration Guide)
• a UMC user (for information see the User Management Component documentation, i.e. UMC Web UI User
Manual and UMX User Manual).
The following table provides some useful concepts on these users you need to know to manage segregation tags.
 Data Segregation App works in close collaboration with the Personnel App or any custom application
that allows you to manage persons in order to segregate the data each person has access to. For this
reason, a general knowledge on Personnel App is required before approaching this table.
SysAdmin User UMC User
Can assign the following roles to a UMC user in order If Persons are created in the Personnel App, must have
for the UMC user to assign segregation tags to these assigned roles in order to assign segregation tags
Persons created in the Personnel App: to Persons:
• AccessControlViewer • AccessControlViewer
• AccessControlAdmin • AccessControlAdmin
Can assign all required command rights to the role of The role of this user must have all assigned required
the UMC user in order for the UMC user to perform command rights in order for the user to perform
operations. For example, operations. For example, the CreatePerson command
the CreatePerson command is required to create is required to create Persons in the Personnel App.
Persons in the Personnel App.

System Apps
SysAdmin User UMC User
Is the first user who accesses the UI Application and Can assign segregation tags to Persons (created in
creates segregation tags. He/she can assign the Personnel App or equivalent custom App) or entity
segregation tags to Persons (created in instances only if he/she is associated with a Person. This
the Personnel App or equivalent custom App) or because the tags assigned to the Person are available in
entity instances without needing to be associated session (the Assigned Tags panel in the Data
with a Person. If the Person to whom you want to Segregation UI) and can be view and manage by the
assign tags is associated with the SysAdmin user, user.
the operation cannot be performed because the
dedicated button is not displayed. This is because all
segregation tags are already assigned to
the SysAdmin user by default.
Can always assign segregation tags to Persons Can assign segregation tags to Persons (created in
(created in the Personnel App or equivalent custom the Personnel App or equivalent custom App) or entity
App) or entity instances because all segregation tags instances only if segregation tags have been assigned to
are already assigned to him/her by default the associated Person, otherwise he/she
by the Personnel App or equivalent custom App. cannot perform the operation.
Can view all segregated data (data associated with Can view segregated data only if the segregation tags,
tags) because all segregation tags are assigned to associated with this data, are assigned to the Person
him/her by default by the Personnel App or associated with this user. This because the tags
equivalent custom App. assigned to the Person are available in session (the
Assigned Tags panel in the Data Segregation UI) and
can be view by the user.
For example, if two tags are associated with an entity
instance, the user must have both these assigned tags in
order to view the instance. Otherwise, if the user has
only one assigned tag, he/she cannot view the instance.
Can always view all not segregated data (data which If Persons are created in the Personnel App, can view
are not associated with tags). not segregated data only if the associated Person has
been enabled to view them (by setting the dedicated
option View Unsegregated data). Created Persons
can view not segregated data by default but a user can
modify the default behavior in order for the created
Person to not view not segregated data.
Which Entity Instances are involved in Data Segregation

Entity instances to which you want to assign segregation tags must be able to be segregated. For example,
segregation tags, Persons and Persons Groups are not.
Segregation tags are the items which allow you to segregate data, so they cannot be segregated in turn.
When you assign segregation tags to Persons or Person Groups, you are granting them the right to access to
segregated data. When you assign segregation tags to entities, for example Materials, you are segregating them.

System Apps
2.5.3 Quick Start to Using Data Segregation

Here is an outline of the main macro-steps required to enable and use Data Segregation functionality properly. We
also provide you an example of a possible scenario in order to help you in understanding and using the
functionality.
Workflow
1. In the User Management Component, create a user who will log on to the UI Application, as described in the
UMC documentation (UMC Web UI User Manual and UMX User Manual).
2. From Solution Studio, install the Data Segregation App when creating your Solution, as described in Creating a
Solution from Scratch of the Opcenter Execution Foundation Development and Configuration Guide.
3. Enable the Enable data segregation tag selection option when creating your UI Application, as described in
Creating a UI Application of the Opcenter Execution Foundation Development and Configuration Guide, to display
the data segregation tags assigned to the user in the runtime application.
4. If the Personnel App will be used to create Persons, assign AccessControlViewer and AccessControlAdmin
roles to the UMC user who will log on to the UI Application. In this way, this user can assign segregation tags to
Persons. For information on these roles, see How to Configure Accounts in the Opcenter Execution
5. Assign all required command rights to the role of the UMC user who wants to perform the operations. For
example, the CreatePerson command is required to create Persons in the Personnel App. See Assigning Rights
to Roles in the Opcenter Execution Foundation Development and Configuration Guide.
6. Access the UI Application as SysAdmin user. For information on this user, see How to Configure Accounts in the
7. Create segregation tags in the Data Segregation App.
8. Log off from the UI application. Segregation tags are displayed and assigned to you by default
by the Personnel App or equivalent custom App the next time you log on.
9. Access the UI Application again.
10. Create a Person in the Personnel App or equivalent custom App and associate this Person with the UMC user. If
the Personnel App is used, the created Person can view not segregated data by default but you can modify the
default behavior in order for he/she to not view not segregated data.
11. Assign the required segregation tags to this Person.
 Pay attention: when you assign segregation tags to Persons (or Person Groups), you are not
segregating them, but you are granting them the right to access to segregated data. When you assign
segregation tags to entities (for example, Materials), you are segregating them instead.
12. Create an entity instance (for example, create a Material in the Material App) and assign the required
segregation tags to it.
13. Log off from the UI application.
14. Access the UI application as the UMC user associated with the created Person. Now you can:
• Create other Persons or Group of Persons.
• Assign all segregation tags that are already assigned to you to these Persons or Group of Persons. Pay attention
that you are not segregating Person/Person Groups, but you are granting them the right to view/do something.
The session is populated with both tags assigned to Persons and tags assigned to Person Groups. Persons
inherit all tags assigned to the Groups to which they are associated. Segregation tags assigned to Person
Groups can be viewed in the Personnel Management environment by selecting the Person assigned to the
Person Group.
• Manage the instances with the same tags already assigned to you.
• Manage the not segregated instances if the Person associated with your user is enabled to view not segregated
data.
• Create new segregation tags. Pay attention that they are not assigned with you by default because you are not
logged on as SysAdmin user. For this reason, you cannot assign the new tags. To do it, you need to log on to the

System Apps
UI application as SysAdmin user again and assign the new segregation tags to the Person associated with the
UMC user.
Example of Scenario
The following diagram shows an example of possible scenario. It has been split in three different phases to better
explain the system behavior.
 Since Personnel App and Material App are involved in the example, a general knowledge on these Apps is
required before approaching this diagram.
Phase 1
Phase 2
Phase 3

System Apps
2.5.4 How Data Segregation works at runtime

Data Segregation is closely integrated with Personnel App, and is managed through a series of ad hoc events, as
shown in the following table.
Event Description
SessionCreated Fired by the system when a user logs in via an Opcenter EX

FN authorization server token.
SessionPopulated Fired by Personnel App or a custom personnel app, to notify the end
of the populate action.
SessionAlignment Fired by the system to allow third-party integration Apps to perform

alignment operations.
SessionAligned Fired by third-party integration Apps to notify the end of their

alignment operations.
SessionUpdated Fired by the system to notify that a session has been updated.
SessionDeleted Fired by the system to notify that a session has been deleted.
When creating handlers for these Data Segregation system events, bear in mind that their envelopes may be NULL
For further information on the events involved see SystemData.Foundation reference documentation.
Behavior
When a user logs on to an App, requesting a token from the Opcenter EX FN Authorization Server (described in
Managing Client Authorization of the Opcenter Execution Foundation Development and Configuration Guide), the

System Apps
system component triggers the SessionCreated event to which the Personnel App is subscribed. Through a
predefined event handler, the Personnel App performs the necessary business logic to retrieve:
• the Person associated with the session user
• the Groups to which the Person belongs.
Personnel Manager then populates the session with the list of Segregation Tags assigned to the retrieved Person
and Group(s), and sends a SessionPopulated event to the system.
The system waits for the SessionPopulated event from Personnel App or custom personnel app (or
the SessionAligned event when there is third-party integration App). The populate session operation has a default
timeout (10 seconds) which can be customized in the following configuration files in the Opcenter EX FN Application
Service Layer and in all hosts of the environment:
• %SITUnifiedSystemRoot%svc-runtime\Web.config
• %SITUnifiedSystemRoot%bin\Worker.exe.config
• %SITUnifiedSystemRoot%bin\Worker32.exe.config
You need to modify these files by adding the LoadSessionTimeout key (in milliseconds), as shown in the
following example:
<appSettings>
<add key="LoadSessionTimeout" value="10000" />
</appSettings>
If the timeout expires or the SessionPopulated event contains an error code, then the populate session
operation fails and the system generates a internal server error.
During create operations the selected tags associated with session user are by default assigned to the entity
instances. The user can modify this behavior directly in the business logic, by modifying the list of segregation tags
associated with the instance.
When the user logs off, the system triggers a SessionDeleted event and the session is cleared. If the token expires,
the related session also expires. The user must consequently repeat the log-in process, and the system triggers a
new SessionCreated event.
 The Personnel App automatically assigns all available segregation tags to the SysAdmin user even if this
user is not associated with a Person.
2.5.4.1 Performing queries on runtime data

All runtime queries performed by users logged on via the Opcenter EX FN Authorization Server, performed either via
a Service Layer oData query or an SDKLean ProjectionQuery, will allow the user to see only the entities whose
segregation tags have also been assigned to the user.
If two entities are associated with different tags, the user must have the assigned tags of both entities to perform an
expand in a relationship. In case of Many-To-One relationship, if the user performs the query on Many side and he
has not the assigned tags of the One side entity, then the navigation property is null, only if the entities are defined
in the same database; otherwise, in case of cross-entities, an exception returns.
2.5.5 What Data Segregation is Applied to

Here we explain when and how Data Segregation is applied to entity instances and when it is propagated.
Data Segregation is applied when:

System Apps
• The Data Segregation App has been added to the Solution.

• The user has logged via Opcenter EX FN Authorization Server (as described in Managing Client Authorization of
the Opcenter Execution Foundation Development and Configuration Guide).
If these prerequisites are satisfied, Data Segregation is then applied to the following operations as follows:
Operation Applied Description
Create Selected session tags are added by default to instances created via API
Platform.Create.
Command handler can modify the Segregation Tag list (see below).
In case of Composition relationship, the part entity inherits the tags of
the composite entity. Any tag added to the part entity in the command
handler will be ignored.
In case of Facet, during the submit operation, the segregation tags of
the related entity are automatically associated with the facet. This
means that the tags associated with the facet by the user will be merged
with the tags of the related entity, in order to restrict the access to the
facets in comparison to the entity (for example, a restricted document
associated to an unrestricted entity).
Edit By default the segregation tags are not modified. Command handler can
modify Segregation Tag list.
In case of simple relationship:
• Segregation tags associated with entity instances are not
propagated.
In case of Composition relationship:
• Part entity tags cannot be modified.
• Changes applied to the composite entity tags are propagated to the
part entity.
In case of Facet:
• Facet tags can be modified independently from the related entity
tags.
• Changes applied to the base entity tags are not propagated to the
Facet.
Copy When copying the entity instance, then segregation tags associated
with entity instances are propagated.
New Revision When creating a new revision of the entity instance, then segregation
tags associated with entity instances are propagated.
Bulk insert Selected session tags are added by default to instances created via API
Platform.Create.
The behavior is the same of the Create operation.

System Apps
Bulk import Selected session tags are added by default to instances created via API
Platform.Create when the entity instance does not exist.
Signals Signals triggered when specific entity instances are created, updated,
deleted, frozen/unfrozen or locked/unlocked, are sent to users who are
subscribed to the signal via authorization server, if the segregation tags
associated with the entities are also assigned to the user.
Events and commands The user session is not propagated in business logic events, and
commands called from business logic events.
So no default values are inserted in create operations and queries are
not segregated.
Lock/unlock Lock/unlock operations do not modify segregation tags associated with

entity instances.
Freeze/unfreeze Freeze/unfreeze operations do not modify segregation tags associated

with entity instances.
Delete/purge Delete/purge operations do not modify segregation tags associated

Mark for cleaning Mark for cleaning operations do not modify segregation tags associated
Queries Queries via Service Layer (including Reading Functions) or via SDKLean
application are segregated by using the selected session tags if a
request is made with a token generated from the Authentication Server.
Queries are not currently segregated in Workers.
GetCommittedEvent The following APIs are not segregated when they are invoked from a
APIs and SDKLean application or from a Reading Function, even if a request is
GetContentPayload API made with a token generated from the Authentication Server:
• IEvent GetCommittedEvent(Guid sessionId, EntityDomain
entityDomain);
• IEnumerable<IEvent> GetCommittedEvents(Guid lastSessionId,
EntityDomain entityDomain);
• IEnumerable<IEvent> GetCommittedEvents(Guid lastSessionId,
EntityDomain entityDomain, int pageSize);
• IEnumerable<IEvent> GetCommittedEventsInRange(Guid
sessionIdFrom, Guid sessionIdTo, EntityDomain entityDomain).
• Stream GetContentPayload(Guid id, UnifiedContentNamespace
contentNamespace = UnifiedContentNamespace.Application);

System Apps
Attach Documents to Documents attached to an entity can be segregated if the Data

Entities Segregation functionality is enabled. The class defining a document
(Content) has been extended by adding a list of tags that allows you to
associate segregation tags with an instance/document. For more
information, see Attaching Documents to Entities in the Opcenter
Associate segregation Segregation tags can be associated to entity instances as standard

tags to entity instances many-to-many relationships towards the entity that needs to be
segregated. For code examples, see Managing Many-to-Many
Relationships in the Opcenter Execution Foundation Development and
In case of generic entities, segregation tags can be added/removed by
using the GetSegregationTags method. For more information, see the
Opcenter Execution Foundation Platform Reference Guide.
Modify the list of In case of Composition relationship, the involved entities must be
segregation tags composite entities. Parent entities will inherit all changes; this because
associated to entity any change applied to the composite entity tags will be propagated to
instances the part entity.
 The session lifecycle is linked to the Token lifecycle. Different tokens created from the same user will
generate different sessions.
Segregation Tags assigned to a Person are available in Session the next time the associated user logs on.
2.5.6 How to Manage Segregation Tags

The Data Segregation workflow starts in the Data Segregation App where segregation tags are created. You can
then assign these segregation tags both to Persons/Person Groups and to entity instances in your App.
Workflow
1. Creating segregation tags in the Data Segregation App.
2. Assign segregation tags to Persons in the Personnel App or custom Apps.
3. Assign segregation tags to entity instances in Apps using default values.
4. If needed, modify the list of segregation tags assigned to entity instances.
Additional Operations on Segregation Tags

System Apps
Edit To modify tag description, tag color and the option to make the tag relevant for logging
operations.
Delete All tags can be deleted, regardless of whether they have already been associated with an
entity instance or Person/Person Group.
2.5.6.1 Creating Segregation Tags

Segregation tags are associated with Persons and entity instances and make it possible to specify which data a user
can see. They are part of the Data Segregation workflow.
When creating segregation tags, you can decide to mark a specific tag relevant for logging operations and then
register a set of information, in order to log operations performed on Data Segregation tags.
Procedure
1. Do either of the following to open the Data Segregation Tag page:
• Click the Data Segregation Tag home tile.
• Click Data SegregationTags Management in the side menu bar and click Data Segregation Tag.
2. In the Data Segregation Tag page, click .
3. In the Add page insert a mandatory name for the new tag.
4. Add an optional description.
5. Select a color for the tag from the list of possibilities. Otherwise, a grey color will be displayed in the Assigned
Tags panel.
6. If you want to make the tag relevant for logging operations, select the Record access in segregation tag log
check box. Segregation logs will be displayed in the Segregation Tag Log page.
7. Click Save.
 • Segregation tags are displayed in the Data Segregation panel the next time the associated user
logs on.
• The CreateSegregationTag Command allows you to create Segregation tags, as described in the
Commands section of the DGS_SD Reference Guide. If it has been directly used and the Color input
parameter has been configured by setting a not allowed value, segregation tags are displayed with a
Grey color in the Assigned Tags panel.
2.5.6.2 Assigning Segregation Tags to Entity Instances in Apps using Default

Values
In any App, segregation tags, assigned to the user who is performing operations, can be associated with entity
instances.
The user must have all these assigned tags in order to view the data. Then, before creating an entity instance, the
user must decide if the instance will be associated with all segregation tags which are assigned to him/her or with a
subset of these tags.
When you assign segregation tags to entities (for example, Materials), you are segregating them.

System Apps
The following procedure describes how you can assign segregation tags to entity instances in Apps by using the
default values, without changing the business logic.
Prerequisites
• The Data Segregation App has been installed in the Solution.
• The Enable data segregation tag selection option has been enabled for your UI Application in Solution Studio,
as described in Creating a UI Application of the Opcenter Execution Foundation Development and Configuration
Guide.
• You have created Data Segregation tags in the Data Segregation App.
• You are a Sysadmin user, otherwise you have created Persons associated with users in the Personnel App or
equivalent custom App and you have associated Data Segregation tags with these Persons. It is possible to
create custom Apps with generic resources, such as equipment, and associate them with users.
• Entity instances to which you want to assign segregation tags must be able to be segregated (for example,
segregation tags, Persons and Persons Groups are not). For further information, see Which Users and Entity
Instances are involved in Data Segregation.
Procedure
1. Do either of the following to open the Data Segregation Tag page:
• Click the Data Segregation Tag home tile.
• Click Data SegregationTags Management in the side menu bar and click Data Segregation
Tag. The Tag Management dialog box opens displaying the following areas:
• Assigned Tags - The Data Segregation Tags that are assigned to the logged on user but not to the
entity instances.
• Assigned and Active Tags - The Data Segregation Tags that are assigned to the logged on user
and entity instances. By default this area is populated with all available tags.
2. If necessary, change the tag assignment using the following buttons:

System Apps
Icon Description
To remove the assigned tag from the entity instances.
To assign the tag to the entity instances.
To assign all the tags to the entity instances.
To remove all the assigned tags from the entity instances.
3. Click OK.
 The CreateSegregationTag Command allows you to create Segregation tags, as described in the
Commands section of the DGS_SD Functional Block Reference Guide. If it has been directly used and
the Color input parameter has been configured by setting a not allowed value, segregation tags are
displayed with a Grey color in the Assigned Tags panel.
2.5.6.3 Modifying the List of Segregation Tags Assigned to Entity Instances

In any App, the list of segregation tags previously created and assigned to entity instances can be modified. This can
be required for example to meet customer needs better.
The system fires a dedicated event (the ReplacedSegregationTagAssociation event) that allows you to implement
custom code to handle propagation logic (third-party entities or simple relationships). For more information, see
DSG_SD Functional Block of the Opcenter Execution Foundation Development and Configuration Guide.
Prerequisites
• The Data Segregation App has been installed in the Solution.
• The Enable data segregation tag selection option has been enabled for your UI Application in Solution Studio,
as described in Creating a UI Application of the Opcenter Execution Foundation Development and Configuration
Guide.
• You have created Data Segregation tags in the Data Segregation App.
• You are a Sysadmin user, otherwise you have created Persons associated with users in the Personnel App or
equivalent custom App and you have associated Data Segregation tags with these Persons. It is possible to
create custom Apps with generic resources, such as equipment, and associate them with users.
• You have assigned segregation tags to entity instances (entity instances are able to be segregated. For further
information, see Which Users and Entity Instances are involved in Data Segregation).
• In case of Composition relationship, the involved entities must be composite entities. Parent entities will inherit
all changes; this because any change applied to the composite entity tags will be propagated to the part
entity. For further information, see What Data Segregation is Applied to.
Procedure
1. In the runtime UI page of your App select an entity instance and click the icon.
The Tags Management sidebar displays the segregation tags that have already been assigned to the selected
entity instance, and those that are available but not currently assigned.
2. Modify the list of segregation tags assigned to the entity instance, as follows:

System Apps
• To assign segregation tags to the selected entity instance, click the icon in the available tags list.
• To unassign segregation tags to the selected entity instance, click the icon in the assigned tags list.
3. Click Save All.
2.5.6.4 Displaying Segregation Tag Logs

When creating Segregation Tags, you can decide to mark a specific tag relevant for logging operations and then
register a set of information, in order to log operations performed on Data Segregation tags. The information you
can track is the following:
• creation, update and deletion of a tag,
• association or disassociation of a tag to/from a Person or a Person Group,
• assignment or unassignment of a tag to/from an entity instance.
You can view the related segregation logs in a dedicated page, the Segregation Tag Log page, that embeds a
search functionality on all the most log relevant information and displays the results in a table view. Each log can be
expanded to show the modification details.
Accessing the Page

1. Do either of the following to open the Segregation Tag Log page:
• Click the Segregation Tag Log home tile.

• Click Data Segregation Tags Management in the side menu bar and click Segregation Tag Log.
The system displays the Segregation Tag Log page.
Sorting results You can sort results by choosing the field on which you want to apply the ordering
criteria (in ascending or descending order).
Searching By clicking on the icon placed on the top of the screen, you can enter search
criteria in the provided filters in order to search by the most relevant information
(involved tags, operation time stamp, user name, action type, involved entities and
entity type, environment).
By clicking on the icon placed next to each retrieved log, the system
automatically fills in the search criteria with the name of the selected segregation tag
and makes it easier to search for all the items that are related to the selected one.
Expanding log details You can expand each log to view some details (time stamp, involved tag, entity to
whom the tag is assigned, environment).
2.5.7 How to Use Data Segregation in Custom and Third-Party

Integration Apps
Data Segregation is closely integrated with the Personnel App to manage Persons.

System Apps
However, custom apps can be used with the Data Segregation functionality to manage persons and/or resources,
such as equipment, and to associate them with users. These custom apps must have predefined event
subscriptions to the event generated when a user logs on the a session (SessionCreated), create and call a
command to invoke a specific method of IUnifiedSdkDataSegregationWriting interface to populate the
session (PopulateSessionSegregationInfo), and fire the SessionPopulated event to notify that the session has
been populated.
Data Segregation can also be used by third-party integration apps, via a predefined event subscription to the
SessionAlignment event. Once the event is fired, information on the session tags can be retrieved with
the GetSessionSegregationInfo command, custom logic can be implemented to manage the session tags, and the
SessionAligned event must be fired to notify that the session has been populated.
SessionId is a parameter of the Session Manager system events. You can programmatically retrieve the SessionId
from the current session by using the following code:
Principal.Claims.Where(c => c.Type == "urn:unifiedsession").FirstOrDefault()?.Value;
However, the user session is not propagated in business logic events, and commands called from business logic
events.
• Handling Persons or Resources with Custom Apps
• Implementing Data Segregation in Third-Party Integration Apps/Functional Blocks
• Logging Operations on Data Segregation Tags
2.5.7.1 Handling Persons or Resources with Custom Apps

The Personnel App, loaded and deployed with the MOM Solution, is closely integrated with the Data Segregation
App, and provides a working environment where Persons can be defined and associated with segregation tags.
However, custom Apps can be used with the Data Segregation functionality instead of, or alongside, the Personnel
App, to manage persons and/or resources, such as equipment, and to associate them with users.
Workflow
 The SessionCreated and SessionPopulated events are available as referenced system events inside the
model project in Project Studio for Functional Blocks, Apps and Extension Apps.
Procedure
To handle the SessionCreated event through an event handler, invoke
the PopulateSessionSegregationInfo method and fire the SessionPopulated event, you have to go through the
following steps, described in the Opcenter Execution Foundation Development and Configuration Guide.
 Pay attention to the timeout expiration when performing these steps.

System Apps
1. In the Functional Block, create a command to call the PopulateSessionSegregationInfo method (see How to
Implement Command Handlers in the Opcenter Execution Foundation Development and Configuration Guide). This
command populates the session with associated segregation tags. For more information on
the PopulateSessionSegregationInfo method see IUnifiedSdkDataSegregationWriting Methods in the Opcenter
Execution Foundation Platform Reference Guide.
2. In the Functional Block or in the App, create an event handler for the SessionCreated event (see How to
Implement Event Handlers in the Opcenter Execution Foundation Development and Configuration Guide). The
event is fired whenever a user logs on and also provides information on the expiry date of the session, the
authentication mode used, the identity of the user, and a unique Id assigned to the session. For reference
information on the SessionCreated event parameters, see SystemData.Foundation reference documentation in
the Foundation Model Reference Guide.
3. Implement the previously created event handler (see Implementing Command and Event Handlers in the
Opcenter Execution Foundation Development and Configuration Guide) to retrieve information on persons or
resources associated with the user passed as a parameter in the SessionCreated event, and their associated
Data Segregation tags. Then, invoke the previously defined command from the SessionCreated event
handler (see Invoking Commands in the Opcenter Execution Foundation Development and Configuration Guide).
4. Fire the SessionPopulated event from the event handler (see Raising Events in the Opcenter Execution
Foundation Development and Configuration Guide) to notify that the session has been successfully populated.
This operation needs to be always performed, even if an error returns or there are not tags to be associated. For
reference information on SessionPopulated event parameters, see SystemData.Foundation reference
documentation in the Foundation Model Reference Guide..
5. In the App, create a predefined event subscription for the SessionCreated event handler (see Configuring Event
Subscriptions in the Opcenter Execution Foundation Development and Configuration Guide). The event
subscription is needed to synchronize with the system so that it will wait for the
successive SessionPopulated event before proceeding.
2.5.7.2 How to Implement Data Segregation in Third-Party Integration Apps/

Functional Blocks
To implement Data Segregation in Third-Party integration Apps/Functional Blocks:
1. Integrate Data Segregation in Third-Party Data Model.
2. Integrate Data Segregation in Third-Party Business Logic.
2.5.7.2.1 Integrating Data Segregation in Third-Party Data Model

Here we provide you a guideline to create the view required to implement Data Segregation in Third-Party
integration Apps/Functional Blocks.
Prerequisites
The view must satisfied certain conditions that are described in the Prerequisites for External Data Source
Views section of the Opcenter Execution Foundation Development and Configuration Guide.
Procedure
1. Create a table containing the session tags. This table must be populated when the Third-Party integration Apps/
Functional Blocks receives the SessionAlignment event handler. We suggest that you:
• Delete no more valid sessions by using the event handler for the SessionDeleted event.
• Implement a business logic of deleting based on the expiry date.
• Update the expiry date when receiving the SessionUpdated event.
For reference information on the SessionAlignment, SessionDeleted and SessionUpdated event
parameters, see the SystemData.Foundation reference documentation.

System Apps
2. For each entity to be segregated, create an associated entity that can contain tags. We suggest that you keep
tags associated with the entity aligned by subscribing the SegregationTagDeleted event. For reference
information on the SegregationTagDeleted event, see SystemData.Foundation reference documentation.
3. Create or update the imported view by running a join query between the Third-Party table, the table with the
associated tags and the table with the session tags. See the following examples.
2.5.7.2.1.1 Example of SQL Server View
CREATE VIEW [dbo].[wExt1] AS
SELECT
FROM [dbo].[Ext1]
WHERE (CONVERT(tinyint,0x1) & SUBSTRING(ISNULL(CONTEXT_INFO(),0), 2, 1)) = 0
UNION ALL
SELECT
FROM [dbo].[Ext1]
WHERE (CONVERT(tinyint,0x1) & SUBSTRING(ISNULL(CONTEXT_INFO(),0), 2, 1)) = 1
AND Id NOT IN
SELECT
M2M.[Ext1_Id]
FROM [Ext1-To-Tag] M2M
LEFT JOIN [SessionSegregationTags] U ON U.[TagName] = M2M.[TagName] AND U.[SessionId]

= SUBSTRING(CONTEXT_INFO(), 19, 16)
WHERE U.[SessionId] IS NULL
AND (CONVERT(tinyint,0x2) & (SUBSTRING(CONTEXT_INFO(), 2, 1)) = 2 OR Id IN (SELECT

[Ext1_Id] FROM [Ext1-To-Tag]))
GO
Into this view, we suggest that you use the database context information. The CONTEXT_INFO is an array of bytes
that is initialized by the system with the data segregation information. See the following table.

System Apps
Byte Provided Information Example
byte 1, bit 0 If the Data Segregation functionality is

enabled or not
SELECT (CONVERT(tinyint,0x1)
& SUBSTRING(CONTEXT_INFO(),
2, 1))
byte 18-33 The ID of the current session

(SessionId)
SELECT
SUBSTRING(CONTEXT_INFO(), 19,
16)
 • The NULL value of the CONTEXT_INFO is the same as the Data Segregation App which is not loaded.
• Bytes from 1 to 34 are reserved.
2.5.7.2.1.2 Example of Oracle View
CREATE OR REPLACE VIEW "ThirdParty "."wMinimalA_Siemens_Si_587277339" AS
SELECT
t.*, ORA_ROWSCN
FROM "ThirdParty "."MinimalA_Siemens_Si_587277339" t
WHERE t."IsDeleted" = 0 AND t."Id" NOT IN
SELECT
M2M."MinimalA_Id"
FROM "ThirdParty "."MinimalA-To-Segrega_160371995" M2M
LEFT JOIN "ThirdParty "."__SessionSegregationTags" U ON U."TagName" = M2M."Name" AND

U."SessionId" = SYS_CONTEXT("ThirdParty ".PKG_COMMON.FCN_GET_CONTEXT_NAME,
'SessionId')
WHERE U."TagsCollectionHash" IS NULL
AND (SYS_CONTEXT("ThirdParty".PKG_COMMON.FCN_GET_CONTEXT_NAME,
'UntaggedDataVisibility') = 1 OR t."Id" IN (SELECT "MinimalA_Id" FROM " ThirdParty "."
MinimalA-To-Segrega_160371995"));

System Apps
2.5.7.2.2 Integrating Data Segregation in Third-Party Business Logic

Here we provide you a guideline to integrate Data Segregation in Third-Party Business Logic.
Workflow
 The SessionAlignment and SessionAligned events are available as referenced system events inside the
model project in Project Studio for Functional Blocks, Apps and Extension Apps.
Procedure
 Pay attention to the timeout expiration when performing these steps.

1. Create an event handler for the SessionAligned event (see SystemData.Foundation reference documentationin
the Foundation Model Reference Guide).
2. Invoke the GetSessionSegregationInfo IUnifiedSdk platform method to retrieve all session tags and all
selected session tags (see Invoking Commandsand Raising Events).
3. Implement custom business logic to manage session tags, for example by storing segregation tags in a third-
party database.
4. Notify the end of the operation by firing the SessionAligned event (see Raising Events). This operation needs to
be always performed in the SessionAligned event handler. For reference information on SessionAligned event
5. If the session token is refreshed from the User Interface the system fires a SessionUpdated event with a new
expiry date. Create an event handler to subscribe to this SessionUpdated event and to implement the business
logic required to update the expiry date of the session. For reference information on the SessionUpdated event
6. Create an event handler for the SessionSelectedChanged event defined in the DSG_SD Functional Block in
order to update the Selected flag of the session tags.
7. If a user logs off, the system triggers a SessionDeleted event. Create an event handler to subscribe to this
SessionDeleted event and to implement the business logic required to clear the session. For reference
information on the SessionDeleted event parameters, see the SystemData.Foundation reference
documentation.
8. In the App, create a predefined event subscription for the SessionAlignment event (see Configuring Event
Subscriptions). The SessionAlignment event contains an expiry date for the session. If the session expires the
third-party App must implement the business logic necessary to clear the session. We suggest that you create a
predefined event subscription also for the SessionUpdated and SessionDeleted events.
 The third-party App must implement the required business logic to clear expired session records, even
when the SessionDeleted event is not triggered.

System Apps
2.5.7.3 Logging Operations on Data Segregation Tags

In order to log operations performed on Data Segregation tags, you can mark a specific tag as log relevant and then
register a set of information, similarly to the Audit Trails. The information you can track is the following:
• creation, update and deletion of a tag,
• association or disassociation of a tag to/from a person or a group,
• assignment or unassignment of a tag to/from an entity instance.
This information is stored in the SegregationLog data structure, which can be directly queried from the code of a
command/event handler via Platform APIs (Query, ProjectionQuery), or from the code of a UI screen via OData
query (a system defined page to display Data Segregation Logs is provided in the Data Segregation App).
Unlike the Audit Trails, the system does not fire any event when a record is added to the SegregationLog table.
For information on how to set a tag as logging relevant, see Creating Segregation Tags.
SegregationLog data structure

SegregationTag Name of the Segregation Tag that has been marked as tracking relevant.
InvolvedEntityId Unique identifier of the Entity instance, to/from which the relevant segregation tag
has been assigned or unassigned.
InvolvedEntityType Full name of the Entity Type, to/from which the relevant segregation tag has been
assigned or unassigned.
InvolvedEntityName Logical key of the Entity instance, to/from which the relevant segregation tag has
been assigned or unassigned.
InvolvedEntity For future use. This attribute will contain the JSON representation of the changes
applied to the Entity instance (or facet instance), to/from which the relevant
segregation tag has been assigned or unassigned.
Action Type of change. Possible values are:

• Created, Updated, Deleted for creation, update and deletion of the tag,
• Assigned, Unassigned for assignment or unassignment of the tag to/from an
entity instance,
• Associated, Disassociated for association or disassociation of the tag to/from
a person or a group.
UserName Full name of the user who performed the action.
Environment The environment where the change occurred. It is defined during the environment
configuration phase (see Opcenter Execution Foundation Installation Guide).

System Apps
Signals App
Channel For future use. This attribute will identify the type of channel referring to the
performed operation. It is now set to 0 and refers to the Writing Channel.
TransactionId Transaction Identifier.
2.6 Signals App

The Signals App provides pages where it is possible to create and configure signal rules in a user-friendly
environment.
The Signals App also allows you to import and export signal rules, and modify or refine their configurations without
needing to open the original development environment.
The App references the following Functional Blocks:
• SGN_MS
• SGN_SD
• UDM_RF
What can I do in the Signals App?

• What Are Signal Rules? provides useful conceptual information.
• Predefined User Roles for Signal Rules explains how to manage signal rules securely through specific user roles.
• Signal Rule Configuration and Runtime States helps you to understand the stages through which signal rules
pass.
• How to Manage Signal Rules describes the configuration workflow and procedures.
2.6.1 What Are Signal Rules?

A trigger is generated when a monitored artifact (source) changes, and you want to activate a specific consequent
action, such as an App command.
To do this, you must configure a Signal Rule, that represents a one-to-one relationship between a trigger and the
logic that must be activated.
For the same trigger you can configure multiple Signal Rules.
The artifacts that can be used as trigger sources are entities, automation entities, or signals (i.e. entities or events
already promoted to signals).
The Signals App provides a Signal Rule Management editor which makes it easy to create complex signal rules in a
user-friendly interface, using the artifacts available from all the Apps present in the solution.
Configuration phases
The life cycle of the rule consists of two main phases:
1. Definition and configuration: in this initial phase, you can configure the Signal Rule by:

System Apps
Signals App
• setting the execution mode either to sequential or parallel,

• selecting a trigger source, such as an entity (e.g. a material tracking unit, a work order, a task etc), a business
event or an automation node type or instance,
• optionally, gathering additional information from other Apps in your solution, by creating queries (for
limitations on the usage of query blocks, please see the Parallel vs Sequential Execution Mode paragraph
below),
• optionally setting trigger conditions through a configurable filter,
• selecting the subsequent action, which will take place when all the specified conditions are satisfied,
• connecting the output parameters of the trigger source to the input parameters required by the triggered
command.
• Activation and deployment: this stage involves the approval and deployment of the completed Signal Rule.
Once successfully deployed, the runtime status of the Signal Rule will be Running and the command it triggers
can effectively be launched.
Parallel vs Sequential Execution Mode

By default Signal Rules are executed in parallel, according to the overall Opcenter EX FN architecture that has been
designed to maximize performance and scalability, and for this reason it strongly leverages asynchronous patterns
where execution of logics is demanded to parallel threads.
Nevertheless, there are some use cases where requests that come first must be served and executed first. This
means avoiding parallelism in favor of sequential execution.
For example it could be necessary to execute Signal Rules sequentially in order to manage rules in the following
way:
• processing all incoming triggers one at a time in a sequential way
• starting a Signal Rule instance after the previous Rule has invoked the action
• queuing all further incoming triggers
 Beware that the sequential and synchronous behavior is not optimal in terms of performance and system
scalability because sequential long running logics could act as bottlenecks. Consequently, you should
always carefully evaluate the logic you are planning to execute sequentially.

System Apps
Signals App
 • Signal Rules with execution mode set to sequential cannot contain query blocks.
• A sequential Signal Rule does not guarantee the sequential execution for the commands it invokes in
the action block. To achieve this behavior, you must explicitly associate the required commands to a
sequential Worker Role (see Configuring Worker Roles in the Opcenter Execution
2.6.2 Predefined User Roles for Signal Rules

Predefined user roles are provided with the Signals App to improve security when performing key operations, such
as deploying a Signal Rule.
These user roles are displayed only when the Signals App has been installed in the solution.
User roles have been defined to cover all operations involved in the signal management process.
These user roles can then be assigned to groups and users in Solution Studio.
 Users that are not assigned to at least one of these predefined roles will not be able to use the Signals App.
For details on how to do this, see the page Configuring Roles in the Opcenter Execution Foundation Development and
Predefined user roles

User View Create Edit Import/ Approv Deploy Disable View Re-
Role Rules Rules Rules Export e Rules Rules Rules Executio Execute
Rules n History Rules
SignalRu
lesAdmin
SignalRu
lesEngin
eer
SignalRu
lesViewe
r
2.6.3 Signal Rule Configuration and Runtime States

There are two types of status for Signal Rules in the Signals App:
• Configuration Status
• Runtime Status
Configuration Status
The configuration status defines the status of a Signal Rule during its modeling phase in the Signal Rule
Management.

System Apps
Signals App
Configuration Status Description
New The Signal Rule's status may be New in these scenarios:

• the Signal Rule is in its initial creation phase and has not yet been
deployed.
• the Signal Rule has just been imported and needs to be approved.
• the Signal Rules was deployed, but was then disabled and
modified. It now needs to be approved and deployed again to put it
back in execution.
• the Signal Rule was deployed and was then deleted without first
disabling its runtime execution. To be effectively deleted it must
now be approved and deployed again to align its runtime status.
In editing The Signal Rule has been approved and deployed and is now being
modified without being previously disabled. This may cause a
misalignment between the configuration and runtime status.
Deployed The Signal Rule has been deployed and is consequently in execution.
Rules with this status can be disabled to stop their runtime execution.
This is mandatory before deleting a deployed rule, and can be
performed before modifying a Signal Rule in order to avoid a possible
misalignment between the configuration and runtime status.
Disabled The signal rule's execution has been stopped.
Deleted The Signal Rule has been deleted, but its runtime status needs to be
aligned in order for it to be definitively removed. See Deleting Deployed
Signal Rules for further information.
If a configuration status change is not successful, one of the following error types is displayed in the Requires
Attention column next to the Signal Rule:
• for System Information
• for a System Warning
• for a System Error, which requires user intervention. To check what the problem may be, you can select
the rule, click the Overview button and see its Last Message field in the Overview Signal Rule pane.
A configuration error may occur, for example, if you try to approve a Signal Rule without configuring its action
tile.
Runtime Status
The runtime status defines the execution status of a Signal Rule once it has been deployed.

System Apps
Signals App
Runtime Description
Status
Running The Signal Rule has been successfully deployed and it is in execution on the active host. Related to
this status, the following situations might occur:
• If the Signal Rule is running on the active host but a deploy error occurs on a stand-by host, the
Runtime status will be Running with the following warning (identified by the icon in
the Requires Attention column, and visible only in the details pane) Deploy failure on one or
more hosts. Please be aware that this rule is not guaranteed to run in case of a switch of the
active host. A possible approach to solve this situation could be to redeploy the rules. After an
additional deploy attempt, the rules will go in Running status without any warning if the
infrastructural problem, which previously prevented the deploy, was temporary and it is now
solved. If this is not the case, further investigations might be required on the server side by
means of other troubleshooting tools such as ETW Viewer.
• If you modify and approve an already deployed signal rule, the rule status remains Running
but the following warning Runtime must be aligned is returned to inform the user that the
running version of the rule differs from the rule which is currently approved. In this case, the
icon is displayed in the Deployed column (and not in the Requires Attention column).
• If you are deploying rules in a distributed environment, you should always check the status of
all the standby hosts in the Opcenter EX FN Worker Monitor tool (see Monitoring Worker
Runtime Instances in the Opcenter Execution Foundation Development and Configuration
Guide). Since the standby hosts do not return information to the current Signal Rule
Management page, if these hosts were not running, they would not be able to execute the
Signal Rules in case of failover switch.
Warning If the signal rule involves an Automation entity type and this rule is running without warnings (
), if the Automation Gateway Server disconnects from the HMI RTIL Platform, the rule
temporarily goes to Warning status and this situation should be automatically solved after the
Automation Gateway Server reconnects to the HMI RTIL Platform.
If the same Signal Rule is running with warnings, after the reconnection to the HMI RTIL Platform,
the rule returns Running with warning ( ).
Stopped The Signal Rule execution has been disabled.

System Apps
Signals App
Runtime Description
Status
Error The following situations might occur:

• If the Error status appears on one single Signal Rule after the deployment operation, the error
can indicate that the signal rule deployment failed on the active host.
• If all Signal Rules return the Error status, it could be due to a general failure caused by a single
rule which prevents High Availability groups from executing rules on another host. If this were
the case, you should open the Worker Monitor and check the High Availability group state (all
groups should be in error in this situation) and then check further error details on the failed
rule in the Windows Event Viewer (see Persisting System, Security and Application Messages on
Microsoft Event Viewer in the Opcenter Execution Foundation Development and Configuration
Guide).
 Runtime errors can be checked in the Signal Rule log and trace files.
2.6.4 Signal Rule Supported Data Types

Signal Rules support all data types with some limitations explained here below.
All properties with simple data types (e.g. string, int, boolean), including enumeration types, are always supported.
Data Type Supported
Simple types (Bool, Integer, Decimal, (always supported, except for the Timespan that is not supported
DateTime, Guid, Blob, Timespan) inside Query Blocks)
List of Simple Types ( with some limitations: list of simple types are not available for
filtering in Source and Query Block. In Filter block "Any" and "Not Any"
are the only available operators.
For more information, see Selecting the Signal Rule Trigger Source
(Source Block), Adding Source Queries to Signal Rules (Source Query
Block), Configuring Filters for Signal Rules (Filter Block) and Adding
Filter Queries to Signal Rules (Filter Query Block)).
Enumeration Types (always)
List of Enumeration Types (if defined as optional, they are shown in Action block but cannot be
wired in Transform. For more information, see Configuring Actions for
Signal Rules (Action Block).
It is not managed in Query Block in Enable List configuration. For more
information, see Adding Source Queries to Signal Rules (Source Query
Block) and Adding Filter Queries to Signal Rules (Filter Query Block)).
Value Types (always)

System Apps
Signals App
Data Type Supported
List of Value Types (in Query Block in Enable List configuration is possible to select only
one child of a Value Type field. For more information, see Adding Source
Queries to Signal Rules (Source Query Block) and Adding Filter Queries
to Signal Rules (Filter Query Block)).
Parameter type containing simple (always)

type properties
List of Parameter type containing (if optional they are shown in Action block but cannot be wired in
simple type properties Transform. For more information, see Configuring Actions for Signal
Rules (Action Block)).
Parameter Type containing (if mandatory)

Parameter Types
List of Parameter type (if optional they are shown in Action block but cannot be wired in
containing Parameter Types Transform. For more information, see Configuring Actions for Signal
Rules (Action Block)).
2.6.5 How to Manage Signals Rules

To create, configure and deploy Signal Rules in the Signals App, the following steps must be performed.
Workflow
1. Create a Signal Rule.
2. Configure the Signal Rule:
• Select a Signal Rule source.
• Add source queries to Signal Rules (optional).
• Combine source and query data (mandatory if additional queries have been configured).
• Configure a filter on the selected source (optional).
• Add filter queries to Signal Rule (optional).
• Select an action.
• Transform the parameters of Signal Rules.
• Check the consistency of Signal Rules.
3. Execute the Signal Rule.

System Apps
Signals App
2.6.5.1 Creating Signal Rules

There are a number of different ways to create Signal Rules in the Signals App:
Creation Operation Description

method
Creating a new Add This is the basic operation for creating a completely new Signal Rule.
Signal Rule from
scratch
Copying an Copy Signal Rules can be copied, regardless of their status, simply by providing a
existing Signal new unique Id.
Rule
This can save substantial time when creating a new Signal Rule, which is very
similar to an existing rule. The status of copied signals is New.
Importing a Import Signal rules that have been exported, using the Export function in
previously the Signal Rule Management page, are saved in the deployment folder in a
exported Signal JSON file.
Rule
This file must not be modified.
When new rules are imported various checks are performed to ensure the
imported file is valid:
• Only well-formed JSON files with a maximum size of 50MB are imported.
• An internal check is performed on the JSON file before it is imported,
ensuring that its contents have not been accidentally modified.
• If the model of the running solution changed (commands, entities,
signals, Automation types/instances), Signal Rules configured may be
rendered invalid. In particular, an error may return when deploying the
Signal Rule or the signal rule may not work properly at runtime.
Depending on the involved signal rule, do either of the following:
• Open the query editor to update the rule structure to the most
recent version of the solution and then save the query to persist
this information on the database.
• Click Reload to ensure the signal source/action data you are
viewing is aligned with the most recent version and then save the
information.
Prerequisites
The user performing this operation belongs to the SignalRulesAdmin or SignalRulesEngineer role.
Creating a new Signal Rule from scratch

1. Do either of the following to open the Signal Rule Management page:
• Click the Signal Rule Management home tile.
• Click Signal Rule Management in the side menu bar and click Signal Rule Management.
2. In the Signal Rule Management page, click .

System Apps
Signals App
Attribut Description
e
Id A unique identifier for the new Signal Rule. The Id cannot successively be
modified. The Id value can only contain alphanumeric characters.
Name A name for the new Signal Rule.
Descripti A description for the new Signal Rule.

on
Templat (Read-only) The template that will be applied to the rule. Currently there is only one option
e available.
Executio Specifies how to execute the Signal Rule and you can choose one of the following options:
n Mode
• Parallel
• Sequential
For more information see What Are Signal Rules?.
Executio Specifies how to configure the execution history of the Signal Rule and you can choose one of
n History the following options:
• Disabled (default): information on the execution history is never stored.
• Enabled: information on the execution history is always stored.
• Enabled only in case of errors: information on the execution history is stored only if
the Signal Rule execution fails.
If set to Enabled or Enabled only in case of errors, the information on the execution history of
the Signal Rule will be stored in the Signal Rule Execution History page.
4. Click either Save to save and close or Save and Config to save the new rule and start configuring it.
Copying an existing Signal Rule

2. In the Signal Rule Management page, select the rule you want to copy and click .
3. Enter a unique Id to identify the new copied rule. The Id cannot successively be modified.
4. Modify name and description of the Signal Rule and configuration of the Signal Rule execution history, if
required. These values can be modified. If you leave these fields empty you will effectively delete the saved
value.
5. Click Save to save and close or Save and Config to save and configure the Signal Rule.
Importing a previously exported Signal Rule

System Apps
Signals App
To use Signal Rules securely, the system provides you with a set of predefined roles. These roles guarantee
that permissions, especially administrative permissions, are divided in such a way as to minimize the risk
of elevation privilege. To prevent unauthorized users from tampering with Signal Rules, the least privilege
principle should be applied when assigning users or groups.

2. In the Signal Rule Management page, click .
3. Browse for the JSON file of the Signal Rules you want to import under Signal Rules to Import.
4. Select the Overwrite existing rules check box if you want existing rules to be updated with the imported rules.
5. Click Import. You can now configure the Signal Rule.
 Signal Rules can be easily modified and deleted while they are still in the configuration phase and have not
been deployed, by using the following buttons:
• Edit to modify name and description of the Signal Rule and configuration of the Signal Rule
execution history.
• Open to modify the configuration of the Signal Rule, such as its source signal or filter.
• Delete to remove a Signal Rule from the list.
Deployed Signal Rules can be modified and deleted, but require extra steps to be performed.
The Signal Rule Management page provides common functionalities such as Group By, Quick Search,
Filter and User Preferences. The Filter functionality provides a more refined search in addition to Quick
Search. You can filter Signal Rules by Id, Configuration Status, Runtime Status, Hide
Approved and Hide Deployed.
2.6.5.2 Configuring Signal Rules

Once you have created a Signal Rule in the Signal Management page in the Signals App, you can configure it to
react to changes by applying filters and running commands.
The configuration operation takes place in the Signal Rule Management.
Workflow
The configuration phase of a Signal Rule consists of the following main phases:
• Select a Signal Rule source.
• Add source queries to Signal Rules (optional).
• Combine source and query data (mandatory if additional queries have been configured).
• Configure a filter on the selected source (optional).
• Add filter queries to Signal Rule (optional).
• Select an action.
• Transform the parameters of Signal Rules.
• Check the consistency of Signal Rules.

System Apps
Signals App
2.6.5.2.1 Selecting the Signal Rule Trigger Source (Source Block)

To start configuring a Signal Rule in the Signals App you must select a source.
The source is the artifact type that acts both as trigger and as the source information for the Signal Rule.
Triggers are sent when changes occur to a certain artifact type, which you have defined as the source of your Signal
Rule.
The following artifacts can be selected as Signal Rule sources:
• entities that have been published in the Public Object Model of the App. Note that only entities whose names do
not contain reserved keywords will be displayed, as described in Reserved Keywords of the Opcenter Execution
Foundation Development and Configuration Guide. As far as Automation entities are concerned, in this list you
will find the engineering entities available in the Master Data Domain.
• Signals promoted in the App (i.e. events or entities that have been promoted to Signals in the App, see
Publishing Artifacts as Signals in the Opcenter Execution Foundation Development and Configuration Guide).
• Timer events that are fired by the Timer you are configuring.
• Automation Node Types, to be notified when any of the Automation Node Instances, created from the specified
Automation Node Type, change. These entities correspond to the entities deployed to the Operational Data
Domain, after the runtime activation.
• specific Automation Node Instances. These entities correspond to the entities deployed to the Operational Data
Domain, after the runtime activation.
The first time you configure a Signal Rule, the Signal Rule Configuration page will open automatically on the
Source Type tab.
 • All parameters belonging to the Automation Node Type Source or the Automation Node Instance
Source are available with their updated value in the Signal Rule Configuration Blocks, even if you did
not select them in the Automation Source Block. For this reason, you need to select only the
parameters required to trigger the Signal Rule.
• Automation parameters may change their values very frequently and can quickly cause data
saturation. A form of filtering logic can be applied server-side within the Automation App through the
smoothing function, which consequently reduces the volume of notifications.
• The data model used as trigger source can change frequently. You can click Reload to ensure the data
you are viewing is aligned with the most recent version, and then save the information. The Reload
operation updates the entity, business event or Automation type/instance structure, including value
types and parameter types.
Prerequisites
• The user performing this operation belongs to the SignalRulesAdmin or SignalRulesEngineer role.
• For Business Event source types: events must have been published as a signals (and subsequently deployed in
the installed App) in order to be accessible from the Signals App. For details on how to publish events as signals
see Publishing Artifacts as Signals in the Opcenter Execution Foundation Development and Configuration Guide.
• For Automation Node Type and Automation Instance source types:
• the Automation App is installed and deployed
• the runtime integration of the Automation Gateway App has been activated and there is at least one
activated Automation Node.
• the user performing configuration operations must have the following access rights:
• access rights to execute the GetAutomationDescriptor Reading Function
• access rights to read
the AutomationNodeInstance, AutomationNodeType, AutomationNodeTypeParameter,
AutomationNodeInstanceParameter Automation Entities.

System Apps
Signals App
These rights can be assigned either by creating a new role from scratch or copying a predefined
signal role and modifying it as described in Creating Roles of the Opcenter Execution
Procedure
2. In the Signal Rule Management page, select the Signal Rule you want to configure and click .
3. With the Source Block selected, in the Configure Source Block pane, in the Source Type tab, click on the tile
corresponding to the type of source you want to use by choosing one of the following and then click Next:
• Entity Added/Modified, to be notified when a specific entity, published in the Public Object Model of its
App, is added or modified.
• Entity Deleted/Frozen/Locked/MarkedForCleaning, to be notified when a specific entity, published in
the Public Object Model of its App, is deleted, frozen, locked or marked to be cleaned.
• Business Event, to be notified when an event, promoted to signal in its App, is fired.
• Time Based, to be notified when a timer event is fired.
• Automation Type, to be notified when the selected Automation Parameters of activated Automation
Instances created from the specified Automation Type change
• Automation Instance, to be notified when the selected Automation Parameters of a specific activated
Automation Instance change.
4. In the Properties tab, set the required properties, according to the artifact you have chosen. Click Save and
then Next.
Source type Properties to set
Entity Added/Modified Select the required App and then the required entity from the
drop-down list.
Its structure is displayed, with a list of simple properties and
value types. If you click on value types, the properties they
contain will be displayed. This source type notifies you when
an entity is added or modified.
Entity Deleted/Frozen/Locked/ Select the required App and then the required entity from the
MarkedForCleaning drop-down list.
The ID if the entity is displayed. This source type notifies you
when this entity is frozen, locked, deleted or marked to be
cleaned.
Business Event Select the required App and then the required event from the
drop-down list.
Its structure is displayed, with a list of its parameters.
Clicking on complex parameters will display the parameters
they contain. Lists of Enumeration Types and lists of
Parameter Types are displayed in gray color because they are
not supported.

System Apps
Signals App
Time Based Set the following properties:

• Start Time: indicates the time when the Timer is
scheduled to start.
• Start Date: indicates the date when the Timer is
scheduled to start.
• Timer Expiration: indicates when the Timer is
scheduled to stop.
• Time Zone: indicates the time zone in which the
Timer is configured.
• Schedule Mode: indicates the type of recurrence
(minute, hourly, daily or weekly).
• Recurs Every: indicates the number of minutes/
hours/days, depending on the configured
Schedule Mode. If you have configured the
weekly schedule, you can set one or more days of
the week.
• User Fields: indicates the UserFields values of the
Timer event at runtime.
 If the Signal Rule is deployed after the configured

start and date time, the Timer will be created and
started in order to guarantee the configured
recurrence (defined by setting Schedule Mode and
Recurs Every). For example, if you have configured
the Timer as follows:
• Start Time: 04:00 PM
• Start Date: today
• Schedule Mode: hourly
• Recurs Every: 2 hours
if the Signal Rule is deployed tomorrow at 05:00 PM,
the Timer event will be fired at 06:00 PM anyway.
Automation Type Select the required Automation Node Type Id from the drop-
down list. If you want to receive the values of the Automation
Type every time the Signal Rule executes, including the first
run and when the Automation Gateway Server reconnects to
the Opcenter Execution Foundation host, select the Enable
Initial State check box. If left unchecked, the values
corresponding to the initial execution and any reconnections
of the Automation Gateway Server to the Opcenter Execution
Foundation host will be discarded.
The structure of the Automation Type is displayed, along
with its Automation Parameters. Select at least one
Automation Parameter to be notified on.

System Apps
Signals App
Automation Instance Select the required Automation Node Instance Id from the
drop-down list. If you want to receive the values of the
Automation Instance every time the Signal Rule executes,
including the first run and when the Automation Gateway
Server reconnects to the Opcenter Execution
Foundation host, select the Enable Initial State check box. If
left unchecked, the values corresponding to the initial
execution and any reconnections of the Automation Gateway
Server to the Opcenter Execution Foundation host will be
discarded. The structure of the Automation Instance is
displayed, along with its Automation Parameters. Select at
least one Automation Parameter to be notified on.
5. In the Source Filter tab, set a filter according to the artifact you have chosen:
Selected Source Type.. Properties to Set...
Entity Added/Modified Select the required operations (Added, Modified). If no filters are
selected, you will be notified on all listed items.
Entity Delete/Frozen/Locked/ Select the required operations (Deleted, Frozen, Unfrozen,

MarkedForCleaning Locked, Unlocked, MarkedForCleaning). If no filters are
selected, you will be notified on all listed items.
Business Event Click Add new envelope and specify the field, operator and value
you want to filter by. Fields containing list of simple types are not
available for filtering because not managed. The filter on
envelopes will apply the OR operator, whilst the individual fields
within each envelope will apply the AND operator. For more
information on firing events with envelopes, see Raising Events in
the Opcenter Execution Foundation Development and
Time Based No filer is available.
Automation Type Use the Filter expression editor to create a filter in order to be
notified only when specific conditions are satisfied for selected
Automation Parameters. The filter is applied only if the Quality
Status associated with the Automation Parameter value
is Good. Changes made to the Automation parameters quality
trigger the Source Block even if a filter is configured. Parameter
defined as list of simple types are not available for filtering
because not managed.

System Apps
Signals App
Selected Source Type.. Properties to Set...
Automation Instance Use the Filter expression editor to create a filter in order to be
notified only when specific conditions are satisfied for selected
Automation Parameters. The filter is applied only if the Quality
Status associated with the Automation Parameter value
is Good. Changes made to the Automation parameters quality
trigger the Source Block even if a filter is configured. Parameter
defined as list of simple types are not available for filtering
because not managed.
 If the App you selected has Extension Apps, the artifacts of the Extension App will also be displayed in
the list.
The configured artifact will now be displayed in the Source Block.
2.6.5.2.2 Adding Source Queries to Signal Rules (Source Query Block)

Only if the execution mode of the created signal rule is parallel, you can enrich the source data for the Signal Rule
by adding up to five source queries.
Source queries add additional information from the manufacturing data model, which is then joined together to
generate new types in the Combine diagram block and use these types in input to the invoked action.
Queries can also be expanded to include related entities and facets.
 Whenever you open the query editor, the structure of the displayed entities (including value types) are
updated and aligned to the most recent version of the solution.
However, it is necessary to then save the query to persist this information on the database.
Example
A Signal Rule is configured with the business event TaskStatusChanged as its source. One of the parameters of the
event is TaskId (Guid), which represents the ID of the task that has changed status.
The Query block could then be configured to retrieve the task in question, using the ID provided in the TaskId
parameter.
To create this scenario, the following condition must be used in the query block: Id = TaskStatusChanged.TaskId.
The Query Block can be configured with two different behaviors:
• retrieving all selected fields of a single Entity
• retrieving only one field of a list of Entities. In this case, the output of the Query Block is a list of values of the
selected field.
Prerequisites
• The user performing this operation must have reading permissions for the entities involved in the query. These
permissions can be assigned to a custom user role either by creating a new role from scratch or copying a
predefined signal role and modifying it. For details on how to do this see Creating Roles in the Opcenter

System Apps
Signals App
• If the source entities include Automation Entities, additional user rights are required.
• The Signal Rule is not configured for sequential execution (queries can only be added to parallel Signal Rules).
Procedure
 The data type of the properties cannot be Timespan. For the supported data types, see Signal Rule
Supported Data Types.

3. In the Signal Rule Editor, select the SourceBlock and click Add Source Query.
4. In the Configure Query Block pane, in the Query Type tab, select the Query Type tile and click Next.
5. In the Properties tab, enter a name for your query.
6. (Optional) Select the Is Relevant check box. If selected, the execution of the Signal Rule fails if the selected
query fails or does not return any data.
7. (Optional) Select the Enable List Query check box. If selected, the query will retrieve a list of the selected field
of the chosen Entity.
8. In the App list box, select the App you want to use for your query. If the App you selected also has Extension
Apps, the entities belonging to these Extension Apps will also be displayed.
9. If Enable List Query check box is selected, the maximum value of entities retrieved must be chosen. Only some
values are supported (25/50/75/100).
10. Select either Related Entities or Facets in the Query Extensibility Behavior area if you want to expand query
entities through related entities or facets. Note that the Order by function is not available for facets.
11. In the Entity list box, select the entity you want to use for your query.
12. Click the Expand tab and select the required entities, according to the extensibility settings you configured in
the previous step.
13. Click the Select tab and select which properties will be included in the query. If Enable List check box is
enabled only one field can be selected. In Enable List configuration Enum fields are not shown because they are
not managed and only child items of Value Type fields can be selected.
14. (Optional) To configure how the results are displayed, click on the Order by tab, and select the properties you
want to order by, specifying ascending or descending order. Note that the Order by function cannot be used for
facets.
15. Click the Filter tab and select the fields you want to filter by, and the operator, and in the Value edit box either:
• click Field, to select a property from the source block. Only properties with compatible data types
will be displayed. Properties containing lists are not available because not managed.
• click Constant, to enter a fixed value, along with its data type.
16. When you have completed the query configuration click Apply, or Reset to start over. Note that if the query
results have already been used in successive Signal Rule diagram blocks (Combine, Filter or Transform) a
warning message will be displayed, and confirmation is required before the reset operation will be executed.
17. Click Save.
18. To preview the results of the query, click View Result.
19. Combine the results of the query with the data from the source artifact in the Combine diagram block.

System Apps
Signals App
 To delete a query block, simply select it and click Remove Source Query.
Bear in mind that deleting a query block could invalidate other successively configured blocks. For
example, if the results of the query had already been used in the filter diagram block.
2.6.5.2.3 Combining Source and Query Data (Combine Block)

The data deriving from the source artifact and from any additional queries performed must be merged together in
the Combine diagram block.
If you have configured additional queries, you must configure the Combine diagram block to make the data, which
is retrieved from the queries, available for the Action diagram block. If a combine diagram block is available, then it
must also contain the source relevant data, otherwise the source data will not be available in the Transform
diagram block.
If you have not used the Query diagram block, you do not need to go through the Combine diagram block.
Moreover, you can create new types using the data retrieved from the Query diagram block. New types can be then
filtered or conveniently transformed for final action invocation.
Prerequisites
• If the source entities include Automation runtime entities, additional user rights are required.
Procedure
2. In the Signal Rule Management page, select the signal rule you want to configure and click .
3. In the Signal Rule Editor select the Combine Block diagram block.
4. In the Combine Type tab, select the combine type tile and click Next.
5. In the Properties tab, click the browse button next to the Expression edit box.
6. In the Combine Editor click Add New Property.
7. Enter a name for the new type in the Field edit box.
8. In the Wiring Type do either of the following:
• Click Constant, select a data type from the Value drop down list, and type the required value.
• Click Field and select the required property from the Value drop down list.
 If the data type of the property for the Constant is TimeSpan, the manually entered value must
use the format d.HH:mm:ss, where d is optional and represents days between 0 and 10675199,
HH represents hours between 0 and 23 and mm / ss represents minutes / seconds between 0
and 59. For example, "100.13:59:01", "13:59:01".
9. After you have created all the properties you require, click Save.

System Apps
Signals App
2.6.5.2.4 Configuring Filters for Signal Rules (Filter Block)

Once you have selected the source, you can optionally apply filters on source artifacts, so that you can refine the
conditions for which the Signal Rule will be executed (for example, among the entities defined as trigger source, you
may want only the entities that have property x greater than y).
Consequently, if the filter query does not return anything, the rule execution is blocked.
To configure the filter you can select the fields as follows:
• either from the Source diagram block (if no queries have been configured)
• or from the Combine diagram block only, if queries have been defined.
After configuring the fields, select an operator that will be used for the filter clause, and set the required values.
 If you add a Query after having defined the Filter, you must redefine the Filter according to the new
Combine block properties.
Filter clauses can be grouped into two or more clauses and are case sensitive.
Prerequisites
• The source has been defined for the Signal Rule.
• If the artifact (from the Source or Combine block) used in the filter contains only an enum in its property list,
and no other properties, this enum must not be nullable.
Procedure
3. In the Signal Rule Editor select the Filter block.
4. Click the Expression browse button in the Properties tab of the side panel.
5. Select the field on which you want to filter from the Field drop-down list.
 In case of Automation Type or Automation Instance sources, you can apply criteria on the
Automation Parameter value, on the value attributes (such as the timestamp, the quality status and so
on, which are documented in the IAutomationValue Properties of the Opcenter Execution
Foundation Platform Reference Guide) including the possibility to execute the Signal Rule when the
Automation Parameter value changes (for example, if data value or parameter quality status change).
To do this, you must select from the Field drop-down list the AutomationParameter/IsChanged
attribute and set it to true/false.
6. Select the required operator and corresponding value. The operator depends on the selected field value.
7. Insert the required value for the filter, either by clicking Constant and manually entering a value, or by
clicking Field and selecting it from a list of possible values.

System Apps
Signals App
 If the data type of the property for the Constant is TimeSpan, the manually entered value must use the
format d.HH:mm:ss, where d is optional and represents days between 0 and 10675199, HH represents
hours between 0 and 23 and mm / ss represents minutes / seconds between 0 and 59. For example,
"100.13:59:01", "13:59:01".
If the property is a List of data type the available operators are Any/Not Any (i.e the list contains at
least one value/the list does not contain any value) and it is not possible to configure the Filter with a
Constant value.
8. If you want to group filters, select the check box for each filter clause you want to group, and then
select And or Or for the first clause in the group.
 To add new clauses click Add New Clause, and select whether the new clause is additional or in
alternative to the first clause by selecting And or Or. To remove existing clauses, click .
9. Click Apply: the configured filter will now be displayed in the Filter Diagram Block of the Configuration tab.
2.6.5.2.5 Adding Filter Queries to Signal Rules (Filter Query Block)

Only if the execution mode of the created Signal Rule is parallel, you can enrich the Signal Rule with further
information from the manufacturing data model, by adding up to five filter queries.
Filter queries add additional information to the Transform diagram block, which matches up the parameters from
the source data stream with those of the final action to be invoked.
Queries can also be expanded to include related entities.
After the Filter Query block, there is no Combine block since at this point of the Signal Rule configuration you will
bind parameters directly in the Transform block.
The Filter Query Block can be configured with two different behaviors: retrieve all selected fields of a single Entity or
retrieve only one field of a list of Entities. In this last configuration the output of the Query Block is a list of values of
the selected field.
 Whenever you open the Query editor the structure of the displayed entities (including value types) are
updated and aligned to the most recent version of the solution.
However, it is necessary to then save the query to persist this information on the database.
Example
A Signal Rule is configured with the business event TaskStatusChanged as its source. One of the parameters of the
event is TaskId (Guid), which represents the ID of the task that has changed status.
The Query block could then be configured to retrieve the task in question, using the ID provided in
the TaskId parameter.
To create this scenario, the following condition must be used in the query block: Id = TaskStatusChanged.TaskId.
Prerequisites
• If the source entities include Automation Entities, additional user rights are required.

System Apps
Signals App
Procedure
3. In the Signal Rule Editor, select the Filter Block and click Add Filter Query.
4. In the Properties pane on the right, click on the Expression browse button.
5. In the Query editor, enter a name for your query and specify the App and specific entity you want to use for your
query.
6. Select the Is Relevant check box if required. If selected, the execution of the Signal Rule fails if the selected
query fails or does not return any data.
7. Select the Enable List check box if required. If selected the query will retrieve a list of the selected field of the
chosen Entity.
8. If Enable List checkbox is selected the maximum value of entities retrieved must be chosen. Only some values
are supported (25/50/75/100)
9. To include related entities in the query, such as the entity's facets, click the Expand tab and select the required
entities. The properties of the selected related entities will be displayed in the Select tab.
10. Click on the Select tab, and select which properties will be included in the query. If Enable List check box is
enabled only one field can be selected. In Enable List configuration Enum fields are not shown because they are
not managed and only child items of Value Type fields can be selected.
 For the supported data types, see Signal Rule Supported Data Types.
If the selected App has Extension Apps, the entities from the Extension App will also be displayed and
can be selected.
11. To configure how the results are displayed, click on the Order by tab, and select the properties you want to
order by, specifying ascending or descending order.
12. Click on the Filter tab, to filter by constant or by selecting a source property, adding as many clauses as
required.
13. Click on the Filter tab, select the field you want to filter by and the operator, and in the Value edit box either:
• click Field, to select a property from the Combine block. Only properties with compatible data types
will be displayed. Properties containing lists are not available because not managed.
• click Constant, to enter a fixed value, along with its data type.
and 59. For example, "100.13:59:01", "13:59:01".
14. When you have completed the query configuration click Apply, or Reset, to start over. Note that if the query
results have already been used in successive Signal Rule diagram blocks (Combine, Filter or Transform) a
warning message will be displayed, and confirmation is required before the reset operation will be executed.
15. Click Save.
16. To preview the results of the query, click View Result.

System Apps
Signals App
 To delete a Query block, simply select it and click Remove Filter Query.
Bear in mind that deleting a query block could invalidate other successively configured blocks. For
example, if the results of the query had already been used in the transform diagram block.
2.6.5.2.6 Configuring Actions for Signal Rules (Action Block)

Once you have created a Signal Rule, configured its source and optionally created a filter you must define which
action will be triggered by the Signal Rule.
 The data model of the Signal Rule action can change frequently. You can click Reload to ensure the data
you are viewing is aligned with the most recent version, and then save the information. The Reload
operation updates the complete data structure, including parameter types.
Prerequisites
• The Signal Rule source has been defined.
Procedure
3. In the Signal Rule Editor, select the Action Block.
4. Do either of the following:
• In the Action Type side panel select the System Action tile, if not already selected by default. Then, in
the Properties side panel, select both the App your required command belongs to and the specific
command that will be triggered by the signal rule from the drop-down lists. The command is displayed,
along with its structure of parameters. Clicking on complex parameters will display their internal
structure. Lists of Enumeration Types and lists of Parameter Types are displayed in gray color because
they are not supported.
• If you are configuring the Signal Rule in order to trigger an action provided by other Apps (for example,
from the BPFlow App or from the Label App), in the Action Type side panel select the related tile and
follow the procedures described in the documentation of the involved App.
5. Click Save.
 If the selected App has Extension Apps, the commands/composite commands from the Extension App will
also be displayed and can be selected.
For the supported data types, see Signal Rule Supported Data Types. List of Blob are not supported even if
optional.
What to do next
You must now wire the parameters of the Signal Rule.

System Apps
Signals App
2.6.5.2.7 Transforming the Parameters of Signal Rules (Transform Block)

The concept of transforming in the Signals App is to connect the parameters of the selected action with those of the
data structures retrieved from the previous blocks (Source/Combine and Filter Query diagram blocks).
A warning triangle is displayed next to the action parameters for which you must provide a binding.
The following tables illustrates when transformation is mandatory or not:
The action parameter is... Transformation is mandatory
... optional
... mandatory
... a mandatory complex type
... an optional complex type with optional

parameters
... an optional complex type with some mandatory If wires are not created for any of the parameters.
parameters
If wires are created for any of the parameters, wires
must be created for the mandatory parameters.
Prerequisites
• The Source and Action diagram blocks have been defined for the Signal Rule.
• The data types of the wired properties are compatible:
Action Parameter Type Compatible Source Property Types
Byte Byte
Int16 • Int16
• Byte
Int32 • Int32
• Int16
• Byte
Int64 • Int64
• Int32
• Int16
• Byte
Decimal Decimal
DateTimeOffset DateTimeOffset
TimeSpan TimeSpan

System Apps
Signals App
Action Parameter Type Compatible Source Property Types
String String
Boolean Boolean
Guid Guid
Enum Enum of the same data type
Blob Blob
Procedure
3. In the Signal Rule Editor, select the Transform Block.
4. Click the browse button next to the Expression edit box in the Properties pane.
5. In the Transform Editor the parameters belonging to the command defined in the action block are displayed.
Wiring is allowed only between lists containing the same type of parameters. Lists of Enumeration Types and
lists of Parameter Types are displayed in gray color because they are not supported.
 If you have previously created and run a new Work Process by selecting the Start New Work
Process tile in the Action Type side panel, the system displays in the grid:
• All parameters of the selected Process Definition and of the related Process Template. When
you will save the configuration, the Process Definition parameters will be wired in the
Transform Block configuration, as well as Work Process NId, Work Process name and Work
Process Description.
• If you have selected the related Process Definition Context, the User Fields related to the
selected Context, with the naming convention: ProcessContextDefinition name/UserField
name.
6. For each parameter you can either:

• Click Constant, to manually enter a specific value in the Value edit box. Note that if your data type is
a blob or a List you can select fields but you cannot enter constants.
• Click Field, to select a specific source artifact property from the data stream in the Value drop down
list.
and 59. For example, "100.13:59:01", "13:59:01".
7. Click Save.

System Apps
Signals App
 If you want to transform parameters from the Task App in order to create a task with an Autogenerated Id,
insert NId as a constant in the value edit box for the NId parameter for the CreateTask action, preceded
by a special unicode character 0091, which can be copied from the unicode web site using Chrome or
Firefox web browsers. If you cannot use these browsers, this special character can also be created in
Microsoft Word as follows:
1. Enter the number 0091.
2. Selecting this number, type the key combination ALT + X.
3. Copy and paste the resulting character back into your web browser, immediately before the NId
constant.
What to do next
You can now approve your Signal Rule.
2.6.5.2.8 Checking the Consistency of Signal Rules

Checks are performed on the general configuration of Signal Rules to ensure that there are no inconsistencies.
Consistency checks are performed automatically every time a signal rule is saved or approved, but can be invoked
manually using the Check Rule Consistency button.
The following modifications are examples of changes that could introduce inconsistencies:
• properties are removed
• the property in a combine block is renamed
• a query block is removed.
For example, in this case a property, which was used in the Combine Block, has been removed from the source
filter, consequently creating an inconsistency in the Signal Rule:
Prerequisites
The user performing this operation belongs to the SignalRulesAdmin or SignalRulesEngineer role.
Procedure
2. In the Signal Rule Management page, select the signal rule you want to configure and click .
3. In the Signal Rule Editor click Check Rule Consistency. A list is displayed at the top of the screen with the
blocks that may contain errors and a description of the error.
4. Click the icon on the row corresponding to the inconsistency you want to check to reopen the Signal Rule in
the correct position to sort out the error.
2.6.5.3 Executing Signal Rules

Signal Rules must be deployed to enable their runtime execution and can be manually re-executed, if needed.

System Apps
Signals App
This is possible when a Signal Rule has been approved, and its consistency has been checked.
• Approving Signal Rules
• Deploying Signal Rules
• Modifying Deployed Signal Rules
• Disabling Deployed Signal Rules
• Deleting Deployed Signal Rules
• Viewing Signal Rule Execution History
• Re-Executing Deployed Signal Rules
• Logging and Tracing Signal Rule Processing Operations
2.6.5.3.1 Approving Signal Rules

Once a signal rule has been configured it must be approved before deployment.
Approved rules can be:
• edited, but if their configuration is modified (i.e. not just name or description) they must be approved again.
• deleted.
Prerequistes
• The source and action blocks of the signal rule have been correctly configured (the filter diagram block is
optional, and wiring is mandatory only if the command selected in the Action diagram block contains
mandatory parameters). If an error should occur for any of the signal rules in the list, a warning icon will be
displayed next to the rule in question, indicating that the signal rule must be reviewed in order to be able to
approve it. The last error to have occurred can be checked by opening the Details pane of the signal rule.
• The user performing this operation belongs to the SignalRulesAdmin role.
Procedure
2. In the Signal Rule Management page, select the rule you want to approve.
 To help find the required signal rule, click the filter symbol and filter the list by Id, Configuration
Status or Runtime Status, or by hiding approved and/or deleted rules form the list.
3. Click Approve. Consistency checks are automatically performed on the signal rule before its status is
changed to Approved.
 Rules can also be approved directly from within the Signal Rule Editor, which is opened by selecting the
rule in the Signal Rule Management page, and clicking .

System Apps
Signals App
2.6.5.3.2 Deploying Signal Rules

When a signal rule is deployed in the Signals App, the command it triggers can effectively be launched. As it is the
worker who launches the command, and not a specific user, no access right checks are performed. It is therefore
essential that the user who deploys signal rules belongs to an appropriate high-level user group and is aware of the
implications of his action. See the topic Predefined User Roles for Signal Rules for further information on how to
configure a secure workflow.
Deployed rules can be modified and deleted, making sure that their configuration and runtime statuses are kept
aligned.
If any problems occur during the deploy operation, and the runtime status of the signal rule is error, a flag is
displayed and the results of the deploy operation can be checked in the signal rule log and trace files.
Prerequisites
• The signal rule has been approved.
• The engineering host must be running for signal rules to be deployed. If you promote another engineering host
in your environment (as described in Promoting a Runtime Host to Engineering Host in an Already Configured
Environment of the Opcenter Execution Foundation Installation Guide), or if you manually move the signal files to
another host, you must then redeploy the signals.
• The Automation Gateway Server must be up and running before deploying Signal Rules that use Automation
Node Instances as source entities.
Procedure
2. In the Signal Rules Management page, select the approved rules you want to deploy.
 To help find the required signal rule, click the filter symbol and filter the list by Id, Configuration
Status or Runtime Status, or by hiding approved and/or deleted rules form the list.
3. Click . The signal rule will now be flagged as deployed, and its runtime status will be Running.
 Rule execution
To avoid the same signal triggering more than one action on different hosts, Signal rules are all run on a
single active host, which can be either a runtime host or the engineering host. When a host is active, the
other environment hosts are in stand-by, ready to take over the rule execution if the active host fails.
2.6.5.3.3 Modifying Deployed Signal Rules

You can modify deployed signal rules, and disabled signal rules.
Once modified their configuration and runtime status must be aligned by approving and deploying them again.
Prerequisites
The user performing the operation belongs to the SignalRulesAdmin role in order to disable the signal rule.

System Apps
Signals App
 Once you have deployed Signal Rules, you must pay careful attention to any modifications made to your
solution in Solution Studio:
• if you modify the solution, by reloading or deleting Apps for example, or modifying Automation Node
Type Parameters in the Automation Gateway App, you must align these modifications in your Signal
Rule configuration, as artifacts used as a source or target may no longer be present.
• if you want to change the data source in Solution Studio, you must first export the Signal Rules, then
delete them from the signal rule editor. Once the data source has been changed you must re-import
the Signal Rules and re-align them with the runtime status, by approving and deploying again.
Procedure
2. In the Signal Rule Management page, select the signal rule whose name or description you want to modify.
3. Then either:
• Click to modify the name and/or description of the signal rule. If an empty value is inserted, this will
effectively clear the value, or
• Click to modify the configuration of the signal rule, such as its filter.
4. Click Save. If you have changed the signal rule configuration, a warning icon is displayed, indicating that
the configuration and runtime statuses are not aligned.
5. Approve the signal rule.
6. Deploy the signal rule.
 If you change the source artifact the filter will be reset and must be reconfigured for the new artifact.
2.6.5.3.4 Disabling Deployed Signal Rules

The runtime execution of Signal rules can be disabled in order to stop their execution temporarily.
Disabled signal rules will still be displayed in the list of signal rules, but they will no longer be running.
The following operations are then possible:
Operation Consequences
modify If you change the configuration of the signal rule, it must then be
approved and deployed again in order to put it back in execution.
deleted No further operations are required, and the signal rule is removed from
the list.
enabled You can decide to put the signal rule back in running status, if you have
not modified its configuration, by clicking .
Prerequisites
The user performing the operation belongs to the SignalRulesAdmin role in order to disable the signal rule.

System Apps
Signals App
Procedure
2. In the Signal Rule Management page, select the signal rule whose runtime execution you want to stop.
3. Click .
2.6.5.3.5 Deleting Deployed Signal Rules

All signal rules can be deleted, regardless of their status, but their configuration and runtime statuses may need to
be aligned:
Signal rule status Behavior
New, not deployed The signal rule is deleted immediately and is removed from the list.
Deployed The signal rule must be approved and deleted in order to complete its
deletion, as the configuration and runtime statuses must be aligned.
Disabled The signal rule is deleted immediately and is removed from the list.
Prerequisites
The user performing the operation belongs to the SignalRulesAdmin role.
Procedure
2. In the Signal Rule Management page, select the signal rule you want to modify or delete.
3. Click Delete.
4. (Deployed rules only) Approve and deploy the signal rule.
2.6.5.3.6 Viewing Signal Rule Execution History

When creating, modifying or copying a Signal Rule, you can decide to store or not information on the execution of
the Signal Rules, as well as to store this information only if the Signal Rule execution fails.
The information is displayed in a dedicated page that lists the Signal Rules already executed and shows useful
details on the Signal Rule execution. For the execution details, see Execution Display Fields.
The refresh operation is also available to ensure the displayed data is aligned with the most recent version.

System Apps
Signals App
 Note on Signal Rule Execution History Database Table

The physical table of the SignalRuleExecutionHistory entity and all related tables are generated in the
database on a dedicated Filegroup (SQL Server) or Tablespace (Oracle), different from the main one. If
several disks are available on your scenario, we suggest that you move the associated datafile to a
separate disk, in order to better manage space and accesses.
For information about the maintenance of Signal Rule Execution History database table, see Using
Maintenance Stored Procedure in the Opcenter Execution Foundation Development and Configuration Guide.
Prerequisites
• The execution history of the Signal Rule has been configured as Enabled or Enabled only in case of errors.
• The Signal Rule has been deployed and executed.
Accessing the Page

1. Do either of the following to open the Signal Rule Execution History page:
• Click the Signal Rule Execution History home tile.
• Click Signal Rule Execution History in the side menu bar and click Signal Rule Execution History.
Execution Display Fields

For each executed Signal Rule, the Signal Rule Execution History page displays the following information by
default:
Id The Id of the Signal Rule.
Start Time The time when the Signal Rule execution is started.
End Time The time when the Signal Rule execution is ended.
Source Type The source type you have set when configuring the Source Block.
Action Type The action type you have set when configuring the Action Block.
Execution Status The status of the Signal Rule execution. Possible values:
• the execution of the Signal Rule is successful

• the execution of the Signal Rule is not completed due to
configuration reasons. For example, the source input is discarded
according to Filter configuration or a Query configured as Is
Relevant does not retrieve any record.
• the execution of the Signal Rule is failed
Error Code The error code returned by the Action called by the Signal Rule. It is
filled only if the Action execution fails and the error is managed.

System Apps
Signals App
Execution Description Description of the Signal Rule execution.
Is Re-Execution Indicates whether the execution is a manual Signal Rule re-execution

or not.
Last Updated On The last update of the Signal Rule execution, corresponding to the
End Time.
Refresh Signal Rule Execution History To refresh the execution history of the Signal Rule.
Re-Execute Signal Rule To re-execute a Signal Rule previously executed.
Overview Signal Rule Execution To view an overview of the Signal Rule execution. The
Overview Signal Rule Execution dialog box displays the Id of
the Signal Rule, the reason why the Signal Rule has been re-
executed and details on Source and Action Blocks.
2.6.5.3.7 Re-Executing Deployed Signal Rules

When creating, modifying or copying Signal Rules, if you decided to store information on the execution of the Signal
Rules, the Signal Rule Execution History page displays the list of the Signal Rules that are already executed at least
once (see Viewing Signal Rule Execution History). Here, you can manually re-execute any Signal Rule, according to
the required prerequisites.
The re-execution of the Signal Rules can be performed regardless of the result of the previous execution. Therefore,
you can re-execute Signal Rules both if their execution previously failed and if they have been partially executed, as
well as if they have been successfully executed.
Prerequisites
• The execution history of the Signal Rule has been configured as Enabled or Enabled only in case of errors.
• The Signal Rule has been executed at least once.
• The Signal Rule has not been deleted.
• The runtime status of the Signal Rule is not Stopped.
Procedure
1. Access the Signal Rules Execution History page.
2. Select the Signal Rule you want to re-execute.
 To help you find the required Signal Rule, click the filter symbol and filter the list by Id.

System Apps
Signals App
3. Click .
4. In the side panel, insert the reason why you want to re-execute the Signal Rule and save the operation. The
Signal Rule will be re-executed.
2.6.5.3.8 Logging and Tracing Signal Rule Processing Operations

Errors might occur while Signal Rules are deployed or processed at runtime.
To analyze these errors, Signal Manager generates logs and traces.
Logs
The following log system events are persisted in the Windows Event Viewer, under the Application and Services
Logs > Siemens > SimaticIT > System > Admin node (see Persisting System, Security and Application Messages on
Microsoft Event Viewer in the Opcenter Execution Foundation Development and Configuration Guide):
Severity Level Log Possible corrective actions
Informational The Signal Rule has been successfully No action is required.

started after it has been created/updated
and deployed.
[Signal Manager] The Rule "<Signal Rule
Name>" "<Rule revision number>" on Host
<Host Name> has been successfully started.
Informational The Signal Rule has been successfully No action is required.

stopped after it has been removed/
updated and deployed.
<Host Name> has been successfully
stopped.
Error The Signal Rule runtime processing The Signal Rule must be corrected and
returned a fatal error and the Signal Rule redeployed.
processing is now stopped.
<Host Name> has terminated with failure
due to this error: <error description> (Error
Code: <Internal Error Code>).

System Apps
System App
Severity Level Log Possible corrective actions
Warning The Signal Rule runtime processing No action is required.

returned an error, but the Signal Rule is
The Signal Rule is actually well configured
still running.
and it is correctly working, but one of its
[Signal Manager] The Rule "<Signal Rule blocks returned a temporary error as a
Name>" "<Rule revision number>" on Host consequence of the message that
<Host Name> has raised this error during processed the Signal Rule.
the processing of block "<Signal Rule
Diagram Block Type>": <error description>
(Error Code: <Internal Error Code>).
For details on the Signal Rule statuses, see Signal Rule Configuration and Runtime States.
Traces
Traces are displayed in Trace Viewer (see the Logging and Analyzing Application Traces with Trace Viewer section in
the Opcenter Execution Foundation Development and Configuration Guide).
2.7 System App

The System App must be present in the Manufacturing Solution because it manages base entities and
functionalities (such as the user preferences and the related commands).
Its presence in the Solution packages represents a prerequisite for building the Solution.
 System App update

According to the procedure you are following (adding, migrating or restoring) and to the version of the
backup you are restoring, do either of the following to ensure that the latest version of the System App will
be in use:
• If you are creating a new solution, the latest version of the System App will be installed.
• If you are migrating an existing one, the latest version of the System App will be installed.
• If you are restoring a backup created in a version that is earlier than 2.3, add the System App to your
solution before building it.
• If you are restoring a backup created in 2.3, select the System App and click the Update button before
building it.
The App references the SITUASys Functional Block. For detailed information on the artifacts contained in this
Functional Block, see the Reference Documentation of the Functional Block.
For a general understanding of Functional Blocks, see Overview of Functional Blocks in the Opcenter Execution

Manufacturing Apps
Barcode App
3 Manufacturing Apps
The Opcenter EX FN Manufacturing Apps are
• Barcode App
• Defect App (with QEMigration Extension App)
• Equipment App (with OPCUAConnect Extension App)
• Label App
• Material App
• Personnel App
• Reference App
3.1 Barcode App

The Barcode App allows you perform the following operations:
• managing Barcode Rules, which can be used to validate Barcode strings, and view the History of each Barcode
reading executed at runtime.
• reading and decoding barcodes through the angular service barcodereaderservice.js
• BRC_MS
• BRC_OP
What can I do in the Barcode App?

• What are Barcode Rules? provides useful conceptual information.
• How to Manage Barcode Rules and Rule Parts describes how to create and configure Barcode Rules and Rule
Parts and how to view the Barcode History.
3.1.1 What are Barcode Rules?

The Barcode App provides a dedicated environment to manage Barcode Rules, which make it possible to validate a
Barcode string against a specific rule.
Once created, Barcode Rules are empty containers which can be associated with Rule Parts, each of them
containing a regular expression which will be used to validate the Barcode string.
While configuring the Barcode Rule, you can define to which item the rule must be applied (for example to a Serial
Number), according to your needs.
In addition, it is possible to view the History of each Barcode reading to easily know which ones are valid, meaning
that they match the rule, or not.
3.1.2 What is the Barcode Service?

The Barcode App provides you with the angular service barcodereaderservice.js that has been designed to read
and decode barcodes.
Automatically reading barcodes can help in avoiding human mistakes, when inserting data.

Manufacturing Apps
Barcode App
The barcode parser is configured to decode MTU identifiers based on Serial Number field (21) as defined in GS1
codification, but it can be extended to decode other serial number fields, as described in How to Manage Barcode
Parser topic.
3.1.3 How to Manage Barcode Rules and Rule Parts

The Barcode App allows you to manage Barcode Rules and their Rule Parts. For this purpose, it provides a
dedicated environment where Barcode Rules can be created, updated and deleted, as well as their Rule Parts.
You can define the composition of your own Barcode Rule, which can be made up of one or more Rule Parts in any
combination you deem necessary.
The Barcode History page traces all the Barcode readings that have been executed at runtime, giving also
information on their validity.
Workflow
1. Create Barcode Rules.
2. Add Rule Parts.
3. View the Barcode History.
4. Exporting and Importing Barcode Rules Data.
Edit To update:
• Barcode Rules
• Rule Parts
Delete To delete:
• Barcode Rules
• Rule Parts
Move up To move the selected Rule Part up one position in the grid (in the string
generated this corresponds to the Rule Part moving one position to the left).
Move down To move the selected Rule Part down one position in the grid (in the string
generated this corresponds to the Rule Part moving one position to the
right).
To export selected entities and instances in an export package that can be

Export
downloaded locally and imported afterwards. See How to Export and Import
Data
Audit Trail of a Barcode Rule
To display the Audit Trail of a Barcode Rule, select the Rule and then navigate to the Audit Trail tab.

Manufacturing Apps
Barcode App
The Audit Trail tab shows the list of all changes performed on the selected Barcode Rule.
3.1.3.1 Creating Barcode Rules

Once created, Barcode Rules are empty containers to which one or more Rule Parts can be added according to your
needs.
Procedure
1. To open the Barcode Rules page, click the Barcode Rules home tile.
2. In the Barcode Rules page, click .
3. Set the required attributes:
Identifier The identifier assigned to the Barcode Rule. Once the Rule is created,
the Identifier value cannot be modified.
Name The name assigned to the Barcode Rule.
Description (Optional) Additional information on the Barcode Rule.

4. Click Save.
3.1.3.2 Adding Rule Parts

After creating a Barcode Rule, you can add one or more Rule Parts which will make up the final Rule. Each Rule Part
is defined by a regular expression which will be used to validate the received Barcode string at runtime.
Procedure
1. In the Barcode Rules page, select a Barcode Rule and click .
2. Click the Rule Parts tab.
3. Click and set the required attributes:
Identifier The identifier assigned to the Rule Part. Once the Rule Part is created, the
Identifier value cannot be modified.
Name The name assigned to the Rule Part.
Description (Optional) Additional information on the Rule Part.

Manufacturing Apps
Barcode App
Item Type (Optional) Represents the item to be considered while defining the
Barcode Rule. An example of Item Type could be: Serial Number.
 • The product does not offer predefined item types. If

you want to use item types, you must configure the
DBInit in the same Functional Block containing the
Barcode Rule.
• It is not possible to set the same Item Type twice in
the same Barcode rule.
• If you do not select the Item Type, the Rule Part will
contribute in validating the Barcode, but its content
will not be returned in the generated string.
Prefix (Optional) Represents the prefix to be included in the regular expression.

For example: SN for Serial Number.
Expression Represents the regular expression which will be used to validate the
received Barcode string.
For example:
\d{3} means that the matching Barcode must contain three numbers.
 The following characters are currently not supported:

• \r
• \n
• \t
The expression will be generated with boundaries (\b) at the beginning

and at the end.
Suffix (Optional) Represents the suffix to be included in the regular expression.

For example: NS for Serial Number.
4. Click Save.
Example
Here below an example of the same Barcode matching or not matching the regular expression defined in the Rule:
Barcode Regular Expression Result
SN123NSPN1234NP \bSN\d{3}NSPN\d{4}NP\b True
SN123NSPN1234NP \bSN\d{6}NSPN\d{10}NP\b False
Result
In the Overview tab of the Barcode Rules page, if you add more than one Rule Parts to your Barcode Rule, it is
possible to view the sum of all the regular expressions in the Expression field.

Manufacturing Apps
Barcode App
3.1.3.3 Viewing Barcode History

The system tracks the outcome of each Barcode reading executed at runtime, indicating also if the Barcode string is
valid which means that it matches the Barcode rule.
Procedure
1. To open the Barcode History page, click the Barcode History home tile.
2. The system displays the following details:
Barcode The identifier of the Barcode.
Validated On Timestamp indicating when the Barcode string has been

validated.
Rule Identifier The identifier of the Rule used to validate the Barcode.
Expression The regular expression used to validate the Barcode string.
Is Valid Flag indicating if the Barcode is valid or not, which means if it

matches the Rule (value true) or not.
User The user who performs the operation.
Created On Timestamp of the History log creation.
Last Updated On Timestamp of the History log last update.
3.1.3.4 Exporting and Importing Barcode Rules Data

The Barcode App allows you to export and import its own master data entities. Unlike the Export operation, the
Import procedure depends on the exported entities and has to be performed carefully as described in the following
section.
Import sequence of the export package

The table below indicates in which order you should import the exported packages, according to the app data
model: the first column lists the entities to be imported and the rows indicate the import sequence.
 Barcode Rules are parent entities and their Rule Parts are automatically exported.
Barcode Rule Barcode Notes

Rule Part
Barcode Rule & Barcode Rule Barcode Rules will be exported

Part together with their Rule Parts both if
the Include Descendants is set to
True or to False, because these two
entities are in composition.

Manufacturing Apps
Barcode App
3.1.4 How to Manage Barcode Parser

The Barcode App provides you with the angular service barcodereaderservice.js that has been designed to read
and decode barcodes.
You can include the barcode scanner service into a custom app, and you can change the configuration in order to
make the parser decode barcodes based on other Serial Numbers, to satisfy your application needs.
Target user
System Integrator, Developer
Prerequisites
• Be familiar with Opcenter Execution Foundation developer environment Opcenter EX FN Development and
• Be familiar with Javascript coding.
What can I do
In this chapter you are going to learn:
• How to include the Barcode Scanner in a User Interface
• Configuring the Barcode Parser
3.1.4.1 How to Include the Barcode Parser in a User Interface

You can include the barcode parser service, provided by Barcode App, in a User Interface through a custom app.
The parser is configured to decode MTU identifiers based on Serial Number field (21) as defined in GS1 codification,
but it can be extended to satisfy your application needs, as described below.
The parser has been designed to work with barcode scanners that act as input device (like a keyboard). It is an
AngularJS service, currently located in the Barcode App, which needs to be injected in the controller where it is
intended to be used.
After having injected the service, it is necessary to
• call the waitForBarcode method to intercept the barcode,
• define the logic used to manage the parsed barcode as in the below codeblock:
Managing the parsed barcode
barcodeReaderService.waitForBarcode(function (barcode) {
var parsed = barcodeReaderService.parseBarcode(barcode);
//logic goes here
});
The barcode parser can be included in a User Interface through:

• an Angular constant containing the parameters required by the parser
• an API setting all the parameters required by the parser

Manufacturing Apps
Barcode App
Including the Barcode Parser

1. In Opcenter Execution Foundation Project Studio, create a custom App.
2. Create a UI Component, following the instructions provided by Creating a UI Component chapter in Opcenter
3. Enrich the UI component code by adding the instructions to inject the barcodereaderservice.js.
Code for injecting barcodereaderservice.js
ComponentController.$inject = ['common.base',
'Siemens.OpcenterEX.PR.Barcode.BarcodeReader.service' ,'<App name>.constant'];

• Define the angular constant <App name>.constant (in this this example, named barcodeParserConfig)
and declare the instance of the injected service in the UI component constructor
Code in UI Component Controller
function ComponentController(base,barcodeService,barcodeParserConfig) {
barcodeService.injectConfig(barcodeParserConfig)
...
}
• Configure the Barcode Parser through APIs.

5. Create a Mashup UI Module that includes the UI Component you have just created, according to your needs.
6. Include the created UI Mashup Module in a UI Application.
Including the Barcode Parser through APIs

The barcodeReaderService service exposes the following methods, that allows you to configure the barcode parser
step by step.
You can call the methods in the following order:
Step Method call Parameter description
1. injectKeys(listOfKeys); listofKeys corresponds to the keys listed in an

angular constant
2. injectEntityCodes(listOfEntityCodes); listOfEntityCodes corresponds to the

entityCodes listed in an angular constant
3. setStartCharacter(startChar); startChar is the character starting the barcode

string
4. setEndCharacter(endChar); endChar is the character ending the barcode

string
5. setSeparatorTag(separatorTag); separatorTag is the character that separates the

data fields contained in the barcode.

Manufacturing Apps
Barcode App
The parameters of these methods must be strings or objects as presented in the structure of the angular constant.
The inject methods add parameters to the existing configuration, while set methods update configured values.
Furthermore, the service provides you with method injectConfig(angularConstant) to inject the complete
structure of the Angular constant.
Example
barcodeservice.clearConfiguration(); // clear if want to substitute
var listofkeys={ keys: [

{ key: '216', entityLength: 6 },
{ key: '218', entityLength: 8 },
{ key: '212', entityLength: 2 }
]
} ;
var listofentitycodes = { entityCodes: [

{ code: 21, entity: 'MTU', uom: '',propertyV
alueName :'MTUNID' },
{ code: 10, entity: 'LOT', uom: 'number' ,pr
opertyValueName :'LOTID'},
{ code: 123456, entity: 'Drum', uom:
'number' ,propertyValueName :'DRUM_ID'},
{ code: 12345678, entity: 'Tank', uom:
'number' ,propertyValueName :'TANK_ID'}
]
};
barcodeservice.injectKeys(listofkeys.keys);
barcodeservice.injectEntityCodes(listofentitycodes.entityCodes);
barcodeservice.setStartCharacter( '+' );
barcodeservice.setEndCharacter ( 'CK');
barcodeservice.setSeparatorTag( '|');
Deleting the barcode parser configuration

If you want to clear the configuration of the barcode parser, you can call method clearConfiguration().
Reference Documentation
See Opcenter Execution Foundation Development and Configuration Guide for further information on the creation of
Mashup UI Modules and UI Applications.
3.1.4.1.1 Defining the Angular Constant

The structure of the Angular constant must be as in the example below.

Manufacturing Apps
Barcode App
 Set the angular.module with the name of the App you are using. In the example, it is the name suggested
for the creation of the App
angular.module('Siemens.Custom.UIContainer')
Example of Angular Constant structure
(function () {
'use strict';
angular.module('Siemens.Custom.UIContainer')
.constant('Siemens.Custom.UIContainer.CustomBarcodeParserConfig.constant',
CustomBarcodeParserDefaultConfig());
function CustomBarcodeParserDefaultConfig() {
return {
data: {
startCharacter: '+',
separatorTag: '|',
endIndicator: 'CK',
keys: [{
key: '212',
entityLength: 2
}],
entityCodes: [{
code: 21,
entity: 'CustomMTU',
uom: '',
propertyValueName: 'CustomMTUNID'
},
{
code: 11,
entity: 'CustomLOT',
uom: '',
propertyValueName: 'CustomLOTID'
}]
}
};
}
}());
After having called the waitForBarcode method , the parser intercepts every key pressed.
The parser's configuration consists of the following data:

Manufacturing Apps
Barcode App
Parameters Description
startCharacter, endIndicator If the start character is encountered, the service records the
subsequent characters, until it encounters the end indicator.
separatorTag It separates the multiple data fields a barcode can contain.
keys The keys, at the beginning of the barcode, indicate the length of
the subsequent entity code. For example, 214 identifies a 4-char
entity code.
entityCodes Entity codes specify the name of the entity from the given
barcode, and its unit of measure. The entity name becomes the
object name in JSON output.
3.1.4.2 Configuring the Barcode Parser

The Barcode Parser the Barcode App provides is configured to decode MTU identifiers based on Serial Number field
(21) as defined in GS1 codification.
You can change the configuration in order to make the parser decode barcodes based on other Serial Numbers, to
satisfy your application needs.
You can configure the following parameters:
Parameter Description Default Value
startCharacter Identifies the start character of the barcode +

string.
separatorTag Identifies the character that separates the data |

fields contained in the barcode.
endIndicator Identifies the end character of the barcode string. CK
keys Identifies the list of supported keys, in terms of 212

key and entityLength.
entityCodes Identifies the list supported entity codes, in terms 21

of code, entity, uom and propertyValueName.
The default parser configuration is contained in %ProgramData%
\Siemens\SimaticIT\Unified\Deploy\UI\apps\<SolutionName.UIApplicationName>\Siemens.OpcenterEX.PR.B
arcode\services
\barcodeParserConfigService.js file.
The default parser configuration is as below:

Manufacturing Apps
Barcode App
data: {
startCharacter: '+',
separatorTag: '|',
endIndicator: 'CK',
keys: [{
key: '212',
entityLength: 2
}],
entityCodes: [{
code: 21,
entity: 'MTU',
uom: '',
propertyValueName: 'MTUNID'
}]
}
In case the scanned barcode cannot be parsed, the system returns it in NOPATTERNMATCHING vector.
If the scanned barcode starts with a wrong character the barcode will be not acquired.
You can create a custom App in order to define the rules used by barcode parser while decoding. The new
configuration overwrites the default configuration.
Procedure
1. In Project Studio:
• Create a new App ( if you are going to make more customizations) or extend the base app (if you want to
use the model and commands provided by the base app). Name it UIContainer and set the Prefix to
Siemens.Custom.
• In the UserInterface project, create a UI Component.
• Follow the wizard and set what you need.
• In Services folder, add a javascript file, that contains the definition of an angular constant. The angular
constant must be named Siemens.Custom.UIContainer.CustomBarcodeParserConfig.constant.
2. In Solution Studio:
• Create a UI Mashup Module.
• Include the UI Component, you have previously created in your custom App, in the UI Mashup Module.
• Generate the UI Mashup Module.
• Associate the UI Mashup Module you have just created with the UI Application you are configuring.
• Build and deploy the Solution.
Result
The Barcode App checks if a custom angular constant definition exists and loads it instead of the default.
Examples of parsing
Here some examples of barcode parsing using the default configuration
Barcode Resulting parsing
+21221MTU_00001CK {"MTU":[{"MTUNID":"MTU_00001","UoM":""}]}

Manufacturing Apps
Defect App
+21221MTU_00001|21221MTU_00002CK {"MTU":[{"MTUNID":"MTU_00001","UoM":""},
{"MTUNID":"MTU_00002","UoM":""}]}
+21221MTU_00001| WrongMTU | {"MTU":[{"MTUNID":"MTU_00001","UoM":""},

21221MTU_00002CK {"MTUNID":"MTU_00002","UoM":""}],"NOPATTERNMATCHI
NG":[" WrongMTU "]}
+WrongMTU|21221MTU_00001| {"NOPATTERNMATCHING":["WrongMTU"],"MTU":
21221MTU_00002CK [{"MTUNID":"MTU_00001","UoM":""},
{"MTUNID":"MTU_00002","UoM":""}]}
Here some examples of barcode parsing using the custom configuration, provided as example
+21221MTU_00001|21210LOT_00001CK {"MTU":[{"MTUNID":"MTU_00001","UoM":""}],"LOT":
[{"LOTID":"LOT_00001","UoM":"number"}]}
+21210LOT_00001|21221MTU_00002| {"LOT":[{"LOTID":"LOT_00001","UoM":"number"},
21210LOT_00001CK {"LOTID":"LOT_00001","UoM":"number"}],"MTU":
[{"MTUNID":"MTU_00002","UoM":""}]}
3.2 Defect App

The Defect App allows you to manage both failures which can occur during the life cycle of a product or process
and quality actions required to resolve the detected failures.
• UDM_RF
• DEF_MS
What can I do in the Defect App?

• What are Failures and Quality Actions? provide useful conceptual information.
• How to Migrate existing Failures to the Defect App describes the procedure to migrate existing Failures, created
in the platform version 3.0, from the Work Instruction App to the Defect App.
• How to Manage Failures and Quality Actions describes how to create and configure Failures and Quality Actions.
3.2.1 What are Failures and Quality Actions?

The Defect App provides a dedicated environment to manage potential problems (Failures), which can occur
during the life cycle of a product or process, and all operations required to resolve them (Quality Actions).

Manufacturing Apps
Defect App
Detected Failures can be assigned to Quality Characteristics (Attributive, Variable and Visual) and organized in
more specific Sub-Failures, as well as Quality Actions can be organized in Quality Sub-Actions, representing more
specific actions to be performed.
In addition, Failures can be associated with Attachments, representing instructions that help you to better identify
the detected Failures. Attachments can be text files, videos and images.
3.2.2 How to Migrate existing Failures to the Defect App

In version 3.0 of Opcenter Execution Foundation, Failures were created in the Work Instruction App and then
associated with Visual Characteristics.
Starting from version 3.1, you can create Failures only in the Defect App, whereas the association with
Characteristics is managed in the Work Instruction App.
For existing Failures, created in the previous platform version, the application supports migration of both Failures
and their association with Visual Characteristics from the Work Instruction App to the Defect App.
After migration, you can manage all Failures in the Failure page of the Defect App and their association with
Characteristics in the Work Instruction App.
To perform the migration, you need to add an Extension App as a customized extension of the Defect App to your
Solution. For this purpose, the dedicated Extension App QEMigration is provided.
The QEMigration App references the following Functional Blocks::
• QEMigration_MS
• DEF_MS
• CHR_MS
• UDM_RF
the Functional Blocks.
Workflow
1. Add the QEMigration App to your Solution.
2. Reconfigure your UI Application, as described in Configuring UI Applications in the Opcenter Execution
3. Redeploying your Solution, as described in How to Deploy a Manufacturing Solution in the Opcenter Execution
4. Migrate the existing Failures.
Adding the QEMigration App to your Solution

1. Access the App Management page in Solution Studio.
2. In the Installed tab, click on the Defect App.
3. In the Extensions tab, click . The system displays the QEMigration tile.
4. Click in the tile of the QEMigration Extension App to add it to your solution.

Manufacturing Apps
Defect App
 Once installed, you can select the Extension App and view the following information:
• In the Dependencies tab, the Functional Blocks referenced by the Extension App.
• In the Where Used tab, in which UI Components and Modules the Extension App is used.
For more information, see How to Manage Apps and Extension Apps in the Opcenter Execution
Migrating the existing Failures

1. Do either of the following to open the Failure Migration page. The existing Failures to be migrated are
displayed in grid.
• Click the Failure Migration home tile.
• Click Failure Migration in the sidebar and then click Failure Migration.
2. Click Migrate and confirm the operation. Failures will be migrated to the Defect App and displayed in the
Failure page.
 • Existing Failures having the same ID and Revision pair of new Failures, created in the Defect App, will
not be migrated.
• Once migrated:
• All existing Failures will be removed from the Work Instruction App.
• The QEMigration Extension App will not be required anymore and it can be removed from your
Solution.
3.2.3 How to Manage Failures and Quality Actions

 Before creating new Failures, we suggest that you migrate the existing ones previously created in the Work
Instruction App (if any). This because existing Failures having the same ID of new Failures, created in the
Defect App, are not migrated.
The Defect App allows you to manage both Failures which can occur during the life cycle of a product or process
and Quality Actions required to resolve the detected failures. For this purpose, it provides a dedicated
environment where Failures and Quality Actions can be created, updated and deleted.
Detected Failures can be assigned to Quality Characteristics (Attributive, Variable and Visual) and organized in
more specific Sub-Failures, as well as Quality Actions can be organized in Quality Sub-Actions, representing more
specific actions to be performed.
the detected Failures. Attachments can be text files, videos and images.
Audit Trail is displayed in the each page to provide evidence of all the operations that have been carried out on a
specific Failure/Quality Action. Its records can be viewed by selecting the Failure/Quality Action and clicking
on Audit Trail tab.
Workflow
1. Create Failures.
2. (Optional) Create Sub-Failures.
3. Create Quality Actions.
4. (Optional) Create Quality Sub-Actions.
5. Create Attachments.

Manufacturing Apps
Defect App
6. Assign Failures and Sub-Failures to Quality Actions.

7. Assign Attachments to Failures.
To update:
Edit
• Failures
• Sub-Failures
• Quality Actions
• Quality Sub-Actions.
• Attachments (only from the Failure Attachment Management
page).
To delete:
Delete
• Failures.
• Sub-Failures
• Quality Actions
• Quality Sub-Actions.
• Attachments (only from the Failure Attachment Management
page).
 Failures organized in Sub-Failures cannot be deleted

before removing the related Sub-Failures.
/ Set/Unset as Current To set/unset the Failure/Sub-Failure as current. When the Set as

Current operation is applied to a Failure/Sub-Failure, the material
is flagged as IsCurrent.
/ Lock/Unlock To configure a Failure/Sub-Failure as read-only, so that it cannot be

edited or deleted. When the locking operation is applied to a
Failure/Sub-Failure, the material is flagged as IsLocked.
You can remove the read-only setting by applying the Unlock
operation.
Create New Revision To create a new revision of the selected Failure/Sub-Failure. The
new revision will have the same settings of the selected Failure/
Sub-Failure, but a new revision value.
To remove the association between:

Disassociate
• Failures/Sub-Failures and Quality Actions.
• Failures/Sub-Failures and Attachments.
To export selected entities and instances in an export package that

Export
can be downloaded locally and imported afterwards. See How to
Export and Import Data

Manufacturing Apps
Defect App
3.2.3.1 Creating Failures

Failures represent potential problems which can occur during the life cycle of a product or process. They can be
assigned to Quality Characteristics (Attributive, Variable and Visual).
Procedure
1. Do either of the following to open the Failures page:
• Click the Failures home tile.
• Click Defect in the side menu bar and click Failures.
2. In the Failures page, click .
Id The identifier assigned to the Failure. Once the Failure is created, the Id value cannot
be modified.
The Id value cannot contain the following special characters: & (ampersand), ' (quote),
# (hashtag), " (double quotes), + (plus), : (colon).
Revision The revision associated to the Failure.

Once the Failure is created, the Revision value cannot be modified.
Name (Optional) The name assigned to the Failure.
Description (Optional) Additional information on the Failure.

4. Click Save.
3.2.3.2 Creating Sub-Failures

Failures can be organized in Sub-Failures. For each Failure you can create more Sub-Failures, whereas for each Sub-
Failure only one parent Failure can be defined.
Procedure
2. In the Failures page, select a Failure and click .
3. Click the Sub-Failures tab.
4. Click and set the required attributes:

Manufacturing Apps
Defect App
Id The identifier assigned to the Sub-Failure. Once the Sub-Failure is

created, the Id value cannot be modified.
The Id value cannot contain the following special characters: &
(ampersand), ' (quote), # (hashtag), " (double quotes), + (plus).
Revision The revision associated to the Sub-Failure.

Once the Sub-Failure is created, the Revision value cannot be modified.
Name (Optional) The name assigned to the Sub-Failure.
Description (Optional) Additional information on the Sub-Failure.

5. Click Save.
3.2.3.3 Creating Quality Actions

Quality Actions are operations that you need to perform in order to resolve the detected Failures.
Procedure
1. Do either of the following to open the Quality Actions page:
• Click the Quality Actions home tile.
• Click Defect in the side menu bar and click Quality Actions.
2. In the Quality Actions page, click .
Id The identifier assigned to the Quality Action.

Once the Quality Action is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Quality Action.
Description (Optional) Additional information on the Quality Action.
Type (Optional) If set to General, the Quality Action can be organized in Quality Sub-Actions.
4. Click Save.
3.2.3.4 Creating Quality Sub-Actions

General Quality Actions can be organized in Quality Sub-Actions. They represent more specific actions that you
need to perform in order to resolve detected Failures.
For each Quality Action you can create more Quality Sub-Actions, whereas for each Quality Sub-Action only one
parent Quality Action can be defined.

Manufacturing Apps
Defect App
Procedure
1. Do either of the following to open the Quality Actions page:
• Click the Quality Actions home tile.
• Click Defect in the side menu bar and click Quality Actions.
2. In the Quality Actions page, select a Quality Action and click .
3. Click the Quality Sub-Actions tab.
4. Click .
Id The identifier assigned to the Quality Sub-Action.

Once the Quality Sub-Action is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Quality Sub-Action.
Description (Optional) Additional information on the Quality Sub-Action.

6. Click Save.
3.2.3.5 Creating Attachments

Attachments represent instructions (text files, videos and images) which can be created and assigned to Failures in
order to identify Failures better.
Procedure
1. Do one of the following:
• Click the Failure Attachments home tile.
• Click Defect in the side menu bar and click Failure Attachments.
• Open the Failures page (see Creating Failures), select a Failure, click and then click the
Attachments tab.
2. Click .
Id The identifier assigned to the Attachment.

Once the Attachment is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Attachment.
Description (Optional) Additional information on the Attachment.
File The document to be attached. You can browse text files, videos and images.
Icon The icon that will be assigned to the attachment.

Manufacturing Apps
Defect App
4. Click Save.
3.2.3.6 Assigning Failures and Sub-Failures to Quality Actions

After creating Failures, Sub-Failures and Quality Actions, you can assign a list of Failures/Sub-Failures to Quality
Actions: one Failure/Sub-Failure can be associated with more Quality Actions, likewise one Quality Action can be
associated with more Failures/Sub-Failures as well.
Procedure
2. In the Failures page, select a Failure/Sub-Failure and click .
3. Click the Quality Actions tab.
4. Click .
5. Set the required attribute:
Quality Action The identifier assigned to the Quality Action.

6. Click Save.
3.2.3.7 Assigning Attachments to Failures

After creating Failures and Attachments, you can assign Attachments to Failures and Sub-Failures. One Failure (or
Sub-Failure) can be associated with more Attachments, likewise one Attachment can be associated with
more Failures (or Sub-Failures) as well.
Procedure
• In the Failure Attachments page (see Creating Attachments), select an Attachment, click and in the
Failures tab select a Failure or a Sub-Failure.
• In the Failures page (see Creating Failures), select a Failure or a Sub-Failure, click and then click the
Attachments tab.
2. Click .
3. Set the required attribute:
Attachment The identifier assigned to the Attachment.

4. Click Save.
3.2.3.8 Exporting and Importing Defect Data

The Defect App allows you to export and import its own master data entities. Unlike the Export operation, the
section.

Manufacturing Apps
Defect App

Example: If you want to import Quality Action, Failure/Sub-Failure and Failure Attachment entities and Quality
Action and Failure/Sub-Failure entities were exported selecting Include Descendants = False, you must import the
packages in this order:
1. Quality Action
2. Failure/Sub-Failure
3. Failure Attachment
 Note that Quality Actions are parent entities and their Quality Sub-Actions are automatically exported.
Instead, Sub-Failures are not automatically exported with Failures and they must be exported as well.
Quality Failures/ Failure Notes

Actions Sub- Attachments
Failures
Quality If Quality Actions and Failures/Sub-Failures are

Actions & exported by setting Include Descendants to
Failures/Sub- False
Failures &
Failure
Attachments

Failures/Sub- True
Failures &
Failure
Attachments

False
Failures/Sub-
Failures
Quality If Quality Actions are exported by

Actions & setting Include Descendants to True
Failures/Sub-
Failures
Failures/Sub- If Failures/Sub-Failures are exported by

Failures & setting Include Descendants to False
Failure
Attachments

Manufacturing Apps
Equipment App
Quality Failures/ Failure Notes

Actions Sub- Attachments
Failures
Failures/Sub- If Failures/Sub-Failures are exported by

Failures & setting Include Descendants to True
Failure
Attachments
Quality
Actions
3.3 Equipment App

The Equipment App provides pages where it is possible to create and configure equipment in a user-friendly
environment.
The App includes:
• a Public Object Model (POM) consisting of the published artifacts of the Functional Blocks and their
relationships;
• a set of UI pages dedicated to Equipment modeling.
• UDM_RF
• EQU_MS
• EQU_OP
For a general understanding of Functional Blocks, refer to Overview of Functional Blocks in the Opcenter Execution
What can I do with the Equipment App?

• Useful conceptual information is provided at
• What is Equipment?
• What is the Connection between Equipment and Automation Gateway
• The workflow and procedures to configure the Plant and the connection with the Automation Gateway are
described at
• How to Configure the Plant.
• How to Configure the Association between Equipment and Automation Gateway
• Information on the Equipment management in the runtime environment is provided at How to Manage
Equipment in the Runtime Environment.
• For an overview of the referenced Functional Blocks and the related documentation see Opcenter Execution
Foundation App Overview
3.3.1 What is Equipment?

Equipment can be used to represent any physical resource used in manufacturing operations and can be organized
in Hierarchies and in Flows.

Manufacturing Apps
Equipment App
The Equipment Configuration essentially defines the manufacturing resources that identify the equipment
capabilities and material position within the production environment.
You can create the Equipment Configuration starting from the definition of an Equipment Type. Used as a sort of
template, the Equipment Type allows you to inherit and share common properties with other Equipment
Configurations. You can then modify these properties for each Equipment Configuration.
An Equipment Configuration can have one or more State Machines, providing you with the flexibility to represent
different Equipment Configuration life cycles according to the different contexts of use, e.g. Maintenance,
Production or Resource Planning.
Furthermore, you can create Equipment Group Configurations, which are useful to simplify and speed up the
configuration of the plant, allowing you to define logical or functional collections of Equipment that have similar
capabilities or that can be used as alternatives in a routing node.
Each Equipment Configuration has a corresponding Equipment runtime instance. On this instance you can directly
set Property and Status values, depending on the contextual operational information.
Both at Equipment Type Property level and at Equipment Configuration Property level, you can define property
values will be editable at runtime, in the corresponding Equipment runtime instance. This capability allows you to
distinguish between properties that inherently represent the Equipment Configuration (such as its allowed voltage
range, maximum rotating speed or target internal temperature and so on) and properties whose value strictly
depends on the runtime contextual information.
You can represent the Equipment Configuration in a hierarchical-driven containment way by defining an Equipment
Hierarchy. This offers you the possibility to provide a logical model, for instance, of its own Plant Model (including
temporary resources such as material handling units) or specific parts of the Plant Model itself that share the same
business relevance, such as Quality Areas, Warehouses, Production Areas, Lines Units, Receiving, Packaging or
Shipping Areas. While doing this, you can use a set of predefined (and extensible) Equipment Levels that are
following major ISA 95 and ISA 88 definitions.
You can also aggregate Equipment Configurations by means of Equipment Flows. Flows are the representation of
physical materials’ flowing paths, which include the production machines and the pipelines used to connect them.
3.3.2 What is the Connection between Equipment and Automation

Gateway
The OPCUAConnect Extension App, which extends the Equipment App data model and screens, allows you to
integrate the Equipment App data model with the Automation Gateway functionalities.
In particular, it allows you to link your plant model (Equipment model) to the shop-floor devices (Automation
Nodes) in order to exchange data with the shop-floor via OPC UA tags.
To do this, you have to use the Equipment app extended screens to associate a piece of Equipment with an
Automation Node and achieve the required configuration.
The OPCUAConnect App references the following Functional Blocks:
• OPCUAConnect_MS
• OPCUAConnect_OP
the above mentioned Functional Blocks.

Manufacturing Apps
Equipment App
3.3.3 How to Configure the Plant

You must use the Equipment App data model to configure all the items that are required to model your Plant and
that are involved in the production process.
The following entities are involved in the Equipment modeling flow:
• Equipment Type, if necessary, creates a predefined Equipment content (consisting of both a set of properties
with or without default values and a State Machine list) to be used as a template for the Equipment
Configuration.
• Equipment Configuration, represents the real Equipment in the plant, with both all necessary properties and a
State Machine list. Equipment Configurations can be created either from Equipment Types, thus inheriting both
a predefined set of properties and a State Machine list, or from scratch. A predefined piece of Equipment is
released by default and can be used by other apps.
• Equipment Level, can help you providing a hierarchical representation of Equipment Configuration.
• Equipment Group, collects Equipment with commonalities or that are alternatives in a routing node.
• Equipment Hierarchy, organizes the Equipment in a tree list. It can be used to model a hierarchical behavior that
takes place in the plant, but also a logical organization of the Equipment the plant consists of.
• Equipment Flow, defines the connections, both physical and logical, among Equipment. It can be used to set the
routings from a piece of Equipment (or an Equipment Group) to others.
Example
1. Create the following Equipment Types:
• OEM1_Multipacker, with the property Status.
• OEM2_Multipacker, with the properties StateCurrent, StateRequested and StateChangeInProcess.
2. Create an Equipment Configuration from each previously created Equipment Type naming them Multipacker1
and Multipacker2, to define the Equipment available on the existing packaging lines.
3. Create the Equipment Group Multipacker and assign the previously defined Equipment Configurations to it.

Manufacturing Apps
Equipment App
4. After configuring the other Equipment your plant consists of (including the Palletizer), create the Plant
Equipment Hierarchy to organize them in a tree list that represents the logical organization of the Equipment
within the plant.
5. Create the PackagingLine1 Equipment Flow establishing a connection from the Multipacker Equipment Group
to the Palletizer Equipment Configuration. In this case, the production flow connects both Multipackers to the
Palletizer.
Workflow
1. (Optional) Define Equipment Configuration Levels.
2. (Optional) Define the Equipment Types.
3. Define the Equipment Configurations.
4. (Optional) Define the Equipment Group Configurations.
• Define connections among Equipment (Equipment Flows)
• Define the physical model of the Plant (Equipment Hierarchies)
6. (Optional) Configure the connection with the Automation Gateway.
3.3.3.1 Defining Equipment Levels

Equipment App provides a set of Equipment Levels that can help you providing a hierarchical representation of
Equipment Configuration. This hierarchical structure is defined by a code that is assigned to each level: top levels
are defined by lower codes.
The following table shows the levels defined by default, according to the level code, and displayed in
the Equipment Level page.
Equipment Level Level Code Description
Enterprise 100 An Enterprise is a collection of Sites and Areas and

represents the top level of a role based
equipment hierarchy.
Site 200 A Site is a physical, geographical, or logical

grouping determined by the Enterprise. It may
contain Areas, Production Lines, Process Cells, and
Production Units.
Area 300 An Area is a physical, geographical, or logical

grouping determined by the Site. It may
contain Process Cells, Production Units, Production
Lines, and Storage
Zones.
ProcessCell 500 Process cells are the low level of equipment

typically scheduled by the Level 4 and Level 3
functions for batch manufacturing processes. The
definitions for process cells are
contained in IEC 61512-1.

Manufacturing Apps
Equipment App
Equipment Level Level Code Description
ProductionLine 500 Production lines are low levels of equipment

typically scheduled by the Level 4 or Level 3
functions for discrete manufacturing processes.
StorageZone 500 Storage zones are low level of material movement

equipment typically scheduled by the
Level 4 and Level 3 functions for discrete, batch and
continuous manufacturing processes.
WorkUnit 600 A Work Unit is any element of the equipment

hierarchy. Work units are
the lowest form of elements in an equipment
hierarchy that are typically scheduled by Level
3 functions.
Unit 700 Units are low level of equipment typically

scheduled by the Level 4 and Level 3 functions
for batch manufacturing processes and continuous
manufacturing processes. The definition of
the unit for batch manufacturing processes is
contained in IEC 61512-1.
WorkCell 700 Work cells are low levels of equipment typically

scheduled by the Level 4 or Level 3
functions for discrete manufacturing processes.
StorageUnit 700 Storage units are low level of material movement

equipment typically scheduled by the
Level 4 and Level 3 functions for discrete, batch and
continuous manufacturing processes.
ProductionUnit 800 Production units are the lowest level of equipment

typically scheduled by the Level 4 or
Level 3 functions for continuous manufacturing
processes.
When configuring your plant, you can decide to use the default levels or create new ones from scratch, as described
in the following procedure.
Audit Trail is displayed in the Equipment Level page to provide evidence of all the operations that have been
carried out on a specific Equipment Level. Its records can be viewed by selecting the particular Equipment Level
and clicking on Audit Trail tab.
Procedure
1. Do either of the following to open the Equipment Levels page:
• Click the Equipment Levels home tile.

Manufacturing Apps
Equipment App
• Click Equipment Engineering in the side menu bar and click Equipment Levels.
2. Click .
3. Set the following parameters and click Save:
Id The unique identifier assigned to the Equipment Level. Once

the Equipment Level is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Equipment Level.
Description (Optional) Additional information on the Equipment Level.
Level The code assigned to the Equipment Level. It must set to a value
>=0.
Available Operations on Equipment Levels

On the existing Equipment Levels you can then perform the following operations, by selecting the Equipment Level
in the Equipment Levels page.
/ The Freeze operation allows you to configure an Equipment Level as

read-only, so that it cannot be edited. When the Freeze operation is
Freeze/Unfreeze performed on an Equipment Level, the Equipment Level is
flagged as IsFrozen.
You can remove the read-only setting by performing the Unfreeze
operation.
Edit To modify Name, Description and Level of an Equipment Level.

The Equipment Level must not be flagged as IsFrozen.
 Level cannot be modified on the Equipment Levels defined by

default.
Delete To permanently remove an Equipment Level.
 This operation cannot be performed on the Equipment Levels

defined by default.
To export selected entities and instances in an export package that can

Export
be downloaded locally and imported afterwards. See How To Export and
Import Data.

Manufacturing Apps
Equipment App
 The Equipment Levels page provides common functionalities such as Group By, Quick Search, Filter and
User Preferences. The Filter functionality provides a more refined search in addition to Quick Search. You
can filter Equipment Levels by Id, Name, Level and Is Frozen.
3.3.3.2 How to Define Equipment Types

To speed up the creation of Equipment Configurations you can set an Equipment Type as default and use it to
create Equipment Configurations; otherwise, Equipment Configurations can be created from scratch. Equipment
Types consist of both a set of properties and a State Machine list. They allow you to configure predefined
equipment contents to be used as templates for Equipment Configurations.
Once created and configured, Equipment Types can be frozen (Freeze ) thus preventing users from modifying
them.
When creating Equipment Configurations, you can firstly define Equipment Types in order to specify a set of
common properties and a State Machine list that will be shared by all Equipment Configurations created from that
Equipment Type.
Equipment Type Properties allow you to extend the information of an Equipment Type, by defining additional
properties, with an Id, a data type and an optional (default) value.
Any change performed on the Equipment Type is not applied to the already created Equipment Configurations.
Even if an Equipment Configuration has been created specifying a reference Equipment Type and inheriting both
properties (their data types and values) and state machines, Equipment Configuration Properties and State
Machines can be managed adding new ones, updating or deleting the existing ones.
Audit Trail is displayed in the Equipment Type page to provide evidence of all the operations that have been
carried out on a specific Equipment Type and its properties. Its records can be viewed by selecting the
particular Equipment Type and clicking on Audit Trail tab.
Workflow
1. Create an Equipment Type.
2. (Optional) Add a Property to an Equipment Type.
3. (Optional) Assign one or more State Machines to an Equipment Type.
Creating an Equipment Type

1. Do either of the following to open the Equipment Types page:
• Click the Equipment Types home tile.

• Click Equipment Engineering in the side menu bar and click Equipment Types.
2. Click .
Id The unique identifier assigned to the Equipment Type. Once

the Equipment Type is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Equipment Type.

Manufacturing Apps
Equipment App
Description (Optional) Additional information on the Equipment Type.
Level (Optional) The level to be set if want to provide a hierarchical

representation of Equipment Type and arrange each equipment
according to the value defined in Equipment Level page.
The following are the default values, otherwise you can set a custom
level defined in the Equipment Level page:
• Enterprise
• Site
• Area
• ProcessCell
• ProductionLine
• StorageZone
• WorkUnit
• Unit
• WorkCell
• StorageUnit
• ProductionUnit
Adding a Property to an Equipment Type

To define the properties of the Equipment Type:
1. In the Equipment Types page, select the Equipment Type to which you want to add the Property, and click
to open the Equipment Type page.
2. In the Properties tab, click .
Id The unique identifier assigned to the property. Once the property is

Property Type The data type of the property (string, decimal, etc).
Property Default Value (Optional) The default value of the property, to be set according to
the format: 'yyyy'-'MM'-'dd' 'HH':'mm':'ss' (for example 2017-12-25
12:00:00).
Runtime Editing If selected, the property value can be modified in the runtime
environment.
4. To further detail the properties through additional attributes, click to open the Equipment
Type Properties page.
5. To define new attributes, in the Attribute tab select the created Property.
6. Click .
7. Set the following parameters and click Save.

Manufacturing Apps
Equipment App
Id The unique identifier assigned to the attribute. Once

the property is created, the Id value cannot be modified.
Attribute Type The data type of the attribute (string, decimal, etc).
Attribute Default Value (Optional) The default value of the attribute.
Runtime Editing If selected, the attribute value can be modified in the runtime
environment.
Assigning a State Machine to an Equipment Type

1. To assign one or more State Machines, defined in the Reference App, in the Equipment Types page, select the
Equipment Type and click to open the Equipment Type page.
2. In the State Machine tab, click .
3. Select the required State Machine and click Save. The system populates the State Machine List by adding the
new State Machine.
Available Operations on Equipment Types

On the existing Equipment Types you can then perform the following operations, by selecting the Equipment Type
and clicking the proper icon in the Equipment Types page.
/ Freeze/Unfreeze The Freeze operation allows you to configure an Equipment Type as read-
only, so that it cannot be edited. When the Freeze operation is performed on
an Equipment Type, the Equipment Type is flagged as IsFrozen.
operation.
Set as Default To set the selected Equipment Type as default, thus allowing the system to
automatically select it while creating an Equipment Configuration.
Edit To modify Name, Description and Level of an Equipment Type. The

Equipment Type must not be flagged as IsFrozen.
 If you launch the UpdateEquipmentType command (documented

at EQU_MS Functional Block in the Opcenter Execution
Foundation Development and Configuration Guide) in the with
the State Machine NId set, the State Machine List will be empty.
Delete To permanently remove an Equipment Type.

Manufacturing Apps
Equipment App

Export
downloaded locally and imported afterwards. See How To Export and
Import Data.
Available Operations on Equipment Type Properties

On the existing Equipment Type Properties you can then perform the following operations, by selecting the
Equipment Type Property and clicking the proper icon in the Properties tab of the Equipment Type page.
Edit To modify Property Default Value of an Equipment Type Property.
Delete To permanently remove an Equipment Type Property.
Available Operations on Equipment Type Property Attributes

On the existing Equipment Type Property Attributes you can then perform the following operations, by selecting the
Equipment Type Property Attribute and clicking the proper icon in the Attributes tab of the Equipment
Type Properties page.
Edit To modify the type or the default value of an attribute.
Delete To permanently remove an Equipment Type Property Attribute.
Available Operations on Equipment Type State Machines

On the existing Equipment Type State Machines you can then perform the following operations, by selecting the
Equipment Type State Machine and clicking the proper icon in the State Machine tab of the Equipment Type page.
Delete To remove an Equipment Type State Machine.
 The Equipment Types page provides common functionalities such as Group By, Quick Search, Filter and
can filter Equipment Types by Id, Name, Description, Is Default, Level and Is Frozen.
3.3.3.3 How to Define Equipment Configurations

Once created and configured, Equipment Configurations can be edited (apart from the Id) and can be frozen
(Freeze ) thus preventing users from modifying them. While creating Equipment Configurations you can choose

Manufacturing Apps
Equipment App
if you want to base them on an Equipment Type or not. Equipment Configurations inherit the properties and the
State Machines of the related Equipment Type, but you can customize the default values both of the inherited
properties and State Machines and define new ones.
Equipment used within Equipment Hierarchies or Equipment Flows cannot be deleted.
For the Equipment Configurations, more State Machines can be defined, each of them representing a life cycle in
different perspectives (see the following table showing class-based status types and values).
Equipment Class Members Status Type Status Values
Prep tank T1000, T1001 Availability Available, In use, Out-of-service
Dirty, Clean
Mix tank T2000, T2001 Availability Available, In use, Out-of-service
Cleaning Dirty, Clean, Sterile
Process Empty, Mixing, Mixed
Transfer line TL1000200X Availability Available, In use, Out-of-service
TL1001200X
TL100X2000 Cleaning Dirty, Clean
TL100X2001
Transfer panel TP100X200X Availability Available, In use, Out-of-service
Cleaning Dirty, Clean

This allows you to manage a complex Equipment status in your environment.
Audit Trail is displayed in the Equipment Configurations page to provide evidence of all the operations that have
been carried out on a specific Equipment and Equipment Configuration Properties. Its records can be viewed by
selecting the particular Equipment and clicking on Audit Trail tab.
 When you create Equipment Configurations in the engineering environment, the system creates
automatically corresponding Equipment instances in the runtime environment.
Workflow
1. Create an Equipment Configuration.
2. (Optional) Add a Property to an Equipment Configuration.
3. (Optional) Associate an Equipment with an existing Equipment Group.
4. (Optional) Assign one or more State Machines to an Equipment Configuration.
Creating an Equipment Configuration

1. Do either of the following to open the Equipment Configurations page:
• Click the Equipment Configurations home tile.

Manufacturing Apps
Equipment App
• Click Equipment Engineering in the side menu bar and click Equipment Configurations.
2. Click .
Id The unique identifier assigned to the Equipment Configuration.

Once the Equipment Configuration is created, the Id value cannot be
modified.
Name (Optional) The name assigned to the Equipment Configuration.
Description (Optional) Additional information on the Equipment Configuration.
Equipment Type (Optional) The Equipment Type to be used to define the

Equipment Configuration content. Once
the Equipment Configuration is created, the Equipment Type value
cannot be modified. If the parameter is not selected, the system
automatically uses the Equipment Type that is currently set as
default, and if the default Equipment Type does not exist, the system
creates an empty Equipment Configuration.
Level (Optional) The level to be set if want to provide a hierarchical

representation of Equipment Configuration and arrange each
equipment according to the value defined in Equipment Level page.
Equipment Configuration inherits the level of the related Equipment
Type. Otherwise, you can set one of the following default values or a
custom level defined in the Equipment Level page:
• Enterprise
• Site
• Area
• ProcessCell
• ProductionLine
• StorageZone
• WorkUnit
• Unit
• WorkCell
• StorageUnit
• ProductionUnit
Adding a Property to an Equipment Configuration

To define the properties associated to the Equipment Configuration:
1. In the Equipment Configurations page, select the Equipment Configuration to which you want to add the
Property and click to open the Equipment Configuration page.
2. Click the Properties tab. If the Equipment Configuration has been created from an existing Equipment Type,
here you will find the inherited Equipment Type properties.
3. To add any other property, click .

Manufacturing Apps
Equipment App
Id The unique identifier assigned to the property. Once

Property Type The data type of the property (string, decimal, etc).
Property Default Value (Optional) The default value of the property.
Runtime Editing If selected, the property value can be modified in the runtime
environment.
5. To further detail the properties through additional attributes, click to open the Equipment
Configuration Properties page.
6. To define new attributes, click the Attribute tab and select the required Property.
7. Click .
8. Set the following parameters and click Save.
Id The unique identifier assigned to the attribute. Once

Attribute Type The data type of the attribute (string, decimal, etc).
Attribute Default Value (Optional) The default value of the attribute.
Runtime Editing If selected, the attribute value can be modified in the runtime
environment.
Associating Equipment Configurations with Equipment Group Configurations

1. In the Equipment Configurations page, select the Equipment Configuration to which you want to associate the
Equipment Group and click to the Equipment Configuration page.
2. In the Equipment Group Configuration tab, click .
3. Select an existing Equipment Group and click Save. You can associate more Equipment Configurations to the
same Equipment Group, but you must create one association at a time.
 You can remove the association between Equipment Configuration and Equipment Group by selecting
the Equipment Configuration and clicking .
Assigning a State Machine to an Equipment Configuration

To assign one or more State Machines, defined in the Reference App:
1. In the Equipment Configurations page, select the Equipment Configuration and click to
the Equipment Configuration page.
2. Click the State Machine tab. If the Equipment Configuration has been created starting from an existing
Equipment Type, here you can find the state machines assigned to Equipment Type inherited by the Equipment
Configuration.

Manufacturing Apps
Equipment App
3. To assign other State Machines, click .

4. Select the required State Machine and click Save.
Available Operations on Equipment Configurations

On the existing Equipment Configurations you can then perform the following operations, by selecting the
Equipment Configuration and clicking the proper icon in the Equipment Configurations page.
/ Freeze/ The Freeze operation allows you to configure an Equipment Configuration as read-
Unfreeze only, so that it cannot be edited.
When the Freeze operation is performed on an Equipment Configuration,
the Equipment Configuration is flagged as IsFrozen.
You can remove the read-only setting by performing the Unfreeze operation.
Edit To modify Name and Description of an Equipment Configuration.

The Equipment Configuration must not be flagged as IsFrozen.
Delete To permanently remove an Equipment Configuration.
Export To export selected entities and instances in an export package that can be
downloaded locally and imported afterwards.
See How to Export and Import Data.
Synchronize To manually synchronize Equipment Configurations and runtime Equipment.
Available Operations on Equipment Configuration Properties

On the existing Equipment Configuration Properties you can then perform the following operations, by selecting
the Equipment Configuration Property and clicking the proper icon in the Properties tab of the Equipment
Configuration page.
Edit To modify Property Default Value of an Equipment

Configuration Property.
Delete To permanently remove an Equipment Configuration Property.
Available Operations on Equipment Configuration Property Attributes

On the existing Equipment Configuration Property Attributes you can then perform the following operations, by
selecting the Equipment Configuration Property Attribute and clicking the proper icon in the Attributes tab of
the Equipment Configuration Properties page.

Manufacturing Apps
Equipment App
Edit To modify the type or the default value of an attribute.
Delete To permanently remove an Equipment Configuration Property Attribute.
Available Operations on Equipment Configuration State Machines

On the existing Equipment Configuration State Machines you can then perform the following operations, by
selecting the Equipment Configuration State Machine and clicking the proper icon in the State Machine tab of
the Equipment Configuration page.
Delete To remove an Equipment Configuration State Machine.
 The Equipment Configurations page provides common functionalities such as Group By, Quick Search,
Search. You can filter Equipment Configurations by Id, Name, Equipment Type, Level and Is Frozen.
3.3.3.4 How to Define Equipment Group Configurations

The creation of Equipment Group Configuration is useful to simplify and speed up the configuration of the plant,
since Equipment Group Configurations allow you to define logical or functional collections of Equipment that have
similar capabilities or that can be used as alternatives in a routing node.
Equipment Group Configurations can be edited (apart from the Id) and can be frozen (Freeze ) thus preventing
users from modifying them, as long as they do not have Equipment assigned.
In addition, Equipment Group Configurations can be associated with other Equipment Group Configurations, in
order to model equip classes and sub-classes.
Audit Trail is displayed in the Equipment Group Configuration page to provide evidence of all the operations that
have been carried out on a specific Equipment Group. Its records can be viewed by selecting the
particular Equipment Group and clicking on Audit Trail tab.
Workflow
1. Create an Equipment Group Configuration.
2. (Optional) Associate an Equipment Group Configuration with an existing Equipment Configuration.
3. (Optional) Join the selected Equipment Group Configuration (as sub-group) with another Equipment Group
Configuration.
4. (Optional) Associate another Equipment Group Configuration (as sub-group) with the selected Equipment
Group Configuration.
Creating an Equipment Group Configuration

1. Do either of the following to open the Equipment Group Configurations page:

Manufacturing Apps
Equipment App
• Click the Equipment Group Configurations home tile.

• Click Equipment Engineering in the side menu bar and click Equipment Group Configurations.
2. Click .
Id The unique identifier assigned to the Equipment Group. Once

the Equipment Group is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Equipment Group.
Description (Optional) Additional information on the Equipment Group.
Category (Optional) A label to be assigned to the Equipment Group to further

classify it either from a logical or a functional point of view. This parameter
can be used to create implicit relationships among different
Equipment Groups.
Associating an Equipment Group with an Equipment Configuration

1. In the Equipment Group Configurations page, select the Equipment Group and click to open
the Equipment Group Configuration page.
2. In the Equipment Configuration tab, click .
3. Select an existing Equipment Configuration and click Save. You can associate more Equipment with the same
Group, but you must create one association at a time.
To remove the association between Equipment Groups and Equipment Configurations, click .
Joining an Equipment Group Configuration with another Equipment

Group Configuration
2. In the Grouped In tab, select the Equipment Group Configuration you want to join with another Equipment
Group Configuration.
3. Click .
4. In the Join Equipment Group Configuration screen, select the Equipment Group Configuration you want to
join with the Equipment Group Configuration.
5. Click Save.
To remove the association between Equipment Group Configurations, click .
Associating an Equipment Group Configuration with another Equipment

Group Configuration

Manufacturing Apps
Equipment App
2. In the Equipment Group Configuration tab, select the Equipment Group Configuration you want to associate
with another Equipment Group Configuration.
3. Click .
4. In the Associate Equipment Group Configuration screen, select the Equipment Group Configuration you want
to associate with the Equipment Group Configuration.
5. Click Save. You can create one association at a time.
To remove the association between Equipment Group Configurations, click .
Available Operations on Equipment Group Configurations

On the existing Equipment Group Configurations you can then perform the following operations, by selecting the
Equipment Group Configurations and clicking the proper icon in the Equipment Group Configurations page.
To modify Name, Description and Category of an Equipment Group

Edit
Configuration.
To remove an Equipment Group Configuration.

Delete
The Freeze operation allows you to configure an Equipment

/ Freeze/Unfreeze
Group Configuration as read-only, so that it cannot be edited. When
the Freeze operation is performed on an Equipment Group
Configuration, the Equipment Group Configuration is
operation.

Export
can be downloaded locally and imported afterwards. See How to
Export and Import Data.
Synchronize To manually synchronize Equipment Group Configurations and

runtime Equipment Groups.
 The Equipment Group Configurations page provides common functionalities such as Group By, Quick
Search, Filter and User Preferences. The Filter functionality provides a more refined search in addition to
Quick Search. You can filter Equipment Group Configurations by Id, Name, Category and Is Frozen.
3.3.3.5 How to Define Connections among Equipment Items

Equipment Configuration Flows represent the connections, both physical and logical, among Equipment, thus
defining routings from a piece of Equipment (or an Equipment Group) to another.
It is possible to configure different connections among Equipment or Equipment Groups simply creating multiple
Equipment Flows. You must then configure each Equipment Flow populating it with the items of interest and
defining the available connections among the involved items.

Manufacturing Apps
Equipment App
Audit Trail is displayed in the Equipment Flow Configuration page to provide evidence of all the operations that
have been carried out on a specific Equipment flow configuration. Its records can be viewed by selecting the
particular Equipment flow and clicking on Audit Trail tab.
Prerequisite
If you want to define a Flow including more than ten Equipment, modify the web.config file of Opcenter EX
FN Service Layer, as described in the following table:
Section Add
<appSettings> <add key="ServiceLayerMaxNodeCount" value="1000" />
<configuration> / <system.web> maxQueryStringLength="102400" in the <httpRuntime> tag
<system.webServer> / <security> / maxQueryString="102400" in the <requestLimits> tag

<requestFiltering>
Workflow
1. Create an Equipment Flow.
2. Configure an Equipment Flow.
Creating an Equipment Flow Configuration

1. Do either of the following to open the Equipment Flow Configurations page:
• Click the Equipment Flow Configurations home tile.

• Click Equipment Engineering in the side menu bar and click Equipment Flow Configurations.
2. In the Equipment Flow Configurations page, click and set the following parameters:
Id The unique identifier assigned to the Equipment Flow. Once

the Equipment Flow is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Equipment Flow.
Description (Optional) Additional information on the Equipment Flow.

3. Click Save.
Configuring an Equipment Flow Configuration

1. In the Equipment Flow Configurations page, select the previously created Equipment Flow from the list.
2. Click Open Flow in the actions bar and then expand either of the following nodes:
• Add by Equipment Configuration, to include Equipment in the Equipment Flow.
• Add by Equipment Group Configuration, to include Equipment Groups in the Equipment Flow.
3. Select the item of interest and then click : the system displays a rectangle representing the selected item in
the upper left corner of the window.

Manufacturing Apps
Equipment App
4. Drag and drop the inserted item to the proper position. If the item is not moved, any subsequently inserted item
will be displayed on top of the existing one, hiding it.
5. To define connections, move the cursor over the item from which the connection starts and then drag and drop
one of the blue arrows displayed on its sides to the target item.
6. To add a label providing information on a connection, select the relative arrow, click , type the description
of interest and then click outside of the edit box to quit the editing mode.
7. If necessary, delete unnecessary items or connections, selecting them and then clicking .
8. Click Save.
 The Equipment Flow Configurations page provides common functionalities such as Group By, Quick
Search, Filter and User Preferences. The Filter functionality provides a more refined search in addition
to Quick Search. You can filter Equipment Flow Configurations by Id and Name.
Available Operations on Equipment Flow Configurations

To open the selected Equipment Flow Configuration and access

Open Equipment Flow Configuration
its details and Audit Trails.
To open the Equipment Flow Configuration in the Flow Editor.

Open Flow
To modify Name and/or Description of the Equipment Flow.

Edit
To permanently remove unnecessary items or connections of

Delete
the Equipment Flow.
To export selected entities and instances in an export package

Export
that can be downloaded locally and imported afterwards. See
How to Export and Import Data
To manually synchronize Equipment Flow Configurations with

Synchronize
runtime Equipment Flows.
3.3.3.6 How to Define the Physical Model of the Plant

The definition of Equipment Hierarchies is useful not only to model the hierarchical behavior that takes place in the
plant, but also to configure the logical organization of the Equipment the plant consists of.
You can define multiple Equipment Hierarchies to be used within the same plant for different needs. Each
Equipment Hierarchy, once created, must be populated with the proper Equipment that can then be organized into
different levels.
The system saves data relative to each Equipment Hierarchy in a json file.

Manufacturing Apps
Equipment App
Audit Trail is displayed in the Equipment Hierarchy Configuration page to provide evidence of all the operations
that have been carried out on a specific Equipment hierarchy configuration. Its records can be viewed by selecting
the particular Equipment hierarchy configuration and clicking on Audit Trail tab.
Workflow
1. Create an Equipment Hierarchy.
• Configure an Equipment Hierarchy
• Import an Equipment Hierarchy
Creating an Equipment Hierarchy

1. Do either of the following to open the Equipment Hierarchy Configurations page:
• Click the Equipment Hierarchy Configurations home tile.

• Click Equipment Engineering in the side menu bar and click Equipment Hierarchy Configuration.
2. In the Equipment Hierarchy Configurations page, click , set the following parameters and then click Save.
Id The unique identifier assigned to the Equipment Hierarchy. Once

the Equipment Hierarchy is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Equipment Hierarchy.
Description (Optional) Additional information on the Equipment Hierarchy.
Configuring an Equipment Hierarchy

1. In the Equipment Configuration Hierarchies page, select the previously created Equipment Hierarchy from the
list and click to open Equipment Hierarchy Configuration page.
2. In the Hierarchy tab, click to add a new node to the selected Equipment Hierarchy.
3. If the Equipment Hierarchy has been previously configured and it already contains Equipment, select the node
below which you want to add other Equipment.
4. Select the Equipment of interest.
5. Click Save.
6. The selected Equipment is displayed as a flat list below the previously selected node (or at root level if no node
had been selected): organize the Equipment hierarchically by dragging and dropping the required items to the
proper position. When you move a node, also the underlying nodes are automatically moved.
7. To remove an item from the Equipment Hierarchy, select it and then click the related icon on the right. Bear
in mind that if you choose to remove a node, also the underlying nodes are removed from the Equipment
Hierarchy.
Importing an Equipment Hierarchy
1. Define an Equipment Hierarchy as described in Equipment Hierarchy json File.

Manufacturing Apps
Equipment App
2. In the Equipment Hierarchy Configurations page, select the previously created Equipment Hierarchy from the
list and click to open Equipment Hierarchy Configuration page. Note that this Equipment Hierarchy must
be empty, otherwise the import operation cannot be performed (the Import button is not displayed).
3. In the Hierarchy tab, click and browse for the .json file previously created.
4. Click , the Equipment Hierarchy is displayed below.
 The Equipment Hierarchies page provides common functionalities such as Group By, Quick
to Quick Search. You can filter Equipment Hierarchy by Id and Name
Available Operations on Equipment Hierarchy Configurations

On the existing Equipment Hierarchy you can then perform the following operations, by selecting the Equipment
Hierarchy Configuration and clicking the proper icon.
To modify Name and Description of an Equipment Hierarchy.

Edit
To permanently remove an Equipment Hierarchy.

Delete

Export
downloaded locally and imported afterwards. See How to Export and
Import Data.
To manually synchronize Equipment Hierarchy Configurations with

Synchronize
runtime Equipment Hierarchies.
3.3.3.6.1 Equipment Hierarchy json File
 Note
In order to successfully import an Equipment Hierarchy from a .json file, please be sure to have already
defined the Equipment Configuration to be used as hierarchy's nodes.

Manufacturing Apps
Equipment App
Example to create a hierarchy
[
{
"EquipmentId":1,
"EquipmentNId":"Equip1",
"EquipmentDesc":"Equip1",
"EquipmentTypeNId":"",
"ChildrenNodes":[
{
"EquipmentId":2,
"ChildrenNodes":[
{
"EquipmentId":3,
"ChildrenNodes":[
]
},
{
"EquipmentId":4,
"ChildrenNodes":[
]
}
]
},
{
"EquipmentId":5,
"ChildrenNodes":[
]
}
]
},
{
"EquipmentId":6,

Manufacturing Apps
Equipment App
"ChildrenNodes":[
]
}
]
Where:
Property Description
EquipmentId The identifier of the Equipment Graph Node Configuration.
EquipmentNId The natural key identifier of the Equipment Configuration.
EquipmentDesc (Optional) The description of the Equipment Configuration.
EquipmentTypeNId (Optional) The natural identifier of the Equipment Type associated with the
Equipment.
ChildrenNodes (Optional) The list of child Equipment.
If you want to modify an Equipment Hierarchy programmatically using

the BulkImportEquipmentHierarchy command, provided by the EQU_MS Functional Block, you must create the
following .json file manually, populating it with data relative to already existing Equipment.

Manufacturing Apps
Equipment App
Example to modify a hierarchy
[
{
"EquipmentId":"1c16b46d-475c-4f4e-8fd6-667e3fb5389e",
"EquipmentNId":"EQ_12",
"EquipmentTypeNId":"EQ_T_2",
"ParentNodeId":"",
"LinkId":null,
"ChildrenNodes":[
]
},
{
"EquipmentId":"ab1ecb5d-81ab-4c5a-98e0-6bf436ebccf2",
"ParentNodeId":"",
"LinkId":null,
"ChildrenNodes":[
{
"EquipmentId":"d98a8350-fc8b-42d6-b010-80980e07a83a",
"ParentNodeId":"ab1ecb5d-81ab-4c5a-98e0-6bf436ebccf2",
"LinkId":"8e6e7f54-18e7-4f51-9fe3-84104e2f83a0",
"ChildrenNodes":null
}
]
},
{
"EquipmentId":"dd12392a-5ae1-47eb-8d66-f790c4a6615d",
"ToBeDeleted":true
}
]
Where in addition to the fields described above:
ParentNodeId Optional) The identifier of the Parent Equipment. If you specify this
property, the Equipment will be added to the Hierarchy as child of another
Equipment; otherwise it will be set as a root element of the Hierarchy.
LinkId (Only if ParentNodeId property has been set) The identifier of the
connection between the Equipment and its parent.
ToBeDeleted Flag indicating if the Equipment must be removed from the hierarchy (true)
or not (false).

Manufacturing Apps
Equipment App
3.3.3.7 Exporting and Importing Equipment Data

The Equipment App allows you to export and import its own master data entities. Unlike the Export operation, the
section.

Example: If you want to import Equipment Type with Custom Equipment Level, you must first import the
Equipment Level package and then the Equipment Type.
 Note that both Equipment Configuration and Equipment Type are parent entities.
 Export Import Packages from version 3.3

If you need to import packages that were exported in 3.x version and that contain entities which refer to
obsolete/removed entities, you must first apply manual changes to the package format files (fmt files) in
order to align the data model schema, before you can correctly perform the import operation.
To import Equipment Configurations, for instance, open the EquipmentConfiguration.fmt file of the
export package and manually remove the line referring to LocationNId from the <ROW> section. As far as
EquipmentType is concerned, open the corresponding fmt file and remove the line referring to
the StateMachineNId.
For more details on the obsolete properties, see Obsolete Functionalities in the Opcenter Execution
Foundation Release Notes.

Manufacturing Apps
Equipment App
Equipment Equipment Equipment Equipment Group Notes

Level Type Configuration
Equipment The export/import

Level operation is
necessary only in
case of custom
Equipment Levels.
Equipment If you export any

Type Equipment Type, the
(only in case related Equipment
of association Type Properties,
with Custom Equipment Type
Equipment Property Attributes,
Levels) Equipment Type
State Machine are
also automatically
exported.
If the State Machines
are specified, they
should be present in
the target
environment.
Equipment If you export any

Configurati Equipment
on (only in case (only in Configuration, the
of association case the related Equipment
with Custom Equipment Configuration
Equipment Type is Properties,
Level) specified) Equipment
Configuration
Property Attributes,
Equipment
Configuration State
Machine are also
automatically
exported.
If one or more State
Machines are
specified, they
should be present in
the target
environment.

Manufacturing Apps
Equipment App
Equipment Equipment Equipment Equipment Group Notes

Level Type Configuration
Equipment If the Equipment

Configurati Configuration
on & belongs to an
Equipment Group
Equipment
Configuration:
Group
1. Export the
Equipment
Configuration by
setting Include
Descendants to
False.
2. Export the
Equipment
Group
Configuration by
setting Include
Descendants to
True.
3. Import the
Equipment
Configuration.
4. Import the
Equipment
Group.
Equipment Equipment Equipment Flow Notes

Group Hierarchy
Equipment If Equipment Groups are

Group hierarchically associated, export
the root entity by setting Include
Descendants to True.
Otherwise, if some parent
Equipment Groups are not
included in the export
package, these entities should be
already present in the target
environment, so that referential
integrity is preserved.

Manufacturing Apps
Equipment App
Equipment Equipment Equipment Flow Notes

Group Hierarchy
Equipment If the Equipment Hierarchies

Hierarchy are exported by setting Include
Descendants to False, the
hierarchy among all the
equipment entities is not
exported, so they will be at the
same level.
Equipment If the Equipment Flows

Flow are exported by setting Include
Descendants to False, the
link among all the equipment
entities is not exported.
3.3.3.8 How to Configure the Association between Equipment and

Automation Gateway
In order to link the plant model to the shop-floor, you have to integrate Equipment App and Automation App.
At engineering level you have to associate Equipment Types with Automation Node Types and Equipment
Configurations with Automation Node Instances. Then you have to activate the data transmission between
Equipment and OPC Servers.
Each time an Automation Node Instance is associated to an Equipment Configuration, the system automatically
creates, at runtime, the association between the Equipment and the Automation Node only if the Automation Node
has been deployed in operational domain, as consequence of its relative Automation Node Instance activation.
 We suggest you not freeze an Equipment Configuration if you have associated it to an Automation Node
Instance that is still not activated. This is due to the fact that when the Automation Node Instance will be
activated, the system will not be able to automatically create the association between the relative
Equipment and Automation Node.
Prerequisites
Automation Node Types and Instances are configured.
Workflow
1. Associate an Equipment Type with one or more Automation Node Types. This step allows you to create a
predefined association to be used as a template for the Equipment Configuration.
2. Associate an Equipment Configuration with one or more Automation Node Instances. This step allows you to
configure the communication between Equipment and Automation Gateway that will be used at runtime.

Manufacturing Apps
Equipment App
3.3.3.8.1 Associating an Equipment Type with an Automation Node Type

The first step in configuring the association between an Equipment and the Automation Gateway, foresees
associating an Equipment Type with one or more Automation Node Types. You can associate more Automation
Node Types, one at a time.
Procedure
1. Click Equipment Engineering in the sidebar and then click Equipment Type Management to
open the Equipment Type Management page.
2. Select an Equipment Type and click the Automation Node Type tab.
3. Click , browse and select the Automation Node Type.
Available Operations on the Association

On the existing associations you can then perform the following operations, by selecting the Equipment Type, the
Automation Node Type of interest and clicking the proper icon in the right sidebar of the Automation
Node Type tab.
To permanently remove the association between an Equipment Type and an

Remove the
Automation Node Type.
Association
3.3.3.8.2 Associating an Equipment Configuration with an Automation Node

Instance
While associating an Equipment Configuration to one or more Automation Node Instances, you can choose to
inherit the association between the selected Equipment Type and the Automation Node Instances, if any, or you
can choose among all the Automation Node Instances that have been defined in the system.
While associating an Equipment Configuration to one or more Automation Node Instances, you can choose whether
you want to associate any Automation Node Instances belonging to any Automation Node Type, or if you want to
limit this choice to the instances that belong only to the Automation Node Type which is associated to the
Equipment Type you have assigned to the Equipment Configuration.
If there is no Equipment Type associated to the current Equipment Configuration, you can associate
any Automation Node Instances belonging to any Automation Node Type.
Procedure
1. Click Equipment Engineering in the sidebar and then click Equipment Configuration Management to
open the Equipment Configuration Management page.
2. Click the Automation Node Instance tab.
3. (Optional) If you have associated an Equipment Type to the current Equipment configuration, select the Use all
Automation Node Instances (..) check box if you want to choose the Automation Node Instances from the
entire set of the available Automation Node Types, regardless of the Automation Node Type which is associated
to the Equipment Type. Otherwise, you will browse only the Automation Node Instances that belong to the
Automation Node Type which is associated to the Equipment Type.
4. Click and select the Automation Node Instance.

Manufacturing Apps
Equipment App
Available operations on the association of Automation Node Instances

The following operation is available:
Remove Association To remove the association between an Equipment Configuration and

an Automation Node Instance. To do this, you have to select the
Equipment Configuration, click the Automation Node Instance tab
and select the Automation Node Instance you want to remove.
3.3.4 How to Manage Equipment in the Runtime Environment

When you create or modify any Equipment Configurations in the engineering environment, the system
automatically creates or modifies corresponding Equipment instances in the runtime environment by copying data
from the Master Data domain to the Operational Data domain.
When the system creates the runtime Equipment instances, both the Properties and the Attributes that are
assigned to the Equipment Configurations are inherited by the Equipment, as well as the related Equipment Levels.
If the Equipment Configurations have a State Machine List assigned, the runtime Equipment will be created with the
same State Machine List.
The system does not automatically synchronize the runtime environment if you manually import engineering data
(e.g. via BulkImport API or DBinit.xml configuration file or import functionality). In these cases, as well as in any
other misalignment situation, you can perform a manual synchronization to re-align the environments.
What can I do in the runtime environment

In the runtime environment, you can perform the following operations

Manufacturing Apps
Equipment App
• Modifying the status of a State Machine assigned to the Equipment

• Visualizing Properties and related Attributes assigned to the Equipment
• Modifying the value of properties assigned to the Equipment
• Modifying the property attributes assigned to the Equipment
• Manually synchronizing engineering and runtime environments
 The Equipment page provides common functionalities such as Group By, Quick Search, Filter and User
Preferences. The Filter functionality provides a more refined search in addition to Quick Search. You can
filter Equipment by Id, Name, Level, Created On and Last Updated On.
3.3.4.1 Modifying the Status of Equipment State Machine

You can modify the status of one or more State Machines associated with the Equipment.
Procedure
1. Do either of the following to open the Equipment page:
• Click the Equipment home tile.

• Click Equipment Runtime in the side menu bar and click Equipment.
2. Select a piece of Equipment and click .
• If there is a State Machine List assigned, select a State Machine and click Set Status.
• If there is a State Machine NId assigned, click Set Status.
4. Set a new status.
5. Click Save.
 If the Equipment has been created without any State Machine, neither the Set Status icon is
displayed in the Equipment page nor State Machines are displayed in the State Machine tab.
3.3.4.2 Modifying Equipment Property Values

You can modify Equipment property values.
Prerequisite
The property must have been configured with the Runtime Editing option selected.
Procedure
1. In the Equipment page, select the piece of Equipment whose Property value you want to modify and click .
2. Click the Properties tab and select a property having the Runtime Editing option set.
3. Click .
4. Modify the Property value.
5. Click Save.

Manufacturing Apps
Label App
3.3.4.3 Modifying Attributes of Equipment Properties

You can modify the attribute values of Equipment properties.
Prerequisite
The attribute must have been configured with the Runtime Editing option selected.
Procedure
1. In the Equipment page, select the piece of Equipment whose property attribute you want to modify and click
.
2. Click the Properties tab and select the property.
3. Click .
4. Click the Attributes tab.
5. Select an attribute having the Runtime Editing option set.
6. Click .
7. Modify the attribute value and click Save.
3.3.4.4 Manually Synchronizing Engineering and Runtime Environments

When you create or modify any Equipment Configurations, Groups, Flows and Hierarchies in the engineering
environment, the system automatically creates or modifies corresponding Equipment instances in the runtime
environment. This alignment is based on a system event, the CommittedEvent (for more information on the
CommittedEvent, see Handling the CommittedEvent in the in the Opcenter Execution Foundation Development and
But if you import Equipment Configurations, Groups, Flows and Hierarchies to the engineering environment (e.g.
via BulkImport API or DBinit.xml configuration file or import functionality) you must perform a manual
synchronization. The manual synchronization is also required if you notice a misalignment in the Equipment data
model between the engineering environment and the runtime environment.
In all these cases, the system cannot perform an automatic synchronization.
Procedure
1. Open one of the following pages:
• Equipment Configurations (see How to Define Equipment Configurations)
• Equipment Configuration Groups (see How to Define Equipment Group Configurations)
• Equipment Hierarchy Configurations (see How to Define Connections among Equipment Items)
• Equipment Configuration Flows (see How to Define the Physical Model of the Plant)
2. Click .
3. Select Overwrite value on runtime properties if you want to overwrite runtime values with the master data
values (e.g. the imported values).
4. Click Execute.
3.4 Label App

The Label App provides Label Management functionalities,
• LBM_MS
• LBM_OP

Manufacturing Apps
Label App
• UDM_RF
What can I do in the Label App?

• What is Label Management? provides useful conceptual information.
• How to Configure Label Types describes the configurations required to properly configure labels.
• How to Raise Print Requests describes the necessary binding configurations between the Label App and
the Signal App in order to raise requests.
• How to Retrigger Print Requests describes how to view the Print History and perform a Reprint action.
3.4.1 What is Label Management?

Labels accompany manufactured end-products, and provide information about them, displayed in a custom layout.
The Label App provides Label Management functionalities that allow you to print labels during the execution of
manufacturing processes. Based on the provided configuration, a label is printed on the required printer, at a
certain time in the production (for example, after a value change), along with a set of data whose actual values are
directly updated at runtime during the printing process.
Concepts
The configuration data of the Label Management is stored by means of the following data model entities:
• Label Types are the containers of all the configurations required to retrieve manufacturing data and display it in
a predefined print format and layout.
• Label Tags are the placeholders to be filled at runtime with actual values.
• Label Templates are the source files in the specific Printer format; they define the final graphical layout and
specify at runtime where the actual values of the tags have to be displayed and printed.
• Label Printers contain the details on the print output destination.
The Label Management data structure can be graphically represented as follows:
3.4.2 How to Configure Label Printing

Here you can find a general overview of the main steps you have to take before you can correctly print out the
desired Label with the correct runtime data.
Below you can find the navigation links to the required procedures.
Preliminary operations
On each machine where Opcenter Execution Foundationis installed verify the following prerequisites:

Manufacturing Apps
Label App
• Install Microsoft .NET Core Windows Hosting Bundle version 3.1.15. This software, which is a prerequisite for the
Label Printing Microservice, can be downloaded from https://dotnet.microsoft.com/download/dotnet-core/
3.1 (in the page, find the first ASP.NET Core Runtime 3.1.15 section, click the Hosting Bundle link in the
Windows row).
• After you have installed Opcenter Execution Foundation, verify that the Label Printing Microservice is running in
IIS by browsing the page: http://localhost/sit-svc/labelPrinting/swagger/v2/swagger.json
If the Label Printing Microservice is properly running the page must show a json file.
The Manufacturing Solution must contain both the Label App and the Signal App.
Workflow
1. Configure the label print layout.
2. Configure Label Types.
3. Configure printers.
4. Raise print requests.
3.4.2.1 How to Configure the Label Print Layout

In order to correctly print Labels, you need a label layout design, which must be created with third-party tools and
proprietary languages, depending on printers in use.
After configuring the layout, you must export it to a file.
The label layout design file must contain the layout you want to print out and the variables that will be replaced at
runtime with the correct data, retrieved from the manufacturing runtime operations. These variables must be
identified by a begin and an end delimiter, and the values will be provided later on before printing the label.
The label layout design file will be attached to the Label configuration by means of the Label Template object.

Manufacturing Apps
Label App
Bear in mind that variables defined in the layout file must match exactly the Label Tags you will define later on in
the Label Type object and the encoding used to generate the design file must match the encoding you will specify in
the Label Template (as described further on in the Label app configuration procedures).
 End-users must configure their own label layout design by applying their own tools and processes.
Therefore, the related instructions are not within the scope of this documentation.
3.4.2.2 How to Configure Label Types

To configure a label you must configure Label Types and associate them to Label Tags and and Label Templates.
Label Tags represent variables that will be dynamically replaced at runtime with the actual values to be printed.
Label Templates represent the print format and layout.
The Label Tags can later be mapped to entities and attributes of other Manufacturing Apps (as explained in the
section Configuring Signal Rules with Print Label Action).
Workflow
1. Create Label Types.
2. Create and associate Label Tags to the selected Label Type.
3. Create and associate Label Templates to the selected Label Type.
3.4.2.2.1 Creating Label Types

The Label App provides a Label Types screen where you can create, edit, copy, freeze/unfreeze and delete Label
Types.
Label Types are defined by Id, Name and Description and are made up of Label Tags and Label Templates. By
means of Label Tags the system knows which manufacturing data must be printed and by means of Label
Templates, the system knows how the label must be printed in terms of design and layout.
Procedure
1. Do either of the following to open the Label Types page:
• Click the Label Types home tile.

• Click Label Management in the side menu bar and click Label Types.
2. Click .
Id The unique identifier assigned to the Label Type. Once the Label Type is created,
the Id value cannot be modified. The Id can contain only lower and uppercase letters,
digits, and underscore. The first character of the Id cannot be a digit.
Name The name assigned to the Label Type.
Description Additional information on the Label Type.

4. Click Save. The new Label Type is created and added to the list of existing Label Types.

Manufacturing Apps
Label App
Available operations on Label Types

On the existing Label Types you can then perform the following operations, by selecting the Label Type and clicking
the proper icon in the Label Types screen.
Open It allows you to access the details of the selected Label Type, in order to associate Label
Tags and Label Templates.
Edit Allows you to modify Name, and/or Description of a Label Type.
Copy Allows you to copy a selected Label Type, and create a duplicate with all Label Tags and
Label Templates associated to the original.
The Copy side panel opens. The panel is pre-filled with all Attributes of the original Label
Type, except the Id.
Enter a new Id and update any other editable fields as needed, then save.
Freeze Allows you to freeze/unfreeze the Label Type.

After the freeze operation:
Unfreeze
• the Is Frozen property checkbox is displayed checked
• the Label Type is not editable
• the frozen status is propagated to the child entities: Label Tags and Label Templates
cannot be added, nor modified
• Label Printer associations cannot be managed for a Label Template on a frozen Label
Type
• the frozen Label Type can still be copied using the icon; the new Label Type
resulting from the Copy operation will not be frozen
After the unfreeze operation:
• the Is Frozen property checkbox is displayed unchecked
• the Label Type is editable again
• the unfrozen status is propagated to the child entities: Label Tags and Label
Templates can be added and modified again
Delete Allows you to permanently remove a Label Type. A confirmation message prompts you to
confirm or cancel your action.
All Label Tags and Label Templates linked to the deleted Label Type are also deleted from
the system.
Label Printers linked to the deleted Label Type are not deleted from the system.
Segregation Allows you to add Data Segregation tags to limit data access of users. See What is Data
Tags Segregation?
To view this icon, the Data Segregation must be enabled and properly configured.

Manufacturing Apps
Label App
Allows you to export selected entities and instances in an export package that can be
Export
downloaded locally and imported afterwards. See How to Export and Import Data for
information about data exchange and Exporting and Importing Label Type and Printer
Data for further information on the import sequence of Label data.
Audit Trail of a Label Type
To display the Audit Trail of a Label Type, select the Label Type and then navigate to the Audit Trail tab.
The Audit Trail tab shows the list of all changes performed on the selected Label Type and its child entities (Label
Tags, Label Templates, and the Label Printers associated to the Label Templates).
3.4.2.2.2 Creating and Associating Label Tags

The Label App provides a Label Tags screen where you can create, edit, and delete Label Tags.
Label Tags are defined by Id, Variable Name, Type, Default Value, and Format, and they specify what information
is printed on the label.
A Label Type can have more Label Tags. These will be used at runtime to provide the correct values to be inserted
into the Label Template when printing a given Label Type.
Label Tags include a default value. The default value is useful when a system integrator needs to directly invoke the
LabelPrint command (not via Signal Rule) and does not provide any tags. In this case, the
LabelPrint command logic retrieves and applies the default value of the tag. For more information, refer to
the PrintLabelAndAddPrintHistory command explained at How to Raise Print Request.
Procedure

2. Select the Label Type for which you want to create a Label Tag and click .
3. In the Label Tags tab, click .
Id The identifier assigned to the Label Tag, unique under a Label Type. Once the Label Tag is
created, the Id value cannot be modified. The Id can contain only lower and uppercase
letters, digits, and underscore. The first character of the Id cannot be a digit.

Manufacturing Apps
Label App
Variable Name The key used for the substitution logic in the source file. This must correspond to the
name of the tag contained in the source file and it is case sensitive. The Variable Name
can contain only lower and uppercase letters, digits, and underscore. The first character
of the Variable Name cannot be a digit.
No check is performed to see whether the placeholders present in the uploaded source
file actually match the Variable Names specified.
It is up to the user to define all tags present in the source file; otherwise errors will occur
at runtime.
 The Variable Name property cannot assume the following values:

• NumberOfCopies
• LabelTemplateId
• LabelPrinterId
These strings are reserved to the corresponding properties that are used in the
Transform Block of the Signal Rule. See Configuring Signal Rules with Print Label
Action
Type The list of possible value types. The following types are available:
• Bigint
• Bool
• Datetime
• Decimal
• Guid
• Int
• Smallint
• String
• Tinyint
Default Value The Tag default value. It is applied when a print request is raised and the runtime value is
null or empty.
Format The format of the value defined above. Enabled only for the following types:
• Datetime
• Decimal
This formatting pattern is applied when a print request is raised on the runtime value
related to this Label Tag, so that for each Tag the user can specify the desired final printed
formatting.
No validation is performed on the format pattern string the user types. For a list of
supported format patterns for DateTimes and Float data types follow the guidelines
presented here: https://docs.microsoft.com/en-us/dotnet/standard/base-types/
standard-date-and-time-format-strings.
5. Click Save. The new Label Tag is created and added to the list of existing Label Tags of the selected Label Type.
Available operation on Label Tags

Manufacturing Apps
Label App
On the existing Label Tags you can then perform the following operations, by selecting the Label Tag and clicking
the proper icon in the Label Tags tab.
Edit Allows you to modify the Variable Name, Type, Default Value, and/or Format of
a Label Tag.
Delete Allows you to permanently remove a Label Tag. A confirmation message prompts
you to confirm or cancel your action.
Segregation Tags Allows you to add Data Segregation tags to limit data access of users. See What is
Data Segregation?
To see this icon, Data Segregation must be enabled and properly configured.
Allows you to export selected entities and instances in an export package that
Export
can be downloaded locally and imported afterwards. See How to Export and
Import Data.
can be downloaded locally and imported afterwards. See How to Export and
Import Data for information about data exchange and Exporting and Importing
Label Type and Printer Data for further information on the import sequence of
Label data.
3.4.2.2.3 Creating and Associating Label Templates

The Label App provides a Label Templates screen where you can create, edit, and delete Label Templates.
Label Templates are defined by Id, Name, and Description, and they specify the format of data to be sent to a
printer for a given Label Type. Label Templates associate a Printer to the correct layout design and variables.
Label Templates include information used to format and retrieve the data when sending out the Print
Request: Source File, Encoding, Formatting Culture, Tag Begin Delimiter, and Tag End Delimiter.
By associating Label Templates to Label Types, the system can retrieve the predefined print format and layout of
the label that must be printed.
Multiple Label Templates can be associated to a Label Type. The system can then retrieve the correct template to
be used to print a given Label Type. This allows, for example, printing the same Label Type and its information in
different graphical sizes and layouts, or on printers from different manufacturers accepting source files in their own
printing language.
A default Label Template can be defined for each Label Type, to be used to print a label without the need to specify
a Label Template in the Print Request.
Label Printers are associated to Label Templates. This way the system can identify the printers on which a given
Label Type can be printed. A default Label Printer can be defined for each Label Template, to be used to print a
label without the need to specify a Label Printer in the Print Request.
Procedure

Manufacturing Apps
Label App

2. Select the Label Type for which you want to create a Label Template and click .
3. In the Label Templates tab, click .
Id The identifier assigned to the Label Template, unique under a Label Type. Once
the Label Template is created, the Id value cannot be modified. The Id can contain only
lower and uppercase letters, digits, and underscore. The first character of the Id cannot
be a digit.
Name The name assigned to the Label Template.
Description Additional information on the Label Template.
Source File The file containing the instructions to be sent to the printer, defined in terms of print
layout design and variables to be substituted with actual values.
The file must be only a text file (plain text, e.g. a file with extension .txt), and the file
format must be supported by the target printer.
 Rich Text Format (.rtf) files, Word Documents (.docx), Portable Document
Format (.pdf) files or other formats are not supported.
The variables, marked with begin and end delimiters (see How to Configure the Label
Print Layout) must match all the Label Tag Variable Names specified for the given Label
Type (see Creating and Associating Label Tags). These placeholders in the source file
will be replaced at runtime with actual values when printing a label.
 If the plain text file, which contains the instructions to be sent to the printer,
changes, you must update the Source File of the Label Template.
Encoding The encoding format that has been applied to the label print layout design file (such as
for example ASCII, UTF-8, UTF-16BE, UTF-16LE, ANSI, Unicode, Unicode Big Endian).
Formatting The culture that will be used when formatting all DateTime and Decimal tags belonging
Culture to the Label Template.
Begin Delimiter The character marking the beginning of the tag. This character must match the
characters that are present in the label print layout design file.
End Delimiter The character marking the end of the tag. This character must match the characters
that are present in the label print layout design file.
5. Click Save.
Available operations on Label Templates

Manufacturing Apps
Label App
On the existing Label Templates you can perform the following operations, by selecting the Label Template
and clicking the proper icon in the Label Templates tab.
Allows you to modify the Name, Description, Source File, Encoding, Begin
Edit
Delimiter and/or End Delimiter of a Label Template.
Allows you to set a Label Template to default. The first Label Template you create for a
Set Default
Label Type is automatically set as default. In the list of Label Templates associated to a
Label Type, the Is Default column specifies the current default Label Template. To
change the default Label Template, select the required Label Template from the list
and click Set Default.
Allows you to permanently remove a Label Template. A confirmation message prompts

Delete
you to confirm or cancel your action.
A Label Template cannot be deleted if it is set as default. Manually change the default
to another Label Template first, then perform the deletion.
Label Printers linked to the deleted Label Template are not deleted from the system.
Allows you to add Data Segregation tags to limit data access of users. See What is Data
Segregation
Segregation?
Tags
The icon is visible only if Data Segregation is enabled and properly configured.
Export
downloaded locally and imported afterwards. See How to Export and Import Data for
information about data exchange and Exporting and Importing Label Type and Printer
Data for further information on the import sequence of Label data.
3.4.2.3 How to Configure Printers

You must configure Printers in order to establish a connection between the Label Type data (Label Template) and
an actual printer (Printer).
Workflow
1. Create Printers.
2. Associate Printers to Label Templates.
3.4.2.3.1 Creating Printers

The Label App provides a Printers screen where you can create, edit, copy and delete Printers.
Printers are defined by Id, Name, Description, and Labeling System, which identity the print option of a
configured Printer.
Procedure
1. Do either of the following to open the Printers page:

Manufacturing Apps
Label App
• Click the Printers home tile.

• Click Label Management in the side menu bar and click Printers.
2. Click .
Id The unique identifier assigned to the Label Printer. Once the Label
Printer is created, the Id value cannot be modified.
Name The name assigned to the Label Printer.
Description Additional information on the Label Printer.
Labeling System To set the printing options, select one of the following:
• Event Only - to raise the LabelPrintRequested event - which
has all the print request information - so that it can be
managed by a custom procedure
• Printer - to perform the printing on a physical printer
• File - to print to a .txt file
The Print Event is always generated before creating the file or sending
the print request to the printer. This applies to the Printer and File
options as well.

Manufacturing Apps
Label App
Labeling System Information The information needed depends on the Labeling System you have
previously selected. To correctly configure a working Printer or File
output, you must enter the following information:
• In case of Printer Labeling System:
• if the printer is installed locally, the name of the
printer
• if the printer is accessible over a network, the
network address of the printer: \\{MyServerName}\\
{PhysicalPrinterName}
 How to retrieve the physical printer

name:
Go to Control Panel > Devices and
Printers, right-click the required
printer and select Printer properties. The
title of the just opened window or the
name in the General tab is the one that
you must use:
In this example the value to be entered

in Labeling System Information is: \
\172.23.193.159\ZDesigner GK420t
Please note that ZDesigner printer is an
example, it is not the only supported
printer.
The group SIT_UNIFIED_LOW must have writing

rights on the printer.
• In case of File Labeling System:

Manufacturing Apps
Label App
• the path to the destination folder of the file. The

group SIT_UNIFIED_LOW must have writing rights
on the printing folder.
When printing on file, the file is printed locally to the Worker
instance that executes the command.
4. Click Save. The new Printer is created and added to the list of existing Printers.
Available operations on Printers

On the existing Printers you can perform the following operations, by selecting the Label Printer and clicking the
proper icon in the Printers screen.
Edit Allows you to modify the Name, Description, Labeling System and/
or Labeling System Information of a Label Printer.
Copy Allows you to copy a selected Label Printer, and create a duplicate using
the existing information of the original.
The Copy side panel opens. The panel is pre-filled with all Attributes of the
original Label Printer, except the Id.
Enter a new Id and update any other editable fields as needed, then save.
Delete Allows you to permanently remove a Label Printer. A confirmation message

prompts you to confirm or cancel your action.
A warning message prompts you if the Label Printer is associated to one or
more Label Templates and thus cannot be deleted. For information about
Label Printer - Label Template associations, see the Creating and
Associating Label Templates section.
Segregation Tags Allows you to add Data Segregation tags to limit data access of users. See
What is Data Segregation?
For this, Data Segregation must be enabled and properly configured.
Allows you to export selected entities and instances in an export package

Export
that can be downloaded locally and imported afterwards. See How to
Export and Import Data. for information about data exchange and
Exporting and Importing Label Type and Printer Data for further
information on the import sequence of Printer data.
3.4.2.3.2 Associating Printers to Label Templates

To fulfill the Printer configuration, you must associate Printers to Label Templates.

Manufacturing Apps
Label App
Procedure

2. Select the Label Type whose Label Template you want to associate and click .
3. Click the Label Template tab.
4. Click the icon. The Printers side panel opens, displaying the list of Printers that are currently associated to
the selected Label Template, if any.
5. Click and select the Printer from the list.
6. Click Add.
Available operations on Printer associations

To add new Printer association.

Add
The first Printer you associate with a Label Template is automatically set as default. In the
Set Default
list of Printers associated with a Label Template, the Is Default column specifies the
current default Printer.
To change the default Label Printer, select a Label Printer from the list and click Set
Default.
If a Printer is set as default, it cannot be deassociated from the Label Template. Set another
Remove
Printer as default and then remove the required one.
3.4.2.4 How to Raise Print Requests

After you have defined the required Label Printers, Label Types, Label Tags, and Label Templates you can trigger a
print operation either via Signal Rules (configurative action) or via API (programmatic action)
You can trigger the print action in either of the following ways:
• Configuring Signal Rules with Print Label Action (configurative approach). This option makes use of Signal Rules
to trigger print requests on specific events, and to retrieve and feed the correct runtime values to the printer for
printing.
• Invoking the PrintLabelAndAddPrintHistory command from custom logic (programmatic approach). This
option is available to system integrators and developers implementing MES/MOM functionalities using Opcenter
EX FN. The PrintLabelAndAddPrintHistory is a composite command which belongs to the Application
Data Domain.
It invokes the AddPrintHistory command, which stores the Print Request information in a Label Print History
entity, and then it invokes the PrintLabel command, which initiates the Print Request.
The AddPrintHistory and PrintLabel are commands which belong to the Operational Data Domain.
Refer to the Commands section of the Label Reference Guide, and to the Commands section of the LBM_OP
Reference Guide.

Manufacturing Apps
Label App
Troubleshooting print operations

If you cannot print using Label App or you are experiencing issues related to it, the following information might help
you solving them.
Labelprinting Microservice Logs

If you are experiencing troubles in using Label App and Labelprinting microservice you can use the logs for
understanding where the issue actually is. There are two types of logs you can check:
1. Label App’s logs are available in the Trace Viewer tool as for other Opcenter EX FN applications (see Logging and
Analyzing Application Traces with Trace Viewer in the Opcenter Execution Foundation Development and
Configuration Guide);
2. Labelprinting Microservice logs: this component creates its logs in the folder C:\inetpub\logs (e.g.
LabelPrintingServices.log) only if the user impersonating the microservice (by default UnifiedLow) has enough
rights to access and create/modify files in the mentioned folder.
Check Certificate expiration date

If you configured Opcenter EX FN for using HTTPS protocol, you need to be sure that the certificate used in the
system is still valid. In case the certificate is not valid, the communication with Labelprinting microservice might not
work.
To check certificate validity, you can perform the following steps:
1. open in Internet Information Service (IIS) Manager, select the Default Web Site and select Bindings in the
right panel
2. In the Bindings window, select the https row and select Edit
3. In Edit Site Binding window, select View in SSL Certificate area and check the expiration date of the
certificate. The certificate must be valid for working correctly in HTTPS protocol environment and allow correct
communication between Opcenter EX FN and Labelprinting microservice.
3.4.2.4.1 Configuring Signal Rules with Print Label Action

In order to trigger a print operation using the available manufacturing data, bindings must be configured between
the Label App and the Signal App.
 For such configurations, previous understanding of Signal App workflows is needed. Follow the
instructions presented in the Signal App documentation. See Creating Signal Rules and Configuring Signal
Rules.
The Signal App is used to create bindings between Opcenter EX FN data and print action input fields.
Once the Label App is deployed, it becomes possible for the user to configure a Signal Rule with a new specific type
of Action: the Print Label Action.
In this case, the Signal Rule trigger source is the runtime data linked to Label Tags, and the triggered action is a
Print Label Action.
Signal Rules are configured to start a Print Label Action by subscribing to any of the available Signal Rule sources.
Binding of Label Tags to actual values at runtime is configured inside the Signal Rule, allowing to retrieve runtime
data from the source. This also permits combining the source data with additional data retrieved via the Query
Block capabilities of the Signal App.

Manufacturing Apps
Label App
It is also possible to choose the Label Printer at runtime by configuring it within the Transform Block of a Signal
Rule; this overrules the Label Printer set at engineering time. If no such configuration is in place, the Signal Rule will
use the Label Printer configured at engineering time.
After the Print Label Action is invoked, a print event is always generated with all the print info payload (refer to the
LabelPrintRequested section of the LBM_OP Reference Guide). Then, depending on the printer used and its
configuration, a file may be generated, or a request may be sent to an actual printer. It is also possible to stop the
flow at event fire, without printing out the label. If the printer used is of type 'Event Only', then only the print event
is raised and no file is created, nor any physical label is printed.
The event can be used inside event subscriptions as well, in order to trigger business logic either from custom
event handlers or from external applications.
Procedure
When configuring Signal Rules of this type, you must perform the following:
1. Set the Action Type to Print Label Action.
2. For the Print Label Action, specify the Number of Copies to be printed, as well as the Label Type and an
associated Label Template and Label Printer. After the Label Type is specified, the associated Label Tags are
also displayed.
Note that it is not mandatory to specify a Label Template and/or Label Printer. If these fields are left empty,
the default ones are used by the system.
These entities are created in and retrieved from the Label App.
3. If needed, configure queries and combine them with the source in the Combine Block.
4. Configure the binding in the Transform Block: each Label Tag must be bound to a runtime value of the same
data type coming from the source or from the Query Blocks, if present.
5. Optional configurations:
Configure the Number of Copies in the Transform Block: associate the NumberOfCopies property to a
runtime value coming from the source OR enter a numeric runtime value for the
NumberOfCopies property, which represents the number of copies to be printed during this single Print
Request.
When the Signal Rule is triggered, the actual value representing the Number of Copies is chosen based on
availability, in the following priority order:
• the Number of Copies configured at runtime in the Transform Block of a Signal Rule - if available, or else
• the Number of Copies configured at engineering time in the Print Label Action Block in the Signal Rule - if
valid, or else
• the default Number of Copies, which is always 1
 In case the Number of Copies configured at runtime in the Transform Block or at engineering
time in the Print Label Action Block is not a valid numeric value, then the default Number of
Copies is used, which is always 1.
Configure the Label Template in the Transform Block: associate the LabelTemplateId property to a
runtime value coming from the source, representing the required template information (its unique
identifier) - this template information must be configured on the source, and it must correspond to a
valid Label Template created in the Label App.
When the Signal Rule is triggered, the actual Label Template which will be used is chosen based on
• the Label Template configured at runtime in the Transform Block of a Signal Rule - if available, or else
• the Label Template configured at engineering time in the Print Label Action Block in the Signal Rule - if
available, or else
• the Label Template set as default on the Label Type - always available

Manufacturing Apps
Label App
 In case the Label Template configured at runtime does not correspond to a valid Label
Template created in the Label App, then the Label Template set as default on the Label Type is
used.
Configure the Label Printer in the Transform Block: associate the LabelPrinterId property to a runtime
value coming from the source, representing the required printer information (its unique identifier) - this
printer information must be configured on the source, and it must correspond to a valid Label Printer
created in the Label App.
When the Signal Rule is triggered, the actual Label Printer which will be used is chosen based on
• the Label Printer configured at runtime in the Transform Block of a Signal Rule - if available, or else
• the Label Printer configured at engineering time in the Print Label Action Block in the Signal Rule - if
available, or else
• the Label Printer set as default within the Label Template > Label Type association - always available
 In case the Label Printer configured at runtime does not correspond to a valid Label Printer
created in the Label App, then the Label Printer set as default within the Label Template is
used.
3.4.3 How to Retrigger Print Requests

All Print Request information is saved and can be reused for reprinting purposes.
A reprint is useful for retriggering a failed Print Request or replacing a damaged label, for example.
Whenever the print command is invoked, all Print Request data sent to the printer is logged into a Print History
entity. This includes all metadata of the Label Type, Label Template and Label Printer at the moment of the
execution of the print command, as well as the runtime values of the Label Tags, so that if the Reprint command is
executed, the same metadata is used.
Available operations on print history

• Viewing the Print History
• Viewing Print History Details
• Reprinting labels
• Using the ReprintLabelsAndAddPrintHistory command
Viewing the Print History

1. Do either of the following to open the Print History page:
• Click the Print History home tile.

• Click Label Management in the side menu bar and click Print History.
2. The following attributes are shown for each Print Request:
Timestamp Date and time information reflecting the moment the Print History entity was
recorded.

Manufacturing Apps
Label App
Label Type Id of the Label Type used in the Print Request.
Label Template Id of the Label Template used in the Print Request.
Printer Id of the Label Printer used in the Print Request.
State Stores whether the Print Request was successful or not.
Reason Stores the reason for the Reprint.
Is a Reprint The checkbox is checked if the recorded Print History event represents a Print
Request executed as a result of a Reprint action.
Print Id The unique identifier of the Print History entity. The Id value cannot be modified.
Is Reprint of Stores the Print Id of the Print History entity for which the Reprint action was
triggered.
Initiated By Stores the name of the user who initiated the Reprint action.
Viewing Print History Details

1. In the Print History page, select the Print History entity whose details you need.
2. Click the Print History Details button.
3. On the Details side menu, the following Print History information is displayed for consulting in read-only mode:
• Label Type
• Label Template
• Label Printer
• Request
• Label Tags
4. Expand each of the above to view its details.
Reprinting Labels
1. On the Print History page, select the Print History entity you want to reprint.
2. Click Reprint Labels.
3. On the Reprint side menu, reconfigure runtime values as needed:
• Enter the Number of Copies to be printed.
• Specify the Printer to be used for the Reprint action.
• Optionally, enter a Reason for executing the Reprint action.
4. Click OK to execute the Reprint action.
The Reprint action will use the Print Request data stored in the Print History (Label Template, Label Printer, Label
Tag values), as well as the previous configuration data, to trigger a new Print Request.
Whenever a Reprint is invoked, the reprint command is executed, and a new Print History entity is recorded. The
user triggering the Reprint action is also traced.

Manufacturing Apps
Label App
Using the ReprintLabelsAndAddPrintHistory command

The ReprintLabelsAndAddPrintHistory is a composite command which belongs to the Application Data Domain.
It invokes the AddReprintHistory command, which stores the Print Request information in a Label Print History
entity, and then it invokes the ReprintLabels command, which initiates the Print Request based on the Label Print
History entity selected for reprint.
The AddReprintHistory and ReprintLabels are commands which belong to the Operational Data Domain.
Refer to the Commands section of the Label Reference Guide, and to the Commands section of the LBM_OP
Reference Guide.
3.4.4 Exporting and Importing Label Type and Printer Data

The Label App allows you to export and import its own master data entities. Unlike the Export operation, the
section.

Example: If you want to import Label Type and Printer entities, and the Label Type entities were exported
selecting Include Descendants = False with no Printers associated to Label Templates, you must first import the
Label Type package and then the Printer one.
 Note that Label Types are parent entities and their Label Templates and Label Tags are automatically
exported.
Label Printers Notes

Types
Label If Label Types are exported by setting Include Descendants to

Types & True and all Printers are associated to Label Templates
Printers
Label • If Label Types are exported by setting Include

Types & Descendants to True and not all Printers are associated to
Label Templates
Printers
Or
• If Label Types are exported by setting Include
Descendants to False and no Printers are associated to
Label Templates
Printers Only if Printers are not associated to Label Templates
Label Only if Label Templates do not have association with Printers

Types

Manufacturing Apps
Material App
3.5 Material App

The Material App provides pages where it is possible to manage engineering and runtime materials.
• MAT_MS
• MAT_OP
• UDM_RF
• EQU_MS
• EQU_OP
What can I do with the Material App?

• Useful conceptual information is provided in What is Material Management? and What are Material App
Properties?.
• The configuration workflow and procedures are described in How to Manage Engineering Materials and How to
Manage Runtime Materials.
• Information on MAT_MS and MAT_OP Functional Blocks referenced by the Material App is provided in MAT_MS
Functional Block and MAT_OP Functional Block in the Opcenter Execution Foundation Development and
3.5.1 What is Material Management?

The Material App makes it possible to manage both engineering and runtime material related entities: from the
definition of Material Group, Material Template and Material to the operational entities as Material Lot, Material
Tracking Unit and Material Tracking Unit Aggregate.
Main entities as Material, Material Lot and Material Tracking Unit can be created either from scratch or starting from
a predefined template. The second way allows you to save time when configuring common properties that are
shared among all the materials with the same characteristics. Materials can be logically grouped through the
definition of a set of Material Group (hierarchical structure).
Once the material engineering phase is completed, you can create operational entities for the runtime material
operation either from scratch or from a template, as:
• Material Lot, representing a logical grouping of homogeneous material quantity.
• Material Tracking Unit, representing a specific quantity of material which manufacturing operations (increase or
decrease quantity, change status, change location) are applied to.
• Material Tracking Unit Aggregate, representing a grouping of non-homogeneous material quantity that requires
to be modeled.
3.5.2 What are Material App Properties?

Properties are custom information that allow you to extend the information of an entity, or a series of entities which
share common data.
Most entities are created from a template, and Properties can be added to these templates during their creation.
When entities are subsequently created from these templates, they inherit the defined Properties. Properties data
type and values can be modified at entity level.

Manufacturing Apps
Material App
The following entities are created from templates and therefore can have Properties:
• Material
• Material Lot
• Material Tracking Unit
• Material Tracking Unit Aggregate.
Property Attributes
When creating Properties you can set the following attributes:
Id The unique identifier assigned to the Property. Once the Property is created, the Id value
cannot be modified.
Type The type of the Property. For the possible types, see Property Types and Values.
UoM The Unit of Measure. This field is mandatory when the selected Type is Quantity.
Value (Optional) The Property value. For the possible values, see Property Types and Values.
If you have assigned Data Segregation tags to an entity, they are shown in the Property page for the selected entity.
Property Types and Values

Data Type Property Type Example values and format
Bigint 5 • from -2^53 (i.e. -9,007,199,254,740,992)

• to (2^53)-1 (i.e. 9,007,199,254,740,991)
Bool 7 true/false
Datetime 8 'yyyy'-'MM'-'dd' 'HH':'mm':'ss', for example

2017-12-25 12:00:00
Decimal 6 Double precision floating point according to IEEE

754-2008 standards.
Guid 9 example: ([a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})
Int 4 • from -2^31 (i.e. -2,147,483,648)

• to (2^31) -1 (i.e. 2,147,483,647)
Quantity 11 Double precision floating point according to IEEE

754-2008 standards.
Smallint 3 to (2^15)-1 (i.e. 32,767)
String 1 0 to 512 characters

Manufacturing Apps
Material App
Data Type Property Type Example values and format
Tinyint 2 0 to 255
Property Use Example

You can use Property to define some characteristics of a Material by creating a Material Template (e.g. Solid
Materials Inbound) and add some Properties such as StorageType with value BigBag, Quantity and Supplier
(with no value). Then you create the Material (e.g. Flour 00) using the Solid Materials Inbound template. The
Material inherits the defined Properties. In the Material Flour 00, you can modify the Property values as necessary.
3.5.3 How to Manage Engineering Materials

The Material App provides engineering pages, where you can manage Materials, together with their properties and
logical grouping.
Each Material can be created:
• from a specific Material Template
• from the default Material Template
• from scratch.
The templates for Material can have properties that are common typed information shared by all Materials created
from the same Material Template.
Materials, as well as Material Groups, can be associated into one or more Material Groups.
Workflow
1. Configure Material Templates.
2. If needed, configure Material Groups (used to logically group Materials).
3. Configure Materials and assign them to the Material Groups.
3.5.3.1 Configuring Material Templates

When creating Materials you can firstly define Material Templates in order to optionally specify a Unit of Measure
that will be set as reference Unit of Measure for the derived Material, and a set of common properties that will be
shared by all Material created from that Material Template.
You can set a Material Template as default and use it to create Materials, otherwise Materials can be created starting
from a specific one.
Material Template Properties allow you to extend the information of an entity (in this case the Material Template),
by defining additional properties, with an Id, a data type and an optional (default) value.
Any change performed on the Material Template is not applied to the already created Materials. Even if a Material
has been created specifying a reference Material Template and inheriting both properties and their data types and

Manufacturing Apps
Material App
values (if defined), Material Properties can be managed adding new ones, updating data type and values or deleting
them.
Workflow
1. Create a Material Template.
2. Add the required Properties to the Material Template.
Creating a Material Template

1. Do either of the following to open the Material Templates page:
• Click the Material Templates home tile.

• Click Material Engineering in the side menu bar and click Material Templates.
2. Click to add a new Material Template.
Id The unique identifier assigned to the Material Template. Once

the Material Template is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Material Template.
Description (Optional) Additional information on the Material Template.
Unit of Measure (Optional) The unit of measure (UoM) associated with the Material
Template. The UoM will be inherited by the Material but you can
modify it when creating the Material.
Set as Default If selected, sets the Material Template as default.

4. Click Save. The new Material Template is created.
 Once the first Material Template is created, the Material Template page is available by selecting the
Material Template and by clicking . Here
other Material Templates can be created from the Overview tab.
Adding a Property to a Material Template

1. In the Material Templates page, select a Material Template and click to open the Material Template page.
2. In the Properties tab, select the Material Template you want to add the Property.
3. Click .
4. Set the required Property attributes and click Save.
Available Operations on Material Templates

On the existing Material Templates you can then perform the following operations, by selecting the Material
Template and clicking the proper icon in the Material Templates page or in the Overview tab of the Material
Template page.

Manufacturing Apps
Material App
Edit Allows you to modify Name, Description and/or Unit of Measure of a Material
Template.
The Material Template must not be flagged as IsFrozen.
Freeze / The Freeze operation allows you to configure a Material Template as read-only, so that
Unfreeze it cannot be edited. When the Freeze operation is performed on a Material Template,
the Material Template is flagged as IsFrozen.
Set / Unset as Allows you to set the selected Material Template as default.
Default You can remove this setting by performing the Unset operation.
Delete Allows you to permanently remove a Material Template.
Export
See How To Export and Import Data for information about runtime data exchange
and Exporting and Importing Material Data for further information on the import
sequence of Material data.
Available Operations on Material Template Properties

On the existing Material Template Properties you can then perform the following operations, by selecting the
Property and clicking the proper icon in the Properties tab.
Edit To modify an existing Property data type and/or value.
Delete To delete an existing Property.
3.5.3.2 Configuring Material Groups

A Material Group can be used to group other Material Groups and Materials.
After creating a Material Group, you can:
• Join the current Material Group (as sub-group) to other Material Groups. For example, if the current Material
Group is LiquidMaterial, you can group it under the RawMaterial Material Group.
• Associate other Material Groups (as sub-groups) with the current Material Group. For example, if the current
Material Group is RowMaterial, you can group SolidMaterial and LiquidMaterial in the current Material Group.
• Associate the Material Group with one or more Material revisions. For example, RawMaterial Material Group can
group:
• Oxygen Rev A Material and SolidMaterial Material Group.

Manufacturing Apps
Material App
• Oxygen Rev A Material and LiquidMaterial Material Group.

• both Oxygen Rev A Material and SolidMaterial and LiquidMaterial Material Groups.
You cannot create closed-loop in the Material Group grouping. For example, If the RawMaterial Material Group
groups LiquidMaterial Material Group, which in turn groups AcidLiquid Material Group, AcidLiquid Material Group
cannot group RawMaterial Material Group.
Both a Material revision and a Material Group can be associated with more Material Groups at the same time.
Workflow
1. Create a Material Group.
2. Join the selected Material Group (as sub-group) to another Material Group.
3. Associate another Material Group (as sub-group) with the selected Material Group.
4. Associate a Material with the selected Material Group.
Creating a Material Group

1. Do either of the following to open the Material Groups page:
• Click the Material Groups home tile.

• Click Material Engineering in the side menu bar and click Material Groups.
2. Click to add a new Material Group.
Id The unique identifier assigned to the Material Group. Once

the Material Group is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Material Group.
Description (Optional) Additional information on the Material Group.

4. Click Save. The new Material Group is created.
 Once the first Material Group is created, the Material Group page is available by selecting the Material
Group and by clicking . Here other Material Groups can be created from the Overview tab.
Joining a Material Group with another Material Group

1. In the Material Groups page, select a Material Group and click to open the Material Group page.
2. In the Grouped In tab, select the Material Group you want to join with another Material Group.
3. Click .
4. Select the Material Group you want to join with the Material Group.
5. Click Save. The Material Group is grouped into the Material Group.
 You can remove the association of the Material Group with a Material Group by selecting the Material
Group to be disjoined in the Grouped In tab and clicking .
Associating a Material Group with another Material Group

Manufacturing Apps
Material App
2. In the Material Groups tab, select the Material Group you want to associate with another Material Group.
3. Click .
4. Select the Material Group you want to associate with the Material Group.
5. Click Save. The Material Group is associated with the other Material Group.
 You can remove the association of the Material Group with another Material Group by selecting the
Material Group in the Material Groups tab and clicking .
Associating a Material Group with a Material

2. In the Materials tab, select the Material Group you want to associate with a Material previously created.
3. Click .
4. Select the Material you want to associate with the Material Group.
5. Click Save. The Material Group is associated with the Material.
 • You can remove the association of the Material Group with the Material by selecting the Material Group
in the Materials tab and clicking .
• You can also associate a Material Group with a Material in the Materials page.
• You can access the associated Material in the Material page by selecting the Material and by clicking
.
Available Operations on Material Groups

On the existing Material Groups you can then perform the following operations, by selecting the Material
Group and clicking the proper icon in the Material Group page in the Overview tab.
Edit Allows you to modify Name and/or Description of a Material Group.

The Material Group must not be flagged as IsFrozen.
Freeze/ Unfreeze The Freeze operation allows you to configure a Material Group as read-only,
so that it cannot be edited. When the Freeze operation is applied to a Material
Group, the Material Group is flagged as IsFrozen.
You can remove the read-only setting by applying the Unfreeze operation.
Allows you to permanently remove a Material Group.

Delete
Export
can be downloaded locally and imported afterwards.
See How To Export and Import Data for information about runtime data
exchange and Exporting and Importing Material Data for further information
on the import sequence of Material data.

Manufacturing Apps
Material App
3.5.3.3 Configuring Materials

By means of Material entity you can model any kind of material that is used in your production processes. Typically
materials are represented in several revisions that could slightly differ from the others but remain valid in
production processes. In specific use cases, it is necessary to provide an additional unique identifier to distinguish
different instances of the same material revision.
Material can be created starting from a Material Template (a default one or a specific one) or starting from scratch.
In the first case, if the selected template provides a set of already defined properties, then these properties are
inherited in the new material revision. If the selected template has a predefined UoM, then this UoM will be
inherited as well.
In some circumstances, for example when more than one instance for each revision of the same material is defined,
you can optionally specify a unique identifier in order to identify a specific instance of material revisions among
other instances of the same material revision (example: oxygen, rev 1, UID 123; oxygen, rev 1 UID 456). If the value of
the unique identifier is left blank, then the system will automatically set the field with the NId-Revision pair.
Workflow
1. Create a Material.
2. Add a Property to a Material.
3. Associate a Material with a Material Group.
Creating a Material
1. Do either of the following to open the Materials page:
• Click the Materials home tile.
• Click Material Engineering in the side menu bar and click Materials.
2. Click to add a new Material.
Id The identifier assigned to the Material. Once the Material is created, the Id value
cannot be modified.
The Id value cannot contain the following special characters: & (ampersand), '
(quote), # (hashtag).
Revision The revision associated to the Material. Once the Material is created,
the Revision value cannot be modified.
Unique Identifier The identifier required to distinguish different instances of the same Material
revision.
If the value is left blank, then the system will automatically set the field with the
NId and Revision pair.
Name (Optional) The name assigned to the Material.
Description (Optional) Additional information on the Material.
Unit of Measure (Optional) The Unit of Measure of the Material.

Manufacturing Apps
Material App
Use Default Template Indicates that the Material will be created using the default Material Template.
Template (Optional) The Material Template to be used to create the Material.

4. Click Save. The new Material is created.
 Once the first Material is created, the Material page is available by selecting the Material and by clicking
. Here other Materials can be created from the Overview tab.
Adding a Property to a Material

1. In the Materials page, select a Material and click to open the Material page.
2. In the Properties tab, select the Material you want to add the Property.
3. Click .
Associating a Material with a Material Group

1. In the Materials page, select a Material and click to open the Material page.
2. In the Material Groups tab, select the Material you want to associate to a Material Group.
3. Click .
4. Select the Material Group you want to associate to the Material.
5. Click Save. The Material Group is associated to the Material.
 • You can remove the association of the Material to a Material Group by selecting the Material Group in
the Material Groups tab and clicking .
• You can also associate a Material Group with a Material in the Material Group page.
• You can access the associated Material Group in the Material Group page by selecting the Material
Group and by clicking .
Available Operations on Materials

On the existing Materials you can then perform the following operations, by selecting the Material and clicking the
proper icon in the Overview tab.
Add New Revision Allows you to create a new revision of the selected Material. The new revision will have
the same settings of the selected Material, but a new revision value.
Edit Allows you to modify Name, Description and/or UoM of a Material.

The Material must not be flagged as IsLocked.

Manufacturing Apps
Material App
Set Material as Allows you to set as Current the selected revision of a Material (Material revision
flagged as IsCurrent).
Current/ Unset
Material as Current You can remove the setting as Current from a Material revision by applying the Unset
Current operation.
Lock/ Unlock The Lock operation allows you to configure a revised material as read-only, so that it
cannot be edited or deleted. When the locking operation is applied to a material,
the material is flagged as IsLocked.
You can remove the read-only setting by applying the Unlock operation.
Copy Revision Allows you to create a copy of the selected Material.
Allows you to permanently remove a Material.

Delete
Export
See How To Export and Import Data for information about data exchange
and Exporting and Importing Material Data for further information on the import
sequence of Material data.
Available Operations on Material Properties

On the existing Material Properties you can then perform the following operations, by selecting the Property
and clicking the proper icon in the Properties tab.
To delete an existing Property.

Delete
3.5.3.4 Exporting and Importing Material Data

The Material App allows you to export and import its own master data entities. Unlike the Export operation, the
section.


Manufacturing Apps
Material App
Example: If you want to import Material Group and Material entities, and the Material Group entities were exported
selecting Include Descendants = False, you must first import the Material Group package and then the Material
one.
 Note that Material Groups are parent entities.
Material Material Material Template Notes

Group
Material Group If Material Group is exported by

& setting Include Descendants to
False
Material
Material Group If Material Group is exported by

& setting Include Descendants to
True.
Material
Note that only Material entities
that are associated to Material
Group entities are exported.
Material • If you export any Material, the

related properties are also
automatically exported.
• If the export package contains
Material entities associated to
Material Group entities, the
Material Group entities must
be already present in the
target environment, so that
referential integrity is
preserved.
Material If you export any Material

Template Template, the related properties
are also automatically exported.
Material Group If Material Groups are

hierarchically associated, export
the root entity by setting Include
Otherwise, if some parent Material
Groups are not included in the
export package, these entities
should be already present in the
target environment in order to
preserve referential integrity.

Manufacturing Apps
Material App
3.5.4 How to Manage Runtime Materials

The Material App provides runtime pages, where you can manage Material Lots, Material Tracking Units (MTU) and
Material Tracking Unit Aggregates (MTUA), together with their properties and their relationships.
A Material Lot represents a logical grouping of homogeneous material quantity, represented by n MTUs.
A MTU represents a specific quantity of material to which manufacturing operations (increase or decrease quantity,
change status, change location) are applied.
To track and move Materials to and from the production line or stock them somewhere in a warehouse, you can use
Material Tracking Units.
Both Material Lots and Material Tracking Units can be created from scratch or starting from a predefined template.
The second way allows you to save time when configuring common properties that are shared among all
the materials with the same characteristics.
Material Tracking Unit Aggregates represent a grouping of both homogeneous and non-homogeneous material
quantity that requires to be modeled.
Workflow
1. Configure Material Lot Templates.
2. Configure Material Lots.
3. If needed, configure Material Tracking Unit Templates.
4. If needed, configure Material Tracking Units (and associate them to Material Lots and Material Tracking Unit
Aggregates, if necessary).
5. If needed, configure Material Tracking Unit Aggregates Templates.
6. If needed, configure Material Tracking Unit Aggregates.
3.5.4.1 Configuring Material Lot Templates

You can create a predefined template that allows you to create a Material Lot. In this way, you save time when
configuring common properties that are shared among all the Material Lots with the same characteristics.
Workflow
1. Create a Material Lot Template.
2. Add the required Properties to the Material Lot Template.
Creating a Material Lot Template

1. Do either of the following to open the Material Lot Templates page:
• Click the Material Lot Templates home tile.

• Click Material Runtime in the side menu bar and click Material Lot Templates.
2. Click to add a new Material Lot Template.

Manufacturing Apps
Material App
Id The unique identifier assigned to the Material Lot Template. Once the Material Lot
Template is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Material Lot Template.
Description (Optional) Additional information on the Material Lot Template.
State Machine (Optional) The State Machine associated to the Material Lot Template. You need to
configure the State Machine in the Reference App.
Set as Default If selected, sets the Material Lot Template as default.

4. Click Save. The new Material Lot Template is created.
 Once the first Material Lot Template is created, the Material Lot Template page is available by selecting
the Material Lot Template and by clicking . Here
other Material Lot Templates can be created from the Overview tab.
Adding a Property to a Material Lot Template

1. In the Material Lot Templates page, select a Material Lot Template and click
to open the Material Lot Template page.
2. in the Properties tab, select the Material Lot Template you want to add the Property.
3. Click .
Available Operations on Material Lot Templates

On the existing Material Lot Templates you can then perform the following operations, by selecting the Material Lot
Template and clicking the proper icon in the Overview tab.
Edit Allows you to modify Name, Description and/or StateMachineNId of a Material Lot
Template.
The Material Lot Template must not be flagged as IsFrozen.
Set/ Unset as Allows you to set the selected Material Lot Template as default.
Default You can remove this setting by performing the Unset operation.
Freeze/ The Freeze operation allows you to configure a Material Lot Template as read-only, in
Unfreeze order that it cannot be edited. When the Freeze operation is performed on a Material Lot
Template, the Material Lot Template is flagged as IsFrozen.

Manufacturing Apps
Material App
Allows you to permanently remove a Material Lot Template.

Delete
Available Operations on Material Lot Template Properties

On the existing Material Lot Template Properties you can then perform the following operations, by selecting the

Delete
3.5.4.2 Configuring Material Lots

A Material Lot represents a logical grouping of a quantity of homogeneous material (i.e. the same material in the
same revision), modeled as one or more Material Tracking Units (MTUs). For example, you can use a Material Lot to
map the production of an homogeneous quantity of a finished material, by logically grouping several MTUs. These
MTUs can have different quantities or can be located in different physical entities (Equipment or Material Tracking
Unit Aggregate).
For the same reason, a Material Lot cannot be assigned neither to Equipment nor to MTU.
In addition, when creating a Material Lot you can enable it to group MTUs of the same Material with different
revision. This allows providing a more flexible logical grouping capability.
The following table can help you to clarify these concepts.
Cases Material Material Material Revisio Number of Storage Allowed /

Lot Tracking Unit n bottles Area Not allowed
Case 1 Material - Material Rev2 1500 -

Lot1 1
- MaterialTracking Material Rev2 200 StorageArea

Unit1 1 1

Lot1 1

Unit2 1 2

Lot1 1

Manufacturing Apps
Material App
Cases Material Material Material Revisio Number of Storage Allowed /

Lot Tracking Unit n bottles Area Not allowed

Unit3 1 2
Case 4 Material - Material Any 1000 -

Lot1 1

Unit1 1 1

Lot1 1

Unit2 1 2

Lot1 1

Unit3 1 2
You can assign a quantity to a Material Lot. This quantity can be freely set without having any direct reference to a
sum of quantity of the grouped MTUs because it only represents an information field, typically set at Enterprise
Resource Planning level.
When assigning a quantity to a Material Lot, the system will help you in setting the proper Unit of Measure,
according to the following criteria.
When creating a Material Lot, it is mandatory to select a Material. After selecting the Material you can:
• Select a specific revision. In this case:
• If the selected Material Revision has an assigned Unit of Measure, the quantity of the Material Lot can be
defined using the same Unit of Measure or a compatible one (multiple, sub-multiple or a Unit of Measure
for which a conversion factor has been defined).
• If the selected Material Revision has not an assigned Unit of Measure, the quantity of the Material Lot can
be defined using any Unit of Measure.
Otherwise, you can also select Current Revision because when creating a Material Lot the current revision is
resolved in a specific one.
• Select any Revision. In this case::
• If all revisions for the selected Material have a specified Unit of Measure, you can specify any Unit of
Measure which is compatible (multiple, sub-multiple or a Unit of Measure for which a conversion factor
has been defined) with the Unit of Measure of any revision.
• If at least one revision has not a defined Unit of Measure, the quantity of the Material Lot can be defined
using any Unit of Measure.
Finally, you can create a Material Lot either from scratch or starting from a predefined template. In the second case,
you can choose to use either a specific template or the default one (only if a default template is set).
Workflow
1. Create a Material Lot.
2. Add the required Properties to the Material Lot.

Manufacturing Apps
Material App
3. Add a Material Tracking Unit to a Material Lot.
Creating a Material Lot

1. Do either of the following to open the Material Lots page:
• Click the Material Lots home tile.
• Click Material Runtime in the side menu bar and click Material Lots.
2. Click to add a new Material Lot.
Autogenerate Id If selected, the unique identifier of the Material Lot to be added

will be autogenerated using the Numbering Pattern defined for
Material Lot Id. You need to configure Numbering Pattern in the
Reference App.
Id The unique identifier assigned to the Material Lot. Once

the Material Lot is created, the Id value cannot be modified. If you
have selected Autogenerate Id, this field will be disabled.
Autogenerate Name If selected, the name of the Material Lot to be added will be
autogenerated using the Numbering Pattern defined for Material
Lot Name. If you are modifying an existing Material Lot, you can
automatically generate (or re-generate) the Material Lot Name by
selecting this check box (see Edit Material Lot operation in
Available Operations on Material Lots). You need to
configure Numbering Pattern in the Reference App.
Name (Optional) The name assigned to the Material Lot. If you have
selected Autogenerate Name, this field will be disabled.
Description (Optional) Additional information on the Material Lot.
Material Id The Material associated with the Material Lot.
Use Current Revision The field is read-only and the shown value is based on the Material
revision you have previously selected.
Use Any Revision If selected, the association will always link the Material Lot to the
revision which is current at that moment of time. If you have
selected a Material in a current revision, this field is disabled.
Material Revision (Optional) The Material revision associated with the Material Lot. If
you have selected Use Current Revision or Use Any Revision, this
field will be disabled.
Material Unique Identifier (Optional) This field is already selected when a specific Material
revision is chosen and only one a Unique identifier exists;
otherwise, one Unique identifier must be selected in the list of the
available ones. If you have selected Use Current Revision or Use
Any Revision, this field will be disabled.

Manufacturing Apps
Material App
Use Default Material Lot Template If selected, the Material Lot will be created using the default
Material Lot Template.
Material Lot Template (Optional) The Material Lot Template to be used for the creation of
the Material Lot. If you have selected Use Default Material Lot
Template, this field will be disabled.
State Machine (Optional) The State Machine associated with the Material Lot. If a
State Machine is selected, it overrides the one potentially defined
in the chosen Material Lot Template. You need to configure the
State Machine in the Reference App.
Unit of Measure (Optional) The Unit of Measure associated with the Planned
Quantity Material Lot.
Planned Quantity (Optional) The planned quantity of the Material Lot. This value
is optional unless Unit of Measure is specified. In this case,
Planned Quantity becomes mandatory.
4. Click Save. The new Material Lot is created.
 Once the first Material Lot is created, the Material Lot page is available by selecting the Material Lot and
by clicking . Here other Material Lots can be created from the Overview tab.
Adding a Property to a Material Lot

1. In the Material Lots page, select a Material Lot and click to open the Material Lot page.
Adding a Material Tracking Unit to a Material Lot

1. In the Material Lots page, select a Material Lot and click to open the Material Lot page.
2. In the Material Tracking Units tab, click .
3. Set the required attributes and click Save. See Configuring Material Tracking Units.
 You can access the associated Material Tracking Unit in the Material Tracking Unit page by selecting
the Material Tracking Unit and by clicking .
Available Operations on Material Lots

On the existing Material Lots, you can then perform the following operations, by selecting the Material
Lot and clicking the proper icon in the Overview tab.

Manufacturing Apps
Material App
Edit Allows you to modify Name and Description.

If you want to apply the Numbering Pattern to the Name property, you must select the
Autogenerated Name check box (regardless of whether you have already used it or not). If the
Numbering Pattern has been modified or if it contains parts that may change (such as a
counter or a timestamp), the Name property will be modified.
The Material Lot must not be flagged as IsFrozen.
Freeze/ The Freeze operation allows you to configure a Material Lot as read-only, so that it cannot be
edited. When the Freeze operation is applied to a Material Lot, the Material Lot is
Unfreeze
You can remove the read-only setting by applying the unfreeze operation.
Allows you to set a State Machine associated with the Material Lot.
Set
State This operation can be performed only if a State Machine is not already associated, otherwise
Machine the icon is not displayed.
Allows you to set a Status associated with the Material Lot.

Set
Status This operation can be performed only if a State Machine is already associated, otherwise the
icon is not displayed.
Allows you to set a Material associated with the Material Lot. You must set the required
Set attributes:
Material
• New Material (mandatory)
• Use Any Revision
• New Material Revision
• New Material Unique Identifier
For the attribute details, see Creating a Material Lot.
Allows you to set a Quantity associated with the Material Lot.

Set
Quantity
Delete Allows you to permanently remove a Material Lot.
Available Operations on Material Lot Properties

On the existing Material Lot Properties you can then perform the following operations, by selecting the Property
and clicking the proper icon in the Properties tab.

Manufacturing Apps
Material App
Available Operations on Material Tracking Units associated with Material Lots

On a Material Tracking Unit associated with a Material Lot, you can then perform the following operations, by
selecting the Material Lot and clicking the proper icon in the Material Tracking Units tab. For more details on the
operations, see Configuring Material Tracking Units.
Allows you to update a Material Tracking Unit associated with a Material Lot.
Edit
Disassociate Allows you to disassociate a Material Tracking Unit with the Material Lot.
Allows you to delete a Material Tracking Unit associated with a Material Lot.
Delete
3.5.4.3 Configuring Material Tracking Unit Templates

You can create a predefined template that allows you to create a Material Tracking Unit (MTU). In this way, you save
time when configuring common properties that are shared among all the MTUs with the same characteristics.
Workflow
1. Create a Material Tracking Unit Template.
2. Add the required Properties to the Material Tracking Unit Template.
Creating a Material Tracking Unit Template

1. Do either of the following to open the Material Tracking Unit Templates page:
• Click the Material Tracking Unit Templates home tile.

• Click Material Runtime in the side menu bar and click Material Tracking Unit Templates.
2. Click to add a new Material Tracking Unit Template.
Id The unique identifier assigned to the MTU Template. Once

the MTU Template is created, the Id value cannot be modified.
Name (Optional) The name assigned to the MTU Template.

Manufacturing Apps
Material App
Description (Optional) Additional information on the MTU Template.
State Machine (Optional) The State Machine associated to the MTU Template. You
need to configure the State Machine in the Reference App.
Set as Default (Optional) If selected, sets the MTU Template as default.

4. Click Save. The new MTU Template is created.
 Once the first Material Tracking Unit Template is created, the Material Tracking Unit Template page is
available by selecting the Material Tracking Unit Template and by clicking . Here
other Material Tracking Unit Templates can be created from the Overview tab.
Adding a Property to a Material Tracking Unit Template

1. In the Material Tracking Unit Templates page, select a Material Tracking Unit Template and click
to open the Material Tracking Unit Template page.
2. in the Properties tab, select the Material Tracking Unit Template you want to add the Property.
3. Click .
Available Operations on Material Tracking Unit Templates

On the existing Material Tracking Unit Templates, you can then perform the following operations, by selecting the
Material Tracking Unit Template and clicking the proper icon in the Overview tab.
Edit Allows you to modify Name, Description and/or State Machine of a Material Tracking
Unit Template.
The Material Tracking Unit Template must not be flagged as IsFrozen.
Set/ Allows you to set the selected Material Tracking Unit Template as default.
Unset as Default You can remove this setting by performing the Unset operation.
Freeze/ The Freeze operation allows you to configure a Material Tracking Unit Template as read-
Unfreeze only, in order that it cannot be edited. When the Freeze operation is performed on a
Material Tracking Unit Template, the Material Tracking Unit Template is
Allows you to permanently remove a Material Tracking Unit Template.

Delete
Audit Trail of a Material Tracking Unit Template

Manufacturing Apps
Material App
To display the Audit Trail of a MTU Template, select the Template and then navigate to the Audit Trail tab.
The Audit Trail tab shows the list of all changes performed on the selected MTU Template.
3.5.4.4 Configuring Material Tracking Units

A Material Tracking Unit (MTU) represents a specific quantity of material to which manufacturing operations
(increase or decrease quantity, change status, change equipment, etc.) are applied. For example, you can use a
Material Tracking Unit to map how your material is managed along a production process.
Several Material Tracking Units can be logically grouped within the same Material Lot. This allows you, for example,
to define that a certain quantity of an incoming material is physically represented by one or more Material Tracking
Units. These MTUs could be physically located in different equipment in your plant (some in a warehouse area,
some in a quality laboratory and some stocked in tanks), assigned to different production phases (quality check,
stock, mixing), representing different quantities.
When creating a Material Tracking Unit, you have to specify where the physical quantity material to be mapped is
located: you can choose to assign the MTUs either to a piece of Equipment or to a Material Tracking Unit Aggregate.
You can assign a Material (revision) to a Material Tracking Unit. This setting is not mandatory, for example when you
want to instruct the system that a certain quantity of material exists in a piece of Equipment but you are not
interested to trace a specific material which could result in an intermediate phase of your production process.
Additionally, you can trace which kind of production the Material Tracking Unit represents: to model this
information, you can optionally use the Code Type field.
When assigning a quantity to a Material Tracking Unit, the system will help you in setting the proper Unit of
Measure, according to the following criteria:
• When creating a Material Tracking Unit and assigning it to a specific (or current) Material revision:
• If the selected Material Revision has an assigned Unit of Measure, the quantity of the Material Tracking
Unit can be defined using the same Unit of Measure or a compatible one (multiple, sub-multiple or a Unit
of Measure for which a conversion factor has been defined).
• If the selected Material Revision has not any assigned Unit of Measure, the quantity of the Material
Tracking Unit can be defined using any Unit of Measure.
• When creating a Material Tracking Unit without assigning any Material, the quantity of the Material Tracking
Unit can be defined using any Unit of Measure.
Finally, you can create a Material Tracking Unit either from scratch or starting from a predefined template. In the
second case, you can choose to use either a specific template or the default one (only if a default template is set).
Workflow
1. Create a Material Tracking Unit.
2. Add the required Properties to the Material Tracking Unit.
Creating a Material Tracking Units

1. Do either of the following to open the Material Tracking Units page:
• Click the Material Tracking Units home tile.

Manufacturing Apps
Material App
• Click Material Runtime in the side menu bar and click Material Tracking Units.
2. Click to create a Material Tracking Unit.
Autogenerate Id If selected, the unique identifier of the Material Tracking Unit to

be added will be autogenerated using the Numbering Pattern
defined for Material Tracking Unit Id. You need to
Id The unique identifier assigned to the Material Tracking Unit. Once

the Material Tracking Unit is created, the Id value cannot be
modified. If you have selected Autogenerate Id, this field will be
disabled.
Autogenerate Name If selected, the name of the Material Tracking Unit to be added
will be autogenerated using the Numbering Pattern defined for
Material Tracking Unit Name. If you are modifying an existing
Material Tracking Unit, you can automatically generate (or re-
generate) the Material Tracking Unit Name by selecting this check
box (see Edit Material Tracking Unit operation in Available
Operations on Material Tracking Units). You need to
Name (Optional) The name assigned to the Material Tracking Unit. If you
have selected Autogenerate Name, this field will be disabled.
Code Type (Optional) The type of Code assigned to the Material Tracking
Unit. The possible values are:
• BatchId: identifies a batch object
• SerialNumber: identifies an object that can be
serialized.
Code (Optional) The Batch Id or Serial Number assigned to the Material

Tracking Unit.
Description (Optional) Additional information on the Material Tracking Unit.
Material Id (Optional) The Material you want to associate with the Material
Tracking Unit. If you specify a Material, you can also specify the
Material Lot (but you cannot specify a Material Lot without
defining the Material). If you specify a Material, you must also
specify the Quantity.
Use Current Revision The field is read-only and the shown value is based on the
Material revision you have previously selected.
Material Revision (Optional) The Material revision associated with the Material
Tracking Unit. If you have selected Use Current Revision, this
field will be disabled.

Manufacturing Apps
Material App
otherwise, one Unique identifier must be selected in the list of
the available ones. If you have selected Use Current Revision,
this field will be disabled.
Unit of Measure (Optional) The Unit of Measure you want to associate with the
Material Tracking Unit. You can specify both UoM and Value
without specifying the Material.
Value (Optional) The Unit of Measure value. You can specify both Value
and UoM without specifying the Material.
This value is optional unless Unit of Measure is specified. In this
case, Value becomes mandatory.
Material Lot (Optional) The Material Lot you want to associate with the
Material Tracking Unit. If you have defined a Material, you can
specify the Material Lot.
Use Default Template If selected, the Material Tracking Unit will be created using the
default Material Tracking Unit Template.
Template (Optional) The Material Tracking Unit Template to be used for the
creation of the Material Tracking Unit. If you have selected Use
Default Material Tracking Unit Template, this field will be
disabled.
State Machine (Optional) The State Machine associated with the Material
Tracking Unit. If a State Machine is selected, it overrides the one
potentially defined in the chosen Material Tracking Unit
Template. You need to configure the State Machine in the
Reference App.
Equipment (Optional) The Equipment you want to associate with the

Material Tracking Unit. If you have selected Material Tracking
Unit Aggregate, this field will be disabled. You can either use the
predefined Equipment or configure the Equipment in the
Equipment App.
Material Tracking Unit Aggregate (Optional) The Material Tracking Unit Aggregate you want to
associate with the Material Tracking Unit. If you have selected
Equipment, this field will be disabled.
4. Click Save. The new Material Tracking Unit is created.
 Once the first Material Tracking Unit is created, the Material Tracking Unit page is available by selecting
the Material Tracking Unit and by clicking . Here other Material Tracking Units can be created from the Overview tab.

Manufacturing Apps
Material App
Adding a Property to a Material Tracking Units

1. In the Material Tracking Units page, select a Material Tracking Unit and click to open the Material
Tracking Unit page.
Available Operations on Material Tracking Units

On the existing Material Tracking Units, you can then perform the following operations, by selecting the Material
Tracking Unit and clicking the proper icon in the Overview tab.
Allows you to modify Name, Description, Code and Code Type.

Edit
If you want to apply the Numbering Pattern to the Name
property, you must select the Autogenerate Name check box
(regardless of whether you have already used it or not). If the
Numbering Pattern has been modified or if it contains parts that
may change (such as a counter or a timestamp), the Name
property will be modified.
The Material Tracking Unit must not be flagged as IsFrozen.
The Freeze operation allows you to configure a Material Tracking

Freeze/ Unfreeze
Unit as read-only, in order that it cannot be edited. When the
Freeze operation is applied to a Material Tracking Unit,
the Material Tracking Unit is flagged as IsFrozen.
You can remove the read-only setting by applying the Unfreeze
operation.
Allows you to set a State Machine associated with the Material

Set State Machine Tracking Unit.
This operation can be performed only if a State Machine is not
already associated, otherwise the icon is not displayed.
Allows you to set a Status associated with the Material Tracking

Set Status Unit.
This operation can be performed only if a State Machine is
Allows you to set a Material associated with the Material

Set Material Tracking Unit. You must set the required attributes:
• New Material Id (mandatory)
For the attribute details, see Creating a Material Tracking Unit.

Manufacturing Apps
Material App
Allows you to set a new Quantity associated with the Material

Set Quantity
Tracking Unit.
Allows you to associate/disassociate a Material Tracking Unit

Associate/ Disassociate Material with the Material Lot.
Lot
Allows you to modify the association of the Material Tracking

Move to a Material Tracking Unit
Unit with a Material Tracking Unit Aggregate.
Aggregate
Allows you to modify the association of the Material Tracking

Move to Equipment Unit with an item of equipment.
Allows you to permanently remove a Material Tracking Unit.

Delete
Available Operations on Material Tracking Unit Properties

On the existing Material Tracking Unit Properties you can then perform the following operations, by selecting the
To modify an existing Property data type and/or value.

Edit

Delete
3.5.4.5 Configuring Material Tracking Unit Aggregate Templates

You can create a predefined template that allows you to create a MTU Aggregate. In this way, you save time when
configuring common properties that are shared among all the MTU Aggregates with the same characteristics.
Workflow
1. Create a Material Tracking Unit Aggregate Template.
2. Add the required Properties to the Material Tracking Unit Aggregate Template.
Creating a Material Tracking Unit Aggregate Template

1. Do either of the following to open the Material Tracking Unit Aggregate Templates page:
• Click the Material Tracking Unit Aggregate Templates home tile.

• Click Material Runtime in the side menu bar and click Material Tracking Unit Aggregate
Templates.
2. Click to add a new Material Tracking Unit Aggregate Template.

Manufacturing Apps
Material App
Id The unique identifier assigned to the Material Tracking Unit Aggregate

Template. Once the Material Tracking Unit Aggregate Template is
Name (Optional) The name assigned to the Material Tracking Unit Aggregate
Template.
Description (Optional) Additional information on the Material Tracking

Unit Aggregate Template.
State Machine (Optional) The State Machine associated to the Material Tracking
Unit Aggregate Template. You need to configure the State Machine in
the Reference App.
Set as Default (Optional) If selected, sets the material lot template as default.
4. Click Save. The new Material Tracking Unit Aggregate Template is created.
 Once the first Material Tracking Unit Aggregate Template is created, the Material Tracking Unit
Aggregate Template page is available by selecting the Material Tracking Unit Aggregate Template and by
clicking . Here
other Material Tracking Unit Aggregate Templates can be created from the Overview tab.
Adding a Property to a Material Tracking Unit Aggregate Template

1. In the Material Tracking Unit Aggregates page, select a Material Tracking Unit AggregateTemplate and click
to open the Material Tracking Unit Aggregate Template page.
2. in the Properties tab, select the Material Tracking Unit AggregateTemplate you want to add the Property.
3. Click .
Available Operations on Material Tracking Unit Aggregate Templates

On the existing material tracking unit aggregate templates you can then perform the following operations, by
selecting the Material Tracking Unit Aggregate Template and clicking the proper icon in the Overview tab.
Edit Allows you to modify Name, Description and/or State Machine of a Material Tracking
Unit Aggregate Template.
The material tracking unit aggregate template must not be flagged as IsFrozen.
Set/ Unset Allows you to set the selected Material Tracking Unit Aggregate Template as default.
as Default You can remove this setting by performing the Unset operation.

Manufacturing Apps
Material App
Freeze/ The Freeze operation allows you to configure a Material Tracking Unit Aggregate
Unfreeze Template as read-only, in order that it cannot be edited. When the Freeze operation is
performed on a Material Tracking Unit Aggregate Template, Material Tracking Unit
Aggregate Template is flagged as IsFrozen.
Delete Allows you to permanently remove a Material Tracking Unit Aggregate Template.
Available Operations on Material Tracking Unit Aggregate Template Properties

On the existing Material Tracking Unit Aggregate Template Properties you can then perform the following
operations, by selecting the Property and clicking the proper icon in the Properties tab.
Audit Trail of a Material Tracking Unit Aggregate Template
To display the Audit Trail of a MTU Aggregate Template, select the Template and then navigate to the Audit Trail
tab.
The Audit Trail tab shows the list of all changes performed on the selected MTU Aggregate Template.
3.5.4.6 Configuring Material Tracking Unit Aggregates

Material Tracking Unit Aggregates represent a grouping of both homogeneous and non-homogeneous material
quantity that requires to be modeled.
They represent physical entities where MTUs can be located.
You can create a MTU Aggregate either from scratch or starting from a predefined template. In the second case, you
can choose to use either a specific template or the default one (only if a default template is set).
Workflow
1. Create a Material Tracking Unit Aggregate.
2. Add the required Properties to the Material Tracking Unit Aggregate.
3. Add a Material Tracking Unit to a Material Tracking Unit Aggregate.

Manufacturing Apps
Material App
Creating a Material Tracking Unit Aggregate

1. Do either of the following to open the Material Tracking Unit Aggregates page:
• Click the Material Tracking Unit Aggregates home tile.
• Click Material Runtime in the side menu bar and click Material Tracking Unit Aggregates.
2. Click to add a new Material Tracking Unit Aggregate.
Autogenerate Id If selected, the unique identifier of the Material Tracking Unit

Aggregate to be added will be autogenerated using the
Numbering Pattern defined for Material Tracking Unit Aggregate
Id. You need to configure Numbering Pattern in the Reference
App.
Id The unique identifier assigned to the Material Tracking Unit

Aggregate. Once the Material Tracking Unit Aggregate is created,
the Id value cannot be modified. If you have
selected Autogenerate Id, this field will be disabled.
Autogenerate Name If selected, the name of the Material Tracking Unit Aggregate to
be added will be autogenerated using the Numbering Pattern
defined for Material Tracking Unit Aggregate Name. If you are
modifying an existing Material Tracking Unit Aggregate, you can
automatically generate (or re-generate) the Material Tracking
Unit Aggregate Name by selecting this check box (see Edit
Material Tracking UnitAggregate operation in Available
Operations on Material Tracking Units Aggregates). You need to
Name (Optional) The name assigned to the Material Tracking Unit

Aggregate. If you have selected Autogenerate Name, this field
will be disabled.
Code Type (Optional) The type of Code assigned to the Material Tracking
Unit. The possible values are:
• BatchId: identifies a batch object
• SerialNumber: identifies an object that can be
serialized.
Code (Optional) The Batch Id or Serial Number assigned to the

Material Tracking Unit.
Description (Optional) Additional information on the Material Tracking Unit

Aggregate.
Material Id (Optional) The Material you want to associate with the Material
Tracking Unit Aggregate.

Manufacturing Apps
Material App
Use Current Revision The field is read-only and the shown value is based on the
Material revision you have previously selected.
Material Revision (Optional) The Material revision associated with the Material
Tracking Unit Aggregate. If you have selected Use Current
Revision, this field will be disabled.
otherwise, one Unique identifier must be selected in the list of
the available ones. If you have selected Use Current Revision,
this field will be disabled.
Unit of Measure (Optional) The Unit of Measure you want to associate with the
Material Tracking Unit Aggregate.
Value (Optional) The Unit of Measure value. This value is optional

unless Unit of Measure is specified. In this case, Value becomes
mandatory.
Use Default Template If selected, indicates that the Material Tracking Unit Aggregate
will be created using the default Material Tracking Unit
Aggregate Template.
Template (Optional) The Material Tracking Unit Aggregate Template to be

used for the creation of the Material Tracking Unit Aggregate.
State Machine (Optional) The State Machine associated with the Material
Tracking Unit Aggregate. If a State Machine is selected, it
overrides the one potentially defined in the chosen Material
Tracking Unit Aggregate Template. You need to configure the
State Machine in the Reference App.
Equipment (Optional) The Equipment you want to associate with the

Material Tracking Unit Aggregate. If you have selected Material
Tracking Unit Aggregate, this field will be disabled. You can
either use the predefined Equipment or configure the Equipment
in the Equipment App.
Material Tracking Unit Aggregate (Optional) The Material Tracking Unit Aggregate you want to
associate with the Material Tracking Unit Aggregate. If you have
selected Equipment, this field will be disabled.
4. Click Save. The new Material Tracking Unit Aggregate is created.

Manufacturing Apps
Material App
 • Once the first Material Tracking Unit Aggregate is created, the Material Tracking Unit Aggregate page
is available by selecting the Material Tracking Unit Aggregate and by clicking
. Here other Material Tracking Unit Aggregates can be created from the Overview tab.
The create operation is also available in the Material Tracking Unit Aggregates tab to create and
• associate a Material Tracking Unit Aggregate with an existing Material Tracking Unit Aggregate.
Adding a Property to a Material Tracking Unit Aggregate

1. In the Material Tracking Unit Aggregates page, select a Material Tracking Unit Aggregate and click to
open the Material Tracking Unit Aggregate page.
Adding a Material Tracking Unit to a Material Tracking Unit Aggregate

1. In the Material Tracking Unit Aggregates page, select a Material Tracking Unit Aggregate and click to
open the Material Tracking Unit Aggregate page.
2. In the Material Tracking Units tab, click .
3. Set the required attributes and click Save. See Configuring Material Tracking Units.
 You can access the associated Material Tracking Unit in the Material Tracking Unit page by selecting
the Material Tracking Unit and by clicking .
Available Operations on Material Tracking Unit Aggregates

On the existing Material Tracking Unit Aggregates you can then perform the following operations, by selecting
a Material Tracking Unit Aggregate and clicking the proper icon in the Overview tab.
Edit Allows you to modify Name, Description, Code and Code Type.
If you want to apply the Numbering Pattern to the Name property,
you must select the Autogenerate Name check box (regardless of
whether you have already used it or not). If the Numbering Pattern
has been modified or if it contains parts that may change (such as a
counter or a timestamp), the Name property will be modified.
The Material Tracking Unit Aggregate must not be flagged
as IsFrozen.
This operation is also available in the Material Tracking Unit
Aggregates tab to update a Material Tracking Unit Aggregate
associated with another Material Tracking Unit Aggregate.

Manufacturing Apps
Material App
Freeze/ Unfreeze The Freeze operation allows you to configure a Material Tracking
Unit Aggregate as read-only, in order that it cannot be edited. When
the freezing operation is applied to a Material Tracking Unit
Aggregate, the Material Tracking Unit Aggregate is
You can remove the read-only setting by applying the Unfreeze
operation.
Allows you to set a State Machine associated with the Material

Set State Machine Tracking Unit Aggregate.
This operation can be performed only if a State Machine is not
Allows you to set a Status associated with the Material Tracking

Set Status Unit Aggregate.
This operation can be performed only if a State Machine is already
associated, otherwise the icon is not displayed.
Allows you to set a Material associated with the Material Tracking

Set Material Unit Aggregate. You must set the required attributes:
• New Material Id (mandatory)
For the attribute details, see Creating a Material Tracking Unit
Aggregate.
Allows you to set a new Quantity associated with the Material

Set Quantity
Allows you to modify the association of the Material Tracking Unit

Load into a Material Tracking Unit
Aggregate with a Material Tracking Unit Aggregate.
Aggregate
Aggregates tab.
Allows you to modify the Equipment associated with the Material

Load into an Equipment
Allows you to permanently remove a Material Tracking Unit

Delete
Aggregate.
Aggregates tab to delete a Material Tracking Unit Aggregate
associated with another Material Tracking Unit Aggregate.

Manufacturing Apps
Personnel App
Available Operations on Material Tracking Unit Aggregate Properties

On the existing Material Tracking Unit Properties you can then perform the following operations, by selecting the
Available Operations on Material Tracking Units associated with Material Tracking

Unit Aggregates
On a Material Tracking Unit associated with a Material Tracking Unit Aggregate, you can then perform the following
operations, by selecting the Material Tracking Unit Aggregate and clicking the proper icon in the
Material Tracking Units tab. For more details on the operations, see Configuring Material Tracking Units.
Allows you to update a Material Tracking Unit associated

Edit
with a Material Tracking Unit Aggregate.
Allows you to modify the association of the Material

Move to a Material Tracking Unit
Tracking Unit with a Material Tracking Unit Aggregate.
Aggregate
Allows you to delete a Material Tracking Unit associated

Delete
with a Material Tracking Unit Aggregate.
3.6 Personnel App

The Personnel App provides pages where it is possible to create and configure Persons, import Persons from UMC
and manage Groups of Persons.
Segregation tags created in the Data Segregation App can subsequently be associated to these Persons and
Groups of Persons, in order to grant them the right to access to segregated data.
• PRM_MS
• DSG_SD

Manufacturing Apps
Personnel App
What can I do with the Personnel App?

• Useful conceptual information is provided in What is Personnel Management.
• The configuration workflow and procedures are described in How to Manage Persons and How to Manage
Person Groups.
• Information on the Functional Block referenced by the Personnel App is provided in PRM-MS Functional
Block (see PRM_MS Functional Block section of the Opcenter Execution Foundation Development and
• Information about logging personal information is provided at Choosing Trace Providers section of the Opcenter
 Security Note
The principles of data protection are important to Siemens and out affiliates. Our products, including
Opcenter Execution Foundation, are designed with privacy in mind and adhere to Siemens’ data protection
requirements. Please visit our privacy statement for more details.
The product processes / stores the following personal data: FirstName, LastName, Email Addresses, Phone
Numbers, Date Of Birth, Nationality, State, City, Address, ZipCode, UserName.
It is essential to collect this information to identify the authorized operators. We only store the data for as
long as necessary. Please contact customer support with any questions.
3.6.1 What is Personnel Management?

The Personnel App makes it possible to manage Persons and Groups of Persons.
Persons can be created from scratch or directly from User Management Component (UMC) users, integrating
additional information such as address, nationality and an image of the person. Whereas, groups can be
created from scratch only.
Data Segregation Integration

Data Segregation tags can be added to Persons or Person Groups to integrate the Data Segregation functionality
into your solution.
Data Segregation tags are defined in the Data Segregation App, whilst Persons/Person Groups and their
association to data segregation tags are defined in the Personnel App.

Manufacturing Apps
Personnel App
3.6.2 How To Manage Persons

Persons can be created in the Personnel App, either from scratch or from UMC Users.
Once they have been created, Data Segregation tags, created in the Data Segregation App, can be assigned to the
Person.
Workflow
1. Create a new Person either by:
• Adding a Person from scratch or based on a UMC User.
• Importing UMC Users or groups of UMC Users.
2. Assign Segregation Tags to Persons.
Available Operations on Persons

On the existing Persons you can then perform the following operations, by selecting the Person and clicking the
proper icon in the Persons page.
Edit To modify required fields.
Delete To delete the Person.
Overview To view an overview of the Person. The Person details dialog box displays:
• In the General tab, unique Id for the created Person and information on
Person name and description.
• In the Details tab, information on Person date of birth, nationality and
full address.
• In the Groups tab, the list of Person Groups to which a Person is
assigned.

Export
and Exporting and Importing Personnel Data for further information on the
import sequence of Personnel data.

Manufacturing Apps
Personnel App
3.6.2.1 Creating a Person

There are a number of different ways to create Persons in the Personnel App:
Creation Description
method
Adding a new You can enter all useful information on a Person, including an image, in a single working
Person from environment.
scratch
 It is strongly suggested to follow local data protection and privacy laws and
consequently avoid inserting personal information, such as the name or surname
of the user, in the mandatory Id field.
Adding a new You can create a Person, starting from a UMC user.
Person based on
a UMC User
• Importing You can import Users or User Groups from UMC.

Users from
UMC
 • Users who have already been assigned to Persons cannot be imported.
• Importing • Before starting a new import operation, the one in progress must be
User Groups completed.
from UMC • Depending on the number of users or user groups to be imported, the import
operation may be a long-running operation and fail due to temporary errors. In
this case, we suggest that you create a new Worker Role with the Import UMC
User command assigned and increase the timeout value in the Worker Roles
page in Solution Studio (see Creating a New Worker Role and Configuring
Worker Roles sections of the Opcenter Execution FoundationOpcenter Execution
Once the operation is completed, you can view the import details, by clicking View
Details. The Import Details dialog box provides the following information:
• the list of the UMC users that have been imported.
• the list of the UMC users that have been assigned to an existing Person.
• the list of the UMC users that have not been imported.
 The creation of the Person entity, which contains the definition of the new Person, is not in itself a
segregated operation.
Prerequisites
Specific securable command rights (documented in the PRM_MS Functional Block in the Opcenter Execution
Foundation Development and Configuration Guide) are required to create and configure Persons:
• The CreatePerson command to create a new person.
• The AssignUserToPerson command must be assigned to the role of the user who wants to assign a UMC User to
a Person.

Manufacturing Apps
Personnel App
• The UnassignUserFromPerson command must be assigned to the role of the user who wants to unassign a
UMC User from a Person.
• (Only to import Users or User Groups) The ImportUsersByUserList command to import users from UMC
• (Only to import Users or User Groups) The ImportUsersByGroup command to import user groups from UMC.
• (Only to add a Person from scratch) The created Person can view not segregated data by default.
The SetCanViewUnsegregatedData command must be assigned to the role of the user who wants to modify
the default behavior in order for the created Person to not view not segregated data. The Data Segregation
functionality must be enabled to use this feature.
The AccessControlViewer or AccessControlAdmin role must also be assigned to the user, in order to be able to
view UMC users. For information on these roles, see How to Configure Accounts of the Opcenter Execution
Adding a new Person from Scratch

1. Do either of the following to open the Persons page:
• Click the Persons home tile.
• Click Personnel Management in the side menu bar and click Persons.
2. In the Persons page, click .
3. In the Add Person panel, select From scratch.
4. In the Details section, enter the following information:
Add Image Insert an image of the new person and browse for the file.
Id A mandatory unique Id for the person you are creating. Once defined,
this value cannot be modified.
First Name (Optional) First name (given name) of the person.
Last Name (Optional) Last name (surname) of the person.
Full Name (Optional) Full name of the person for identifying.
Initials (Optional) Initials of the person.
Title (Optional) Title of a user to identify the position.
Description (Optional) Description for the person.

5. If you want the created Person to view the not segregated data, leave the default setting of the View
Unsegregated data checkbox. Otherwise, remove the selection from View Unsegregated data checkbox; in
this way, the created Person cannot view not segregated data.
6. If you want to associate a UMC user to the person:
a. Click next to the User Name field.
b. In the Select UMC Users dialog box select the user you want to associate and click Select: the User
Name field is filled with information retrieved from UMC. This data can be modified if required.
7. (Optional) In the Phone and Mobile Phone section, enter the work and personal phone numbers of the person
as required.
8. (Optional) In the E-Mail section, enter the work and personal email addresses of the person as required.

Manufacturing Apps
Personnel App
9. (Optional) In the Other Details section, enter the information on the person's date of birth, nationality, and full
address. Use to select the month and year.
10. Click Save.
Adding a new Person based on a UMC User

3. In the Add Person panel, select From UMC User.
4. In the Select UMC Users dialog box select the user you want to associate and click Select: in the Add
Person page, in the Details section the Id and User Name fields are filled with information retrieved from UMC.
This data can be modified if required.
5. In the Details section, enter the following information:
Add Image Insert an image of the new person and browse for the file.
First Name (Optional) First name (given name) of the person.
Last Name (Optional) Last name (surname) of the person.
Full Name (Optional) Full name of the person for identifying.
Initials (Optional) Initials of the person.
Title (Optional) Title of a user to identify the position.
Description (Optional) Description for the person.

6. (Optional) In the Phone and Mobile Phone section, enter the work and personal phone numbers of the person
as required.
7. (Optional) In the E-Mail section, enter the work and personal email addresses of the person as required.
8. (Optional) In the Other Details section, enter the information on the person's date of birth, nationality, and full
address. Use to select the month and year.
9. Click Save.
Importing Users from UMC

3. In the Import UMC Users panel, select the From User List.
4. Select at least one filter condition in order for the system to return a list of users.
5. Select the user you want to import or select all users by setting the dedicated option. Users who have already
been assigned to Persons will not be imported.
6. Click Save.

Manufacturing Apps
Personnel App
Importing User Groups from UMC

3. In the Import UMC Users page, select the From Group radio button.
4. Select the group you want to import and click Save.
3.6.2.2 Assigning Segregation Tags to Persons

Data Segregation Tags can be assigned to Persons to integrate the Data Segregation functionality into your
solution.
The creation of the PersonSegregationTag entity, which associates segregated tags to Persons, is not in itself a
segregated operation. So, when you assign segregation tags to Persons, you are not segregating them but you are
granting them the right to access to segregated data. See also PRM_MS Functional Block in the Opcenter Execution
 In order to assign Segregation Tags to a Person, these tags must be assigned to the logged on user. In case
the logged user is the SysAdmin, all Segregation Tags are already assigned to him/her by default. In case
the logged user is not the SysAdmin, bear in mind to assign segregation tags to this user, otherwise he/she
cannot perform the operation.
The SysAdmin user can assign Segregation Tags to Persons or entity instances without needing to be
associated with a Person in the Personnel App.
For information on SysAdmin user, see Quick Start to Using Data Segregation and How to Configure
Accounts of the Opcenter Execution Foundation Development and Configuration Guide.
Prerequisites
• The Data Segregation App has been installed in the solution.
• The ManageSegregationTagsToPersonsAssociation command right must be assigned to the role of the user
who wants to assign the segregation tag. For more information, see PRM_MS Functional Block in the Opcenter
• The AccessControlViewer or AccessControlAdmin role must also be assigned to the user, in order to assign
Segregation Tags to the Person. For information on these roles, see How to Configure Accounts of the Opcenter
• In case the logged user is not the SysAdmin, segregation tags must be assigned to this user, otherwise he/she
cannot perform the operation (if the logged user is the SysAdmin, all Segregation Tags are already assigned to
him/her by default).
• The Person to whom you want to assign tags is not associated with the SysAdmin user. Otherwise, the
dedicated button ( Manage) is not displayed because all segregation tags are already assigned to the
SysAdmin user by default.
Procedure
1. Do either of the following to open the Segregation Tags Management page:
• Click the Segregation Tags Management home tile.
• Click Personnel Management in the side menu bar and click Segregation Tags Management.

Manufacturing Apps
Personnel App
2. In the Segregation Tags Management page filter the list of Persons (see UI Common Functionalities) to display
those to whom you want to assign tags. Otherwise, if you do not enter any filtering criteria, the grid remains
empty.
3. Select the user associated with the Person and click Manage. The Manage Tags sidebar displays the
Segregation Tags that have already been assigned to the selected Person, and those that are available but not
currently assigned.
4. To assign Segregation Tags to the selected Person, click the icon in the available tags list and click Save.
 • Changes made to the Segregation Tags assigned to a Person are applied the next time the associated
user logs on.
• The Manage button is not displayed if the user associated with the Person is the SysAdmin. This
is because all segregation tags are already assigned to this user by default by the Personnel App.
 • You can unassign Segregation Tags from the selected Person by clicking the icon in the Manage
Tags sidebar.
• Persons inherit all tags assigned to the Groups to which they are associated with. You can view
Segregation Tags assigned to Person Groups by selecting the Person assigned to the Person Group in
the Segregation Tags Management page and by clicking View Group Tags. The Person Group
Segregation Tags sidebar displays the Segregation Tags that are currently assigned to each Person
Group.
3.6.2.3 Modifying Persons

You can modify the Persons you have entered in the Personnel App. All fields can be modified, except the Id.
Prerequisites
Specific command rights (see PRM_MS Functional Block in the Opcenter Execution Foundation Development and
Configuration Guide) are required to modify Persons. In particular:
• The AssignUserToPerson command must be assigned to the role of the user who wants to assign a UMC User to
a Person.
• The UpdatePerson command to modify a Person.
• An existing Person can view non-segregated data by default. To allow a Person to view segregated data, you
must assign the SetCanViewUnsegregatedData command to the role of the user who wants to modify the
capability of the existing Person to view non-segregated data.
• The Data Segregation functionality must be enabled to use this feature.
The AccessControlViewer or AccessControlAdmin role must also be assigned to the user, in order to be able to
For more information on the mentioned command, see also PRM_MS Functional Block in the Opcenter Execution
Procedure
2. In the Persons page, select the required Person.

Manufacturing Apps
Personnel App
3. Click .
4. In the Edit Person dialog box, select the required section, modify the personal information and then click Save:
Section Description
Details To modify Person name, title, and description. The Person Id

cannot be modified.
Click the View Unsegregated data check box to allow the
modified Person to view non-segregated data.
Phone and Mobile Phone To modify work and personal phone numbers.
E-Mail To modify work and personal email.
Other Details To modify date of birth, nationality, and full address.

The list of Person Groups to which a Person is assigned in the Groups tab cannot be modified.
3.6.2.4 Deleting Persons

You can delete the Persons you have entered in the Personnel App. Persons can be deleted even if tags and users
have been associated to them. Naturally deleting a Person does not delete their associated tags or users.
Prerequisites
• Specific command rights are required to modify Persons. In particular:
• The UnassignUserFromPerson command must be assigned to the role of the user who wants to
unassign a UMC User from a Person.
• The DeletePerson command right must be assigned to the role of the user who wants to delete a Person.
• The AccessControlViewer or AccessControlAdmin role must also be assigned to the user, in order to be able to
For more information on the mentioned commands see PRM_MS Functional Block in the Opcenter Execution
Procedure
2. In the Persons page, select the required Person.
3. Click .
3.6.3 How to Manage Person Groups

In the Personnel App, you can group Persons who share common characteristics.
Groups of Persons can be created from scratch. After creating a Person Group, one or more Persons can be assigned
to the Person Group. A Person can be assigned to more Person Groups at the same time.

Manufacturing Apps
Personnel App
You can complete the Group configuration by assigning a list of segregation tags, previously created in the Data
Segregation App, to the Person Group.
Workflow
1. Create a Person Group.
2. Assign a Person to a Person Group.
3. Assign Segregation Tags to a Person Group.
Available Operations on Person Groups

On the existing Person Groups you can then perform the following operations, by selecting the Person Group and
clicking the proper icon in the Person Groups page.
Edit To modify required fields.
Delete To permanently remove a Person Group.

Export
and Exporting and Importing Personnel Data for further information on the
import sequence of Personnel data.
3.6.3.1 Creating a Person Group

You can create Groups of Persons in the Personnel App from scratch.
Prerequisites
The CreatePersonGroup command right (documented in PRM_MS Functional Block in the Opcenter Execution
Foundation Development and Configuration Guide) must be assigned to the role of the user who wants to create a
Person Group.
Procedure
1. Do either of the following to open the Person Groups page:
• Click the Person Groups home tile.
• Click Personnel Group Management in the side menu bar and click Person Groups.

Manufacturing Apps
Personnel App
2. In the Person Groups page, click .

Id The unique identifier assigned to the Person Group. Once the Person
Group is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Person Group.
Description (Optional) Additional information on the Person Group.

4. Click Save. The new Person Group is created.
3.6.3.2 Assigning Persons to Person Groups

After creating Persons and Person Groups, you can assign one or more Persons to the Person Group. A Person can
be associated with more Person Groups at the same time.
Prerequisites
• The AssociatePersonsWithPersonGroup command right must be assigned to the role of the user who wants to
associate Persons with Person Groups.
• The DisassociatePersonsFromPersonGroup command right must be assigned to the role of the user who
wants to remove the association between Persons and Person Groups. For more information, see PRM_MS
Functional Block in the Opcenter Execution Foundation Development and Configuration Guide).
Procedure
2. In the Person Groups page, select the required Person Group.
3. Click .
4. In the Assign Persons to Person Group page, do either of the following:
• Enter the required Person Id in the dedicated field.
• Click . In the displayed dialog box, select the required Person and click Select. The selected Person is
displayed in the dedicated field.
5. Click Add Person. The Person is assigned to the Person Group.
 You can remove Persons from a Person Group by selecting one or more Persons and by clicking
Remove.
3.6.3.3 Assigning Segregation Tags to Person Groups

Data Segregation Tags can be assigned to Person Groups to integrate the Data Segregation functionality into your
solution.

Manufacturing Apps
Personnel App
The creation of the PersonGroupSegregationTag entity, which associates segregated Tags to Person Groups, is not
in itself a segregated operation. So, when you assign segregation tags to Person Groups, you are not segregating
them but you are granting them the right to access to segregated data. See also PRM_MS Functional Block in the
Opcenter Execution Foundation Development and Configuration Guide).
 In order to assign Segregation Tags to a Person Group, these tags must be assigned to the logged on user,
however all Segregation Tags are assigned to SysAdmin users by default.
The Opcenter Execution Foundation SysAdmin user can assign Segregation Tags to Person Groups or
entity instances without needing to be associated to a Person Group in the Personnel App.
Prerequisites
• The Data Segregation App has been installed in the solution.
• The Segregation Tags to be assigned to the Person Group must have already been assigned to the logged on
user.
• The ManageSegregationTagsToPersonGroupsAssociation command right must be assigned to the role of the
user who wants to assign the segregation tag. For more information, see PRM_MS Functional Block in the
Opcenter Execution Foundation Development and Configuration Guide).
Procedure
2. In the Person Groups page, select a Person Group and click . The Assign Segregation Tags sidebar displays
the segregation tags that have already been assigned to the selected Person Group, and those that are available
but not currently assigned.
3. To assign Segregation Tags to the selected Person Group, click the icon in the available tags list and click
Save.
 • Changes made to the Segregation Tags assigned to a Person Group are applied the next time the
associated user logs on.
• You can unassign Segregation Tags from the selected Person Group by clicking the icon in
the Assign Segregation Tags sidebar.
• Persons inherit all tags assigned to the Groups to which they are associated with. You can view
Segregation Tags assigned to Person Groups in the Personnel Management environment by selecting
the Person assigned to the Person Group in the Segregation Tags Management page and by clicking
View Group Tags. The Person Group Segregation Tags sidebar displays the Segregation Tags
that are currently assigned to each Person Group.
3.6.3.4 Modifying Person Groups

You can modify the Person Groups you have entered in the Personnel App. All fields can be modified, except the Id.
Prerequisites
The UpdatePersonGroup command right must be assigned to the role of the user who wants to modify a Person
Group. For more information on the mentioned command, see also PRM_MS Functional Block in the Opcenter

Manufacturing Apps
Personnel App
Procedure
3. Click and modify required fields. Only the Id of the Person Group cannot be modified.
4. Click Save.
3.6.3.5 Deleting Person Groups

You can delete the Person Groups you have entered in the Personnel App.
Prerequisites
The DeletePersonGroup command right must be assigned to the role of the user who wants to delete a Person
Group. For more information on the mentioned command see PRM_MS Functional Block in the Opcenter Execution
Procedure
3. Click .
3.6.4 Exporting and Importing Personnel Data

The Personnel App allows you to export its own master data entities, see How To Export and Import Data for more
information about the procedure.
Unlike the Export operation, the Import procedure depends on the exported entities and has to be performed
carefully as described in the following section.

Example: If you want to import Person Group and Person entities, and the Person Group entities were exported
selecting Include Descendants = False , you must first import the Person Group package and then the Person one.
 Note that Person Groups are parent entities.
Person Group Person Notes
Person Group & If Person Group is exported by

setting Include Descendants to False
Person

Manufacturing Apps
Reference App
Person Group Person Notes
Person Group If Person Group is exported by

& setting Include Descendants to True.
Person Note that the system will export only the
Person entities that are associated to
Person Groups.
Person If the export package contains Person

entities associated to Person Groups, the
Person Groups must be already present in
the target environment in order to
preserve referential integrity.
Person Group
3.7 Reference App

The Reference App provides pages where it is possible to:
• Manage Units of Measure
• Manage Entity Lifecycles with State Machines
• How to Manage Autonumbering
The Reference App references the UDM_RF Functional Block. For detailed information on the artifacts contained in
this Functional Block, see the Reference Documentation of the Functional Block.
3.7.1 How to Manage UoMs

Opcenter EX FN provides pages where you can manage Units of Measure (UoMs).
The UoM management is based on the concept of grouping UoMs into different categories, called UoM dimensions,
according to the physical property they measure (such as length, mass, time). Each UoM dimension contains
base UoMs, which represent the base unit for measuring a physical quantity (such as meter, kilogram, second). For
each base UoM can be defined multiple and submultiple UoMs, and the conversion factors (UoM Factors) between
this base UoM and other base UoMs belonging to the same UoM dimension.
For example:
• The UoM dimension mass contains the base UoM kilogram and the base UoM pound. For the base UoM
kilogram, the submultiple gram and the multiple ton are defined, as well as the conversion factor between
kilogram and pound.
• The UoM dimension volume contains the base UoM liter. For the same UoM dimension you can define the base
UoM bottle and the conversion factor between the base UoMs bottle and liter (e.g. bottle = 2 liter). You can also
define bottle multiples (e.g. case = 6 bottle and pallet = 360 bottle).
Opcenter EX FN provides a set of predefined entities (see Units of Measure Management in the Opcenter Execution
Foundation Development and Configuration Guide. These entities are flagged as IsSystemDefined. Predefined
entities cannot be modified, except for their Name and Description, in order to maintain universally known

Manufacturing Apps
Reference App
symbols and ratio among the UoMs, but allowing the customization of the name and the description in a language
different from the default one.
In addition to the predefined entities, you can define custom entities such as UoM dimensions, base UoMs with
related multiples/submultiples, and UoM factors, by following this workflow:
Workflow
1. Create the UoM Dimension to which the new UoMs will belong.
2. Create the required base UoMs associated to the UoM Dimension.
3. Add to the base UoMs the required multiples and submultiples and/or the proper conversion factors between
base UoMs.
 Constraints on entities relationships

• Each multiple and submultiple must be only associated to its base UoM, through the proper conversion
factor. For example, the conversion factor between millimeters to meters must be defined, but the
conversion factor between millimeters to yards is not allowed.
• A base UoM can be associated to several conversion factors to define its relationship with other base
UoMs in the same UoM dimension. If a conversion factor is defined between two base UoMs (for
example UoM A toward UoM B), the inverse conversion factor (UoM B toward UoM A) must not be
defined.
3.7.1.1 Configuring UoM Dimensions

A UoM dimension represents a physical category, such as length, time, volume.
The required custom UoM dimension must be created before creating and configuring custom UoMs.
Workflow
1. Add a UoM Dimension.
2. Add a UoM to a UoM Dimension.
Adding a UoM Dimension

1. Do either of the following to open the Units of Measure Dimensions page:
• Click the Units of Measure Dimensions home tile.
• Click Units of Measure Management in the side menu bar and click Units of Measure Dimensions.
2. Click .

Manufacturing Apps
Reference App
Id The unique identifier assigned to the UoM dimension. Once

the UoM dimension is created, the Id value cannot be modified.
Name (Optional) The name assigned to the UoM dimension.
Description (Optional) Additional information on the UoM dimension.

4. Click Save. The new UoM dimension is created and displayed in the UoM dimension grid.
 Once the first Units of Measure Dimension is created, the Units of Measure Dimension page is available by
selecting the Units of Measure Dimension and by clicking
. Here other Units of Measure Dimensions can be created from the Overview tab.
Available Operations on UoM Dimensions

On the existing UoM dimensions you can then perform the following operations, by selecting the UoM dimension in
the grid and clicking the proper icon.
Allows you to modify Name and/or Description of a UoM dimension.

Edit
The UoM dimensions must not be flagged as IsFrozen.
Hidden UoM dimensions cannot be modified.
Allows you to permanently remove a UoM dimension.

Delete
The UoM dimensions provided by Opcenter EX FN (flagged
as IsSystemDefined) cannot be deleted.
 If a UoM dimension is deleted all the UoMs belonging to that UoM

dimension are deleted as well.
The Freeze operation allows you to configure a UoM dimension as read-only,

Freeze/ Unfreeze
so that it cannot be edited. When the Freeze operation is performed on a
UoM dimension, the UoM dimension is flagged as IsFrozen.
Hidden UoM dimensions cannot be frozen.
 • If a UoM dimension is frozen, all the base UoMs, the multiples/

submultiples and the UoM factors related to that base UoM are
frozen as well.
• If a UoM dimension is unfrozen, all the base UoMs, the
multiples/submultiples and the UoM factors related to that
base UoM are unfrozen as well.

Manufacturing Apps
Reference App
The Hide operation allows you to prevent a UoM dimension from being
Hide/ Unhide
displayed among the UoM dimensions available for the UoM management.
When the Hide operation is performed on a UoM dimension, the UoM
dimension is flagged as IsHidden.
You can restore the visibility of a hidden UoM dimension by performing the
Unhide operation.
 If a UoM dimension is hidded, all the base UoMs, the multiples/

submultiples and the UoM factors related to that base UoM are
hidded as well.
Export Allows you to export selected entities and instances in an export package
that can be downloaded locally and imported afterwards.
exchange and Exporting and Importing UoM Data for further information on
the import sequence of UoM data.
Adding a Unit of Measure to a Unit of Measure Dimension

1. In the Unit of Measure Dimensions page, select a Unit of Measure Dimension and click to open the Unit of
Measure Dimension page.
2. In the Unit of Measures tab, click .
3. Set the required attributes and click Save. See Configuring UoMs.
 You can access the associated Unit of Measure in the Unit of Measure page by selecting the Unit of
Measure and by clicking .
Available Operations on Unit of Measures associated with Unit of Measure

Dimensions
On a Unit of Measure associated with a Unit of Measure Dimension, you can then perform the following operations,
by selecting the Unit of Measure Dimension and clicking the proper icon in the Unit of Measures tab. For more
details, see Configuring UoMs.

Manufacturing Apps
Reference App
Edit Allows you to modify the properties of the base UoM.
 If the UoM Dimension of a custom base UoM is modified, all the

UoM factors defined between this base UoM and the other custom
base UoMs, in the same UoM Dimension, are deleted.
Hide/ Unhide The Hide operation allows you to prevent a UoM from being displayed among
the UoMs available for the UoM management. When the Hide operation is
performed on a UoM, the UoM is flagged as IsHidden.
You can restore the visibility of a hidden UoM by performing the Unhide
operation.
 • If a base UoM is hidden, all the related multiples/submultiple

UoMs and UoM factors are hidden as well.
• If a base UoM is unhidden, the related UoM dimension, if
hidden, is unhidden as well and, if a UoM factor is defined
between this base UoM and another base UoM not hidden, this
UoM factor is unhidden as well.
Allows you to permanently remove a base UoM.

Delete
Audit Trail of a Unit of Measure Dimension
To display the Audit Trail of a Unit of Measure Dimension, select one and then navigate to the Audit Trail tab.
The Audit Trail tab shows the list of all changes performed on the selected Unit of Measure Dimension.
3.7.1.2 Configuring UoMs

In the Units of Measure page you can create and manage UoMs which represent the base unit for measuring a
physical quantity, such as meter, kilogram, second. A UoM must belong to a specific UoM dimension. Once you have
created a base UoM you can define related multiple UoMs and submultiple UoMs, and define conversion factors
between this base UoM and other base UoMs belonging to the same UoM dimension.
Workflow

Manufacturing Apps
Reference App
1. Add a Base UoM.

2. Add a Multiple/Submultiple UoM to a Base UoM.
3. Add a UoM Factor to a Base UoM.
Adding a Base UoM

1. Do either of the following to open the Units of Measures page:
• Click the Units of Measures home tile.
• Click Units of Measure Management in the side menu bar and click Units of Measures.
2. Click .
Id The unique identifier assigned to the base UoM. Once the UoM is
Name (Optional) The name assigned to the base UoM.
Description (Optional) Additional information on the base UoM.
UoM Dimension The UoM dimension to which the new UoM belongs.
4. Click Save. The new base UoM is created and displayed in the grid of the Unit of Measure Management page.
 Once the first Units of Measure is created, the Units of Measure page is available by selecting the Units of
Measure and by clicking . Here other Units of Measures can be created from the Overview tab.
Available Operations on UoMs

On the existing base UoMs you can then perform the following operations, by selecting the base UoM from the
grid and clicking the proper icon in the Overview tab.
Edit Allows you to modify the properties of the base UoM.

Hidden UoMs cannot be modified.
 If the UoM Dimension of a custom base UoM is modified, all the

UoM factors defined between this base UoM and the other custom
base UoMs, in the same UoM Dimension, are deleted.

Manufacturing Apps
Reference App
Hide/ Unhide The Hide operation allows you to prevent a UoM from being displayed
among the UoMs available for the UoM management. When the Hide
operation is performed on a UoM, the UoM is flagged as IsHidden.
operation.
 • If a base UoM is hidden, all the related multiples/submultiple

UoMs and UoM factors are hidden as well.
• If a base UoM is unhidden, the related UoM dimension, if
hidden, is unhidden as well and, if a UoM factor is defined
between this base UoM and another base UoM not hidden, this
UoM factor is unhidden as well.
Delete Allows you to permanently remove a base UoM.

The UoM dimensions provided by Opcenter EX FN (flagged
as IsSystemDefined) cannot be deleted.
Allows you to export selected entities and instances in an export package

Export
that can be downloaded locally and imported afterwards.
exchange and Exporting and Importing UoM Data for further information on
the import sequence of UoM data.
Adding a Multiple/Submultiple UoM to a Base UoM

1. In the Unit of Measures page, select the base UoM for which you want to define a multiple/submultiple
UoM and click to open the Unit of Measure page.
2. In the Multiple/Submultiple Unit of Measures tab, click .
3. Set the following attributes to define the multiple/submultiple UoM by using the formula BaseUoM = (K1
* Multiple/SubmultipleUoM) to convert quantities.
For example: BaseUoM = g and MultipleUoM = kg therefore K1 should be set to 1000 and the resulting formula
is quantity in g = 1000 * quantity in kg.
Id The unique identifier assigned to the multiple/submultiple UoM. Once

the multiple/submultiple UoM is created, the Id value cannot be
modified.
Name (Optional) The name assigned to the multiple/submultiple UoM.
Description (Optional) Additional information on the multiple/submultiple UoM.
K1 Multiplier The multiplication factor K1 in the conversion formula.

Manufacturing Apps
Reference App
4. Click Save. The new multiple/submultiple UoM is created and displayed in the Multiples/Submultiple Unit of
Measures grid.
Available Operations on Multiple/Submultiple UoMs

On the existing multiple/submultiple UoMs you can then perform the following operations, by selecting the
multiple/submultiple UoM in the grid and clicking the proper icon.
Edit Allows you to modify Name, Description and the K value of a multiple/
submultiple UoM. The K value cannot be modified if a multiple/submultiple
UoM is flagged as IsSystemDefined, in order to maintain universally known
ratio among UoMs.
Hide/ Unhide The Hide operation allows you to prevent a UoM from being displayed
among the UoMs available for the UoM management. When the Hide
operation is performed on a UoM, the UoM is flagged as IsHidden.
operation.
 If a multiple/submultiple UoM is unhidden, the related base UoM

and the related UoM dimension are unhidden as well.
Allows you to permanently remove a multiple/submultiple UoM.

Delete
Adding a UoM Factor to a Base UoM

1. In the Unit of Measures page, select the source base UoM, for which you want to define a UoM factor and click
to open the Unit of Measure page.
2. In the Unit of Measure Factors tab, click .
3. Set the proper attributes to define the conversion factor between the source base UoM selected and a target
base UoM, by using the formula SourceUoM = K0 (K1 * TargetUoM)n + A to convert quantities.
For example: SourceUoM = K (Kelvin) and TargetUoM = F (Fahrenheit) therefore K0 should be set to 1, K1 to
0.555555556, n to 1 and A to 255.372 and the resulting formula is quantity in K = 0.555555556 * quantity in F +
255.372.
Target UoM The base UoM for which you are defining a conversion factor towards
the source base UoM, previously selected.
K0 Multiplier The multiplication factor K0 in the conversion formula. Default value

(i.e. when not specified) = 1.
K1 Multiplier The multiplication factor K1 in the conversion formula. Default value

(i.e. when not specified) = 1.

Manufacturing Apps
Reference App
Exponent The exponent n in the conversion formula. It must be an integer.

Default value (i.e. when not specified) = 1.
Addend The addend parameter A in the conversion formula. Default value (i.e.
when not specified) = 0
4. Click Save. The new conversion factor between a source base UoM and a target base UoM is created and
displayed in the UoM Factor grid.
Available Operations on UoM Factors

On the existing UoM factors you can then perform the following operations, by selecting the UoM factor in the grid
and clicking the proper icon.
Edit Allows you to modify all the attributes of a UoM factor. A UoM factor
flagged as IsSystemDefined cannot be modified .
Allows you to permanently remove a UoM factor.

Delete
 If the conversion factor formula, be it direct or inverse, generates a complex number, the conversion will
return an error (complex numbers are not used inside MES procedures).
3.7.1.3 Exporting and Importing UoM Data

The Reference App allows you to export and import its own master data entities. Unlike the Export operation, the
Import procedure depends on the exported entities and has to be performed as described in the following section.

Example: If you want to import UoM Dimension, UoM and UoM Factor entities, if the UoM Dimension entities were
exported selecting Include Descendants = False and UoM is exported selecting Include Descendants= True, you
must import the packages in this order:
1. UoM Dimension
2. UoM.
 • Unit of Measures defined by the system (flagged as Is System Defined) cannot be exported.
• UoM Dimensions are parent entities and their UoM are exported automatically.
• If you export multiple/submultiple UoMs without exporting their own source UoM, the import
operation cannot be performed.
• You cannot import a child entity if it belongs to a parent entity that is not in the database during the
import operation.

Manufacturing Apps
Reference App
UoM UoM UoM Notes

Dimension Factor
UoM Dimension & If UoM Dimension is exported by

UoM & UoM Factor setting Include Descendants to True
UoM Dimension & If UoM Dimension is exported by

UoM & UoM Factor setting Include Descendants = False and
if UoM is exported by
setting Include Descendants to True.
UoM & UoM Factor If UoM is exported by setting Include

UoM Dimensions
UoM
3.7.2 How to Manage Entity Lifecycles with State Machines

Opcenter EX FN provides pages where you can manage State Machines.
A State Machine represents the lifecycle of an entity and it is defined by a set of Statuses and Transitions. A State
Machine can then be applied to Equipment, Operations, Work Orders, and Tasks (Tasks are automatically
associated with a default Task management State Machine).
The Status Definitions represent a list of all the states available for a State Machine configuration: starting from a
Status Definition it is in fact possible to create an instance of that Status Definition and assigning it to the proper
State Machine.
The Status Transition Definitions describe a set of Verbs which provide a business relevant meaning to a transition
between two statuses of a State Machine.
In addition, Opcenter EX FN provides a Status Behavior Definitions entity to host relevant information to be
logically associated to a Status of a State Machine. At start up this entity is left empty, allowing you to fill it (through
a DBInit procedure) with its business relevant information. When you are assigning a Status to a State Machine, it
will be possible for you to associate one or more behaviors to the Status itself.
Workflow
1. Create the Status Definitions.
2. Create the Status Transition Definitions (i.e. the Verbs).
3. Configure the State Machine (by assigning Statuses and Status Transitions, and optionally Status Behaviors)

Manufacturing Apps
Reference App
3.7.2.1 Configuring Status Definitions

The Status Definitions represent all the statuses that you want to assign to an entity in order to represent its
lifecycle. The lifecycle is modeled by the Status Machine and the Status Definitions represent all the statuses that an
entity may assume in its lifecycle.
Each Status Definition represents a reference status, that is a sort of template that you use to define (and link
together) several Statuses. The Statuses are created during the configuration of the Status Machine and can be
viewed as instances of the Status Definitions. When you choose and assign a Status Definition to the State Machine,
the system automatically creates a Status that corresponds to the chosen Status Definition and from which it
inherits all the properties (color, outcome and so on).
For each Status Definition you may have several Statuses, used in different Status Machines, and linked to the same
Status Definition identifier (Id). This is useful, for example, because you can query for a Status Definition Id (the
reference status) and retrieve all the Statuses associated with this Id (along with the entities that are associated
with these Statuses).
Adding a Status Definition

1. Do either of the following to open the Status Definitions page:
• Click the Status Definitions home tile.
• Click Status Management in the side menu bar and click Status Definitions
2. Click .
Id The unique identifier assigned to the Status Definition. Once

the Status Definition is created, the Id value cannot be modified.
Name (Optional) The name assigned to the Status Definition.
Description (Optional) Additional information on the Status Definition.
Color (Optional) The color (in hex code, for example #DF0000) that will be
associated to the Status Definition.

Manufacturing Apps
Reference App
Outcome The Outcome of the status represents its result. The possible options
are:
• NoOutcome: it represents a status which is not final.
• Success: it represents a final status which has completed
correctly.
• Failure: it represents a final status which has not
completed correctly.
• Skip: it represents a status which is skipped.
4. Click Save. The new Status Definition is created and displayed in the Status Definitions grid.
Additional operations on Status Definitions

On the existing Status Definitions you can then perform the following operations, by selecting the Status Definition
and clicking the proper icon.
Edit To modify Name, Description, Color and Outcome of the Status Definition.
Outcome cannot be modified if the Status Definition is flagged as
IsSystemDefined. The Status Definition must not be flagged as IsFrozen.
Freeze/ Unfreeze The Freeze operation allows you to configure a Status Definition as read-
only, so that it cannot be edited. When the Freeze operation is performed
on an entity, the Status Definition is flagged as IsFrozen.
operation.
Hide/ Unhide The Hide operation allows you to prevent a Status Definition from being
displayed among the Status Definitions available for the definition of a
Status. When the Hide operation is performed on a Status Definition, the
Status Definition is flagged as IsHidden.
You can restore the visibility of a hidden Status Definition by performing the
Unhide operation.

Export
exchange and Exporting and Importing Entity Life Cycle and State Machine
Data for further information on the import sequence of Entity Life Cycle and
State Machine data.
Delete To permanently remove a Status Definition.

Manufacturing Apps
Reference App
3.7.2.2 Configuring Statuses

Statuses are instances of Status Definitions which define the State Machine lifecycle.
A Status can be associated to one or more Status Behavior to give it a business relevant meaning (see Configuring
Status Behavior Definitions).
Workflow
1. Add a Status.
2. Associate a Status Behavior with a Status.
Adding a Status
1. Do either of the following to open the Statuses page:
• Click the Statuses home tile.
• Click Status Management in the side menu bar and click Statuses.
2. Click .
Status Definition The Status Definition associated with the Status. Status Definitions
represents all the status that you want to assign to an entity in order
to represent its lifecycle.
When selecting the Status Definition, the Color and the Outcome of
the selected Status Definition are automatically associated with the
Status.
State Machine The State Machine associated with the Status. A State Machine
represents a lifecycle, defined by a set of Statuses, as instances of
Status Definitions.
Name (Optional) The name assigned to the Status. If the value is left blank,
then the system will automatically set the field with the Name of
Status Definition associated with the Status.
Description (Optional) Additional information on the Status. If the value is left

blank, then the system will automatically set the field with the
Description of Status Definition associated with the Status.
Is Initial Allows you to set the selected Status as the initial status of the State
Machine.
4. Click Save. The new Status is created and displayed in the Statuses page.
 Once the first Status is created, the Status page is available by selecting the Status and by clicking
. Here other Statuses can be created from the Overview tab.
Available Operations on Statuses

Manufacturing Apps
Reference App
On the existing Status you can then perform the following operations, by selecting from the Overview tab, the
Status and clicking the proper icon.
Edit Allows you to modify Name, Description, Color and Outcome of the
Status. Outcome cannot be modified if the Status is flagged as
IsSystemDefined.
Allows you to set the selected Status as the initial status of the State
Set Status as Initial
Machine.
Delete Allows you to permanently remove a Status. If you delete a Status,

any relationships with all the Status Behaviors associated to it will
also be deleted.
Export Allows you to export selected entities and instances in an export

package that can be downloaded locally and imported afterwards.
See How To Export and Import Data for information about runtime
data exchange and Exporting and Importing Entity Life Cycle and
State Machine Data for further information on the import sequence
of Entity Life Cycle and State Machine data.
Associating Status Behaviors with a Status

1. In the Statuses page, select a Status and click to open the Status page.
2. Select a Status.
3. In the Status Behavior tab, click and select a Status Behavior.
4. Click Save. The Status Behavior is associate with the Status.
 You can remove the association between a Status Behavior and a Status by selecting the Status Behavior
in the Status Behavior tab and clicking .
3.7.2.3 Configuring Status Transition Definitions

A Status Transition Definition represents the transition between two statuses. It is identified in the UI page by
the Verb attribute, which represents an easy-to-understand action name associated to a status transition. Verb
definitions could be for example Start, Complete, Pause.
You cannot associate Status Transition Definitions with Status Definitions in this page: you will establish this
association while configuring the State Machine.
Adding a Status Transition Definition

1. Do either of the following to open the Status Transition Definitions page:
• Click the Status Transition Definitions home tile.
• Click Status Management in the side menu bar and click Status Transition Definitions.
2. Click .

Manufacturing Apps
Reference App
3. Insert a value for the new Verb in order to identify a status transition.
4. Click Save. The new Status Transition Definition is created and displayed in the Status Transition
Definitions grid.
Additional operations on Status Transition Definitions

On the existing Status Transition Definitions you can then perform the following operations, by selecting the Status
Transition Definition and clicking the proper icon.
Operati Description
on
Allows you to permanently remove a Status Transition Definition.

Delete
The Freeze operation allows you to configure a Status Transition Definition as read-only, so that it
Freeze/ cannot be edited. When the Freeze operation is performed on an entity, the
Status Transition Definition is flagged as IsFrozen.
Unfree You can remove the read-only setting by performing the Unfreeze operation.
ze
The Hide operation allows you to prevent a Status Transition Definition from being displayed among
Hide/ the Status Transition Definition available for the definition of a Status Transition. When the Hide
operation is performed on a Status Transition Definition, the Status Transition Definition is flagged
as IsHidden.
Unhide
You can restore the visibility of a hidden Status Transition Definition by performing the Unhide
operation.
Allows you to export selected entities and instances in an export package that can be downloaded
locally and imported afterwards.
Export
See How To Export and Import Data for information about runtime data exchange and Exporting and
Importing Entity Life Cycle and State Machine Data for further information on the import sequence of
Entity Life Cycle and State Machine data.
3.7.2.4 Configuring Status Behavior Definitions

A Status Behavior Definition is a list of custom Status Behaviors that can be associated to one or more states of a
State Machine.
Each Status Behavior can be associated to one or more states of a specific State Machine.
Adding a Status Behavior Definition

1. Do either of the following to open the Status Behavior Definitions page:
• Click the Status Behavior Definitions home tile.
• Click Status Management in the side menu bar and click Status Behavior Definitions.
2. Click .

Manufacturing Apps
Reference App
Id The unique identifier assigned to the Status Behavior Definition. Once

the Status Behavior Definition is created, the Id value cannot be
modified.
Name (Optional) The name assigned to the Status Behavior Definition.
Description (Optional) Additional information on the Status Behavior Definition.

4. Click Save. The new Status Behavior Definition is created and displayed in the Status Behavior Definitions grid.
Additional operations on Status Behavior Definitions

On the existing Status Behavior Definitions you can then perform the following operations, by selecting the Status
Behavior Definition and clicking the proper icon.
Edit Allows you to modify Name and Description of the Status Behavior
Definition.
Delete Allows you to permanently remove a Status Behavior Definition. If you delete
a Status Behavior Definition, any relationships with all the Statuses
associated to it will also be deleted.
Export
State Machine data.
3.7.2.5 Configuring State Machines

A State Machine represents a lifecycle, defined by a set of Statuses, as instances of Status Definitions, as well as by a
set of Status Transition, which define the path between a source and a target Status, identifying it by means of a
Verb selected from the list of available Status Transition Definitions.
Instantiating a Status from a Status Definition results in the entity inheriting a set of attributes from the Status
Definition, such as Name and Description, which can be customized if necessary.
Additionally, a Status can be associated to one or more Status Behavior to give it a business relevant meaning.
When the list of the required Statuses of a State Machine is defined, it is also necessary to define all the relevant
Status Transitions between a source and a target Status. For each Status Transition defined, it is possible to
instruct the system to raise an event whenever the related change of state occurs.
Prerequisites
The required Status Definitions, Status Behavior Definitions and Status Transition Definitions have been
previously created.

Manufacturing Apps
Reference App
Workflow
1. Add a State Machine.
2. Assign Status to the State Machine.
3. Add a Status Transition to the State Machine.
Adding a State Machine

1. Do either of the following to open the State Machines page:
• Click the State Machines home tile.
• Click Status Management in the side menu bar and click State Machines.
2. Click .
Id The unique identifier assigned to the State Machine. Once the State
Machine is created, the Id value cannot be modified.
Name (Optional) The name assigned to the State Machine.
Description (Optional) Additional information on the State Machine.

4. Click Save. The new State Machine is created and displayed in the State Machines page.
 Once the first State Machine is created, the State Machine page is available by selecting the State Machine
and by clicking . Here other State Machines can be created from the Overview tab.
Additional operations on State Machines

On the existing State Machine you can then perform the following operations, by selecting from the Overview tab,
the State Machine and clicking the proper icon.
Edit Allows you to modify Name and/or Description of the State Machine.
The Status Definition must not be flagged as IsFrozen.
Freeze/ Unfreeze The Freeze operation allows you to configure a State Machine as read-only, in
order that it cannot be edited. When the Freeze operation is performed on an
entity, the State Machine is flagged as IsFrozen.
 • If a State Machine is frozen, all the Statuses and the State

Transitions related to that State Machine are frozen as well.
• If a State Machine is unfrozen, all the Statuses and the State
Transitions related to that State Machine are unfrozen as well.

Manufacturing Apps
Reference App
Hide/ Unhide The Hide operation allows you to prevent a State Machine from being
displayed among the State Machines available for the definition of a lifecycle.
When the Hide operation is performed on a State Machine, the State Machine
is flagged as IsHidden.
You can restore the visibility of a hidden State Machine by performing the
Unhide operation.
 • If a State Machine is hidden, all the Statuses and the State

Transitions related to that State Machine are hidden as well.
• If a State Machine is unhidden, all the Statuses and the State
Transitions related to that State Machine are unhidden as well.
Delete Allows you to permanently remove a State Machine.
Export Allows you to export selected entities and instances in an export package that
State Machine data.
Assigning Status to the State Machine

1. In the State Machines page, select a State Machine and click to open the State Machine page.
2. In the Statuses tab, click .
3. Select a Status Definition: the Name, the Description, the Color and the Outcome of the selected Status
Definition are automatically associated to the Status of the State Machine.
4. Click Save. The new Status is created and assigned to the State Machine.
 You can access the associated Statuses in the Statuses page by selecting the Status and by clicking .
Available Operations on Statuses assigned to State Machines

On the existing Statuses you can then perform the following operations, by selecting the Status and clicking the
proper icon.
Edit Allows you to modify Name, Description, Color and Outcome of the
Status. Outcome cannot be modified if the Status is flagged as
IsSystemDefined.

Manufacturing Apps
Reference App
Allows you to set the selected Status as the initial status of the State
Set Status as Initial
Machine.
Delete Allows you to permanently remove a Status. If you delete a Status,

any relationships with all the Status Behaviors associated to it will
also be deleted.
Adding a Status Transition to a State Machine
 To add a Status Transition at least two Status Definitions must have been created.
1. In the State Machines page, select a State Machine and click to open the State Machine page.
2. In the Transition tab, click .
Verb The previously defined action associated to the Status Transition.
Source Status The initial Status Definition of the Status Transition. Once the Status
Transition is created, the Source Status cannot be modified.
Target Status The target Status Definition of the Status Transition. Once the Status
Transition is created, the Target Status cannot be modified.
Do RaiseEvent Option to be selected if you want to raise an event when the transition
between the initial status and the target status occurs.
4. Click Save. The new Status Transition between the source Status and the target Status is created and displayed
in the Transition grid.
Available Operations on Transitions assigned to State Machines

On the existing Transitions you can then perform the following operations, by selecting the Transition and clicking
the proper icon.
Edit Allows you to modify the option Do RaiseEvent.

The Status must not be flagged as IsFrozen.
Delete Allows you to permanently remove a Status.
Audit Trail of a State Machine

Manufacturing Apps
Reference App
To display the Audit Trail of a State Machine, select the State Machine and then navigate to the Audit Trail tab.
The Audit Trail tab shows the list of all changes performed on the selected State Machine.
3.7.2.6 Exporting and Importing Entity Life Cycle and State Machine Data
section.

Example: If you want to import State Machine and Status Behavior Definition entities, and the State Machine
entities were exported by setting Include Descendants to False, you must first import the State Machine package
and then the Status Behavior Definition one.
 • System-defined State Machines (i.e. flagged as Is System Defined) cannot be exported

• State Machines are parent entities and their Statuses are automatically exported
State Status Status Notes

Machine Behavior
Definition
State Machine & If the State Machine is exported by

Status & Status setting Include Descendants to True, the
Behavior State Machine will be exported together with
Definition its Statuses, Status Transitions and State
Behavior Definitions associated to the
Statuses.
Note that the Status Behavior Definitions that
are not associated with the exported Status
will not be exported.
State Machine & If the State Machine is exported by

Status & Status setting Include Descendants to False:
Behavior
• the State Machine will be exported with its
Definition
Status
• the State Transition will not be exported.

Manufacturing Apps
Reference App
State Status Status Notes

Machine Behavior
Definition
Status Behavior If the export package contains Status Behavior

Definition Definitions associated to Statuses, the Statuses
must be already present in the target
environment.
Status & Status

Behavior
Definition
Status & Status

Behavior
Definition
Status
Status Definition Status Transition Notes

Definition
Status Definition
Status Transition
Definition
3.7.3 How to Manage Autonumbering

Autonumbering can be configured for all entities. By default, Opcenter Execution Foundation allows to configure
the pattern for properties, ids and names of the following entities:
• Material Lots in the Material App
• Material Tracking Units in the Material App
• Material Tracking Unit Aggregates in the Material App
• Tasks in the Task App
You can define the composition of your own Numbering Pattern, which can be made up of one or more of the
following Numbering Pattern Parts in any combination:
• Counter - a progressive numeric value which you have to configure.
• Constant - the constant value string of your choice.
• Timestamp - the string representing the point in time when this numbering pattern part is generated.
• Parameter - the property of the entity whose value will be used within the Numbering Pattern.
If you create a new entity instance, you can use the Numbering Pattern to generate both the Id and the Name
properties.
If you update an existing entity instance, you can use the Numbering Pattern to only modify the Name property.

Manufacturing Apps
Reference App
 As the Id field must be unique, an error is thrown if its value already exists. Consequently, when
configuring a numbering pattern to be used for the Id field, you should ensure that the chosen
combination for the associated numbering pattern will generate unique strings, such as including a
Counter as part of the numbering pattern. For the same reason, pay attention when using the command
ResetCounter.
Workflow
1. Configure the Counters.
2. Configure the Numbering Patterns.
If needed, you can configure the autonumbering functionality for custom entities.
3.7.3.1 Configuring Counters

The Counter is one of the parts you can use within your Numbering Pattern. It allows you to generate an increasing
sequence of positive integers that can be incremented or reset according to predefined configuration values, based
on the settings configured in this page.
You can use the same Counter in more than one Numbering Pattern.
The Counter can be reset either when it reaches a specific value (Max Value), or at a specific time (Time Based
Reset) or a combination (the Counter is reset at the specified time if it has not already reached the maximum value,
or vice versa).
Procedure
Create a Counter doing either of the following:
• Create a Counter in the UI Application.
• Add the code required in the database initialization file (Dbinit.xml).
Creating a Counter in the UI Application

1. Do either of the following to open the Counters page:
• Click the Counters home tile.
• Click Autonumbering in the side menu bar and click Counters.
2. Click to add a new Counter.
Attributes Description
Id The unique identifier of the Counter.

Manufacturing Apps
Reference App
Attributes Description
Name The name assigned to the Counter.
Description Additional information on the Counter.
Enforced Sequencing If selected, enables the transactional behavior for counters. If the
creation command fails, the system rollback the progressive value
incremented by the Counter thus reusing the number after
command execution retry.
If not selected the system does not rollback the progressive value
incremented by the Counter thus further increasing the progressive
number after the command execution retry.
Seed The starting value of the Counter. The value must be positive or
equal to zero. The default value: 0.
Increment The incremental value added to the previous value. Only positive
values are supported. The default value: +1.
Max Value The highest value to be reached before the Counter is reset to its
seed. If not specified, it is never reset and a possible overflow error is
raised.
Leading Zeros If selected, enables zeros to be added before the first significant digit
in a numbering string. The default value: false.
Time Based Reset Defines when the reset takes place. The possible date formats are:
• yyyy, the Counter is automatically reset on the start of
a new calendar year.
• yyyy-MM, the Counter is automatically reset on the start
of a new calendar month.
• yyyy-ww, the Counter is automatically reset on the start
of a new calendar week.
The default value: an empty string.
4. Click Save. The new Counter is created.
Creating a Counter in the Dbinit.xml file

1. Open the database initialization file (Dbinit.xml).
2. Add the code required, as shown in the following example:

Manufacturing Apps
Reference App
<Entity type="Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.Counter">
<Property name="NId" kind="Plain" value="EntityCounter" />
<Property name="Name" kind="Plain" value="Entity Counter" />
<Property name="Description" kind="Plain" value="Entiy counter, 9 digit" />
<Property name="Seed" kind="Plain" value="1" />
<Property name="Increment" kind="Plain" value="1" />
<Property name="MaxValue" kind="Plain" value="99999999999" />
<Property name="LeadingZeros" kind="Plain" value="True" />
</Entity>
Available operations on Counters

On the existing Counters you can then perform the following operations, by selecting the Counter and clicking the
proper icon.
Edit If the Counter is not yet used in a Numbering Pattern, it allows you to modify
all the attributes of a Counter, apart from the Id.
If the Counter is already used in a Numbering Pattern, then it only allows you
to modify the Name, Description and Max Value of a Counter.
Reset To reset the Counter to its initial value (seed).
/ Freeze/Unfreeze The Freeze operation allows you to configure a Counter as read-only, so that it
cannot be edited. When the Freeze operation is performed on a Counter,
the Counter is flagged as IsFrozen.
/ Hide/Unhide The Hide operation allows you to prevent a Counter from being displayed
among the Counters available for the Numbering Pattern. When the Hide
operation is performed on a Counter, the Counter is flagged as IsHidden.
You can restore the visibility of a hidden Counter by performing the Unhide
operation.
Delete To permanently remove a Counter.
exchange and Exporting and Importing Autonumbering Configuration Data
for further information on the import sequence of Autonumbering
Configuration data.

Manufacturing Apps
Reference App
3.7.3.2 Configuring Numbering Patterns

A Numbering Pattern is made up of separate Numbering Pattern Parts (Counter, Constant, Timestamp and
Parameter) in any combination, and it is associated to a specific entity type.
Workflow
1. Define your Numbering Pattern doing either of the following:
• Configure Numbering Patterns in the UI Application.
2. Allocate Numbering Pattern Parts doing either of the following:
• Allocate Numbering Pattern Parts in the UI Application.
Adding a Numbering Pattern in the UI Application

1. Do either of the following to open the Numbering Patterns page:
• Click the Numbering Patterns home tile.

• Click Autonumbering in the side menu bar and click Numbering Patterns.
2. Click to add a new Numbering Pattern.
App Name The name of the App with the entity types to which you want to
apply the Numbering Pattern. You can choose one of the
following:
• Material
• Task
Entity Type The entity types to which the Numbering Pattern can be
applied. The entity types are filtered according to the selected
App Name.
The possible entity types are:
For the Material App:
• MaterialLot
• MaterialTrackingUnit
• MaterialTrackingUnitAggregate
For the Task App:
• Task
Destination Property The destination of the Numbering Pattern within the entity type.
The possible destination fields are:
• Id
• Name
Name The name assigned to the Numbering Pattern.
Description Additional information on the Numbering Pattern.

Manufacturing Apps
Reference App
4. Click Save. The new Numbering Pattern is created as an empty container and you must now add the Numbering
Pattern Parts as required.
 Once the first Numbering Pattern is created, the Numbering Pattern page is available by selecting the
Numbering Pattern and by clicking . Here other Numbering Patterns can be created from the
Overview tab.
Adding a Numbering Pattern in the Dbinit.xml file

2. Add the code required, as shown in the following example:
<Entity
type="Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPattern">
<Property name="NId" kind="Plain" value="NId" />
<Property name="Name" kind="Plain" value="Numbering Pattern Name" />
<Property name="Description" kind="Plain" value="Numbering Pattern
Description" />
<Property name="EntityTypeNId" kind="Plain" value="AppName.EntityType" />
</Entity>
Available operations on Numbering Patterns

On the existing Numbering Patterns you can then perform the following operations, by selecting the Numbering
Pattern and clicking the proper icon in the Overview tab.
Edit To modify Name, Description and Entity Type.
/ Freeze/Unfreeze The Freeze operation allows you to configure a Counter as read-only, so

that it cannot be edited. When the Freeze operation is performed on a
Counter, the Counter is flagged as IsFrozen.
You can remove the read-only setting by performing the Unfreeze operation
Delete To permanently remove a Numbering Pattern.
exchange and Exporting and Importing Autonumbering Configuration Data
for further information on the import sequence of Autonumbering
Configuration data.
Adding a Numbering Pattern Part in the UI Application

Manufacturing Apps
Reference App
1. In the Numbering Patterns page, select a Numbering Pattern and click to open the Numbering Pattern
page
2. In the Numbering Pattern Part tab, select the Numbering Pattern you want to add the Numbering Pattern Part.
3. Click .
4. Set one of the allowed Numbering Pattern Parts (the other three will be automatically disabled as they must be
configured one at a time):
• Constant: the constant value string of your choice.
• Counter: a progressive numeric value previously configured.
• Timestamp: the string representing the point in time when this numbering pattern part is generated.
The available options are: yyyy (year), yyyy-MM (year-month) and yyyy-ww (year-week number)
• Parameter: the property of the entity whose value will be used in the Numbering Pattern. The available
options vary according to the Entity Type the Numbering Pattern refers to:
Entity Parameters
Material Lot in the Material App • MaterialNId, the Id of the Material

associated to the Material Lot.
• MaterialRevision, the revision of the
Material associated to the Material Lot.
Material Tracking Unit in the Material App • MaterialNId, the Id of the Material
associated to the Material Tracking Unit.
Material associated to the Material
Tracking Unit.
Material Tracking Unit Aggregate in the • MaterialNId, the Id of the Material

Material App associated to the Material Tracking Unit
Aggregate.
Material associated to the Material
Work Order • MaterialNId, the Id of the Material

associated to the Work Order.
Material associated to the Work Order.
Work Order Operation • WorkOrderNId, the Id of the Work Order

associated to the Work Order Operation.
• OperationNId, the Id of the Operation
associated to the Work Order Operation.
• OperationRevision, the revision of the
Operation associated to the Work Order
Operation.
Task • TaskDefinitionNId, the Id of the Task

Definition associated to the Task.
• TaskDefinitionRevision, the revision of
the Task Definition associated to the Task.
5. Click Save. The new Numbering Pattern Part is created and added to your Numbering Pattern.
6. Repeat steps 3 to 5 to add all the required Numbering Pattern Parts to your Numbering Pattern.

Manufacturing Apps
Reference App
Adding a Numbering Pattern Part in the Dbinit.xml file

2. Define Numbering Pattern Parts that rely on Counters, Constant, Timestamp and Parameters, as follows:
 Parameters are already provided by the system. See Adding a Numbering Pattern Part in the UI
Application.
• Define Counters by adding the code required in the database initialization file, as shown in the following
example. Otherwise, you can configure Counters in the UI Application.
<Entity
type="Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.Counter">
<Property name="Description" kind="Plain" value="Entiy counter, 9
digit" />
</Entity>
• Define the Numbering Pattern Part by adding the code required in the database initialization file, as
shown in the following example. Pay attention that the supported Timestamp formats are: yyyy (year),
yyyy-MM (year-month) and yyyy-ww (year-week number). Otherwise, you can configure Numbering
Patterns Parts in the UI Application.

Manufacturing Apps
Reference App
<Entity
type=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPatternPa
rt">
<Property name="Counter" kind="SingleReferenceToParent">
<LogicalKey
entityType=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.Counter">
</LogicalKey>
</Property>
<Property name="NumberingPattern" kind="SingleReferenceToParent">
<LogicalKey
entityType=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPattern">
<Property name="EntityTypeNId" kind="Plain"
value="AppName.EntityType" />
</LogicalKey>
</Property>
<Property name="Sequence" kind="Plain" value="4" />
</Entity>
<Entity
type=
rt">
<Property name="Constant" kind="Plain" value="EntityName_" />
<LogicalKey
entityType=
</LogicalKey>
</Property>
</Entity>
<Entity
type=
rt">
<Property name="Timestamp" kind="Plain" value="yyyy-ww" />
<LogicalKey
entityType=
</LogicalKey>
</Property>

Manufacturing Apps
Reference App

</Entity>
<Entity
type=
rt">
<Property name="ParameterNId" kind="Plain" value="Parameter" />
<LogicalKey
entityType=
</LogicalKey>
</Property>
</Entity>
Available Operations on Numbering Pattern Parts

On the existing Numbering Pattern Part you can then perform the following operations, by selecting the Numbering
Pattern Part and clicking the proper icon.
Edit To modify the selection of the Numbering Pattern Part.
Delete To permanently remove a Numbering Pattern Part.
Move To move the selected Numbering Pattern Part up one position in the grid (in the string generated
up this corresponds to the Numbering Pattern Part moving one position to the left).
Move To move the selected Numbering Pattern Part down one position in the grid (in the string
down generated this corresponds to the Numbering Pattern Part moving one position to the right).
Audit Trail of a Numbering Pattern
To display the Audit Trail of a Numbering Pattern, select the Pattern and then navigate to the Audit Trail tab.
The Audit Trail tab shows the list of all changes performed on the selected Numbering Pattern.

Manufacturing Apps
Reference App
3.7.3.3 Configuring Autonumbering for Custom Entities

Here is an outline of the main steps required to configure a Numbering Pattern for a custom entity and a Numbering
Pattern Part for NId and/or Name entity parameter. We provide you some code examples in order to help you in
understanding and applying the autonumbering functionality in case of custom entities. Pay attention that the
examples need to be customized before using.
For a better comprehension, let's consider the following example of entity and the related command.
Procedure
2. Add the code required to customize App Name and Entity Type fields in the Numbering Pattern Management
page > Add dialog box, as shown in the following example.

Manufacturing Apps
Reference App
<Entity
type=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPatternEntity">
<Property name="NId" kind="Plain" value="AppName.EntityType" />
</Entity>
<Entity
type=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPatternEntityIn
fo">
<Property name="AppName" kind="Plain" value="AppName" />
<Property name="EntityName" kind="Plain" value="EntityType" />
<Property name="NumberingPatternEntityNId" kind="SingleReferenceToParent">
<LogicalKey
entityType=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPatternEntity">
</LogicalKey>
</Property>
</Entity>
3. Define Numbering Patterns by adding the code required in the database initialization file, as shown in the
following example. Otherwise, you can configure Numbering Patterns in the UI Application.
<Entity
type="Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPattern">
<Property name="Name" kind="Plain" value="Numbering Pattern Name" />
<Property name="Description" kind="Plain" value="Numbering Pattern
Description" />
<Property name="EntityTypeNId" kind="Plain" value="AppName.EntityType" />
</Entity>
4. Define Numbering Pattern Parts that rely on Counters, Constant, Timestamp and Parameters, as follows:
• Define Parameters by adding the code required in the database initialization file, as shown in the
following example.

Manufacturing Apps
Reference App
<Entity
type=
rameter">
<Property name="NumberingPatternEntity" kind="SingleReferenceToParent">
<LogicalKey
entityType=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPatternEn
tity">
</LogicalKey>
</Property>
<Property name="NId" kind="Plain" value="Parameter1" />
</Entity>
<Entity
type=
rameter">
<Property name="NumberingPatternEntity" kind="SingleReferenceToParent">
<LogicalKey
entityType=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.NumberingPatternEn
tity">
</LogicalKey>
</Property>
<Property name="NId" kind="Plain" value="Parameter2" />
</Entity>
• Define Counters by adding the code required in the database initialization file, as shown in the following
example. Otherwise, you can configure Counters in the UI Application.
<Entity
type="Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.Counter">
<Property name="Description" kind="Plain" value="Entiy counter, 9
digit" />
</Entity>
• Define the Numbering Pattern Part by adding the code required in the database initialization file, as
shown in the following example. Pay attention that the supported Timestamp formats are: yyyy (year),
yyyy-MM (year-month) and yyyy-ww (year-week number). Otherwise, you can configure Numbering
Patterns Parts in the UI Application.

Manufacturing Apps
Reference App
<Entity
type=
rt">
<Property name="Counter" kind="SingleReferenceToParent">
<LogicalKey
entityType=
"Siemens.SimaticIT.ReferenceData.UDM_RF.RFModel.DataModel.Counter">
</LogicalKey>
</Property>
<LogicalKey
entityType=
</LogicalKey>
</Property>
</Entity>
<Entity
type=
rt">
<Property name="Constant" kind="Plain" value="EntityType_" />
<LogicalKey
entityType=
</LogicalKey>
</Property>
</Entity>
<Entity
type=
rt">
<Property name="Timestamp" kind="Plain" value="yyyy-ww" />
<LogicalKey
entityType=
</LogicalKey>
</Property>

Manufacturing Apps
Reference App

</Entity>
<Entity
type=
rt">
<Property name="ParameterNId" kind="Plain" value="Parameter1" />
<LogicalKey
entityType=
</LogicalKey>
</Property>
</Entity>
<Entity
type=
rt">
<Property name="ParameterNId" kind="Plain" value="Parameter2" />
<LogicalKey
entityType=
</LogicalKey>
</Property>
</Entity>
5. Open the <CommandName>Handler.cs file for Create and/or Update commands.

6. Add the code required to get numbering pattern parts and replace parts with the corresponding value, as shown
in the following example.

Manufacturing Apps
Reference App
private CreateEntityType.Response CreateEntityNameHandler(CreateEntityType

command)
{
var entityTypeInstance= platform.Create<IEntityType>();
entityTypeInstance.Prop1 = command.Prop1;
entityTypeInstance.Prop2 = command.Prop2;
// autonumbering usage for NId and Name
try
{
//get Numbering Pattern Part for EntityType NId
var nPart= platform.ProjectionQuery<INumberingPattern>()
.Include("NumberingPatternParts")
.Include("NumberingPatternParts.Counter")
.Where(np => (np.EntityTypeNId == "EntityType"))
.FirstOrDefault(np => np.NId == "NId");
// after Numbering Pattern Part is retrieved, you need to calculate/evaluate
all parts
// for example, if the pattern is a constant and a counter
IList<INumberingPatternPart> numberingPatternPartsOrdered =
nPart.NumberingPatternParts.OrderBy(npp => npp.Sequence).ToList();
var sb = new StringBuilder();
foreach (var numberingPatternPart in numberingPatternPartsOrdered)
{
if (numberingPatternPart.Constant != null)
{
sb.Append(numberingPatternPart.Constant);
continue;
}
if (numberingPatternPart.Counter != null)
{
var counter = numberingPatternPart.Counter;
var value = platform.Counters.GetNext(counter.NId,
counter.Seed.GetValueOrDefault(), counter.Increment.GetValueOrDefault());
sb.Append(value);
continue;
}
}
entityTypeInstance.NId = sb.ToString();
}
catch (ArgumentException)
{
return new CreateEntityType.Response { Error = "Numbering pattern for
EntityType not exist" };
}
}

Manufacturing Apps
Reference App
3.7.3.4 Exporting and Importing Autonumbering Configuration Data

section.

Example: If you want to import Counters and Numbering Patterns , you must first import the Counters package and
then the Numbering Patterns package one.
• System-defined Counters (flagged as Is System Defined) cannot be exported.

• Counters are parent entities, child entities cannot be imported without their parents.
Counters Numbering Notes

Patterns
Counters
Counters & If Numbering Patterns are exported by

Numbering Patterns setting Include Descendants to True and
Counters are exported by setting Include
Descendants to False.

Process Apps
Business Process Flow App
4 Process Apps
The Opcenter Execution Foundation Process Apps are
• Business Process Flow App
• Task App
• Work Instruction App
4.1 Business Process Flow App

The BPFlow App provides pages where it is possible to manage business process flows in a user-friendly
environment.
• BPF_MS
• BPF_OP
• UDM_RF
• TSK_MS
• TSK_OP
• EQU_MS
• EQU_OP
What can I do in the Business Process Flow App?

• What are Business Process Flows? provides useful conceptual information.
• How to Manage Process Definitions describes the configuration workflow and procedures.
• How to Manage Work Processes describes how to create and execute work processes.
4.1.1 What are Business Process Flows?

Business Process Flows define the steps involved in processes, such as work order operations and equipment
cleaning.
The Business Process Flow App allows you to graphically construct and then execute these workflows, using the
artifacts available in your solution.
The App follows Business Process Modeling Notation (BPMN) 2.0 standards.
Concepts
Business Process Flows are based on the following:
• Process Templates - Master Data domain entities which act as templates for the creation of Process
Definitions.
• Process Context Definitions - Metadata which describes how to contextualize (i.e. link to operational entities)
runtime work processes.
• Process Definitions - Master Data domain entities that contain the information required to describe a specific
business process, which can be used in the Flow Editor. Process Definitions can optionally be based on Process
Templates and optionally linked to Process Contexts.

Process Apps
• Consistency Checks - In order to be deemed executable, Process Definitions must pass consistency checks in
the approval process. The user cannot decide which conditions should be included in these checks. The model
design of the Process Definition as well as its internal consistency and external consistency (references to other
entities) are verified.
• Flow Editor - a graphical editor used to create and modify BPMN Diagrams starting from a specific Process
Definition.
• Work Processes - Operational domain entities, which are used to execute instances of Process Definitions.
• Work Process Contexts - The actual context of a specific Work Process instance.
4.1.2 How to Manage Process Definitions

The creation of Process Definitions is made up of three main phases. First of all a Process Definition Template,
which can be reused as often as possible, is created. A more specific Process Definition, based on the generic
Process Template, is created.
Once the Process Definition has been correctly defined it can be transformed into a visually represented Process
Definition Flow in a user-friendly editor.
Limitations in defining IDs

Ids must begin with an alphabetical char (A-Z, a-z) or an underscore (_), without the keywords Contexts or
Parameters. The rest of the variable name can include numbers (0-9) as well. No other characters, spaces, symbols,
and punctuation marks are supported.
Workflow
1. Create Process Templates.
2. Create Process Definitions.
3. Define Process Flow Diagrams.
4.1.2.1 Creating Process Templates

Process Templates are templates for the definition of input/output parameters, which are inherited by all Process
Definitions that have used the process template as a starting point.
They can be system-defined or created by the user.
Process Definitions can be based on the default Process Template, on any selected Process Template or created
from scratch without a template.
Audit Trail is displayed in the Process Template page to provide evidence of all the operations that have been
carried out on a specific Process Template. Its records can be viewed by selecting the
particular Process Template and clicking on Audit Trail tab.
Workflow
1. Add a new Process Template.
2. Set a Process Template as default.
3. Add Process Template Parameters.

Process Apps
Available Operations on Process Templates

To modify Process Templates attributes, apart from the Id.

Edit
To delete the Process Template.

Delete

Export
downloaded locally and imported afterwards. See How to Export and Import Data.
Available Operations on Process Template Parameters

To modify Process Templates Parameters, apart from the Id.

Edit
To delete the Process Template Parameters.

Delete
4.1.2.1.1 Adding a New Process Template

Process Templates are templates for the definition of input/output parameters, which are inherited by all Process
Definitions that have used the process template as a starting point.
Procedure
1. Do either of the following to open the Process Templates page:
• Click the Process Templates home tile.

• Click Process Engineering in the side menu bar and click Process Templates.
2. In the Process Templates page, click .
3. Insert a mandatory unique Id for the new Process Template.
4. Enter an optional name and description.
5. Click Save. The new Process Template is displayed in the Process Templates page.
 The Process Templates page provides common functionalities such as Group By, Quick
Search, Filter and User Preferences. The Filter functionality provides a more refined search in
addition to Quick Search. You can filter Process Templates by Id, Name, Description, Is Default and Is
System Defined.
4.1.2.1.2 Setting a Process Template as Default

A Process Template can be set as default in order to facilitate the creation of Process Definitions based on Process
Templates, as the user does not need to explicitly define which template to use.

Process Apps
Only one Process Template at a time can be set to default, so whilst this operation cannot be undone, it is sufficient
to set a different Process Template to default to remove this option.
It is not mandatory to set a default Process Template.
Procedure

2. In the Process Templates page, click on the Process Template you want to set as default.
3. Click .
4.1.2.1.3 Adding Process Template Parameters

Parameters can be set for Process Templates, which are then inherited by all Process Definitions based on the
template.
However, as no dynamic link is created between the Process Template and Process Definition, these parameters
can subsequently be modified. Any modifications made to these parameters will not have any impact on other
Process Definitions based on the same Process Template.
Procedure

2. In the Process Templates page, select a Process Template and click to open the Process Template page.
3. Click the Parameters tab.
4. Click .
5. For each Process Template Parameter add the following information:
Id The unique identifier assigned to the Process Template Parameter.

Once created, the Id value cannot be modified.
 The Process Template Parameter Id must follow the

defined limitations.
Type The data type of the Process Template Parameter value. The
following data types are
supported: Bigint, Bool, Datetime, Decimal, GUID, Int, Quantity,
Smallint, String, Tinyint.
Unit of Measure It represents the base unit for measuring a physical quantity (such as
meter, kilogram). This is enabled only when Process
Template Parameter's Type is Quantity.

Process Apps
Value (Optional) The default value of the Process Template Parameter,

displayed at runtime. If you select the Read Only option, this value
cannot be overwritten at runtime. Depending on the Type selected, a
description of the format is provided next to the Value label for Bool,
Datetime and Guid. If this field is left blank when updating the value,
it will be set to null.
 If the value is not compliant with the data type (for example,
if an integer is supplied as a value for a Bool data type) the
Process Template Parameter cannot be saved.
The maximum number of characters for a string value is 255.
Direction Set to Input, Output, or Input/Output.
Read only If selected, indicates that the value of the parameter cannot be
modified or deleted when inherited by a Process Definition.
6. Click Save.
4.1.2.2 Creating Process Definitions

Process Definitions contain the information required to describe a specific business process, which can be used to
create Process Definition Models.
Audit Trail is displayed in the Process Definition page to provide evidence of all the operations that have been
carried out on the specific Process Definition. Its records can be viewed by selecting the particular Process
Definition and clicking on Audit Trail tab.
Workflow
1. Creating new Process Definitions
2. Creating a new revision of a Process Definition
3. Adding Process Definition Parameters
4. Setting a Process Definition to current
5. Locking a Process Definition
Edit To modify Process Definition attributes, apart from the Id.
To delete the Process Definition.

Delete
Export To export a Process Definition. It will be saved as a .bpmn file.

Process Apps
Set Current. To set to current specific Process Definition revisions.
Lock To lock or unlock specific Process Definition revisions.
Unlock
 Process Definitions support revision management. Each revision has a unique Id and a specific revision
number. All subsequent revisions of the same Process Definition will maintain this same Id.
4.1.2.2.1 Adding a New Process Definition

Process Definitions are part of the Business Process Flow and can be based on Process Templates.
There are three ways to create new Process Definitions:
Creation mode Details
From scratch The new Process Definition can be based on an existing Process
Template, or can be created totally from scratch.
By copying an existing Process Definition The newly created Process Definition inherits the attributes of the
original Process Definition, but has its own Id. The inherited
attributes, apart from the base Process Template, can be
modified and no dynamic link exists with is source Process
Definition.
By importing an existing Process Definition BPMN files can be imported, along with their parameters. If the
model was created in the Opcenter EX FN environment, its
contexts and context user fields will also be imported. If a BPMN
model is imported into an existing process definition model, the
template on which it was based will no longer be considered, and
any parameters, contexts and context user fields in the imported
files will overwrite the existing ones.
Creating a Process Definition from scratch

1. Do either of the following to open the Process Definitions page:
• Click the Process Definitions home tile.

• Click Process Engineering in the side menu bar and click Process Definitions.
2. In the Process Definitions page, click .
3. For each Process Definition enter the following information:

Process Apps
Attributes Definition
Id A mandatory Id to identify the Process Definition. It must begin

with a Latin character. Non Latin characters are not supported
for Id. Once defined, this value cannot be modified.
Revision A mandatory ID to identify the specific revision of the Process

Definition.
Use Default Template (Optional) If selected, the Process Definition will be based on
the Process Template defined as default.
Template Id (Optional) The Process Template on which the Process

Definition is based. If Use Default Template is selected, this
field is disabled.
Name An optional name for the Process Definition.
Description An optional description for the Process Definition.

4. Click Save. The new Process Definition is displayed in the Process Definitions page. You can now add or modify
Process Definition parameters.
Copying an existing Process Definition


2. In the Process Definitions page, select the Process Definition you want to copy.
3. Click Copy .
4. Enter a new Id for the copied Process Definition.
5. Enter a new revision number for the copied Process Definition.
6. Click Save. The new Process Definition is displayed in the Process Definitions page. You can now add or modify
Importing an existing Process Definition

2. In the Process Definitions page, click .
3. For each Process Definition enter the following information:

Process Apps
Id A mandatory Id to identify the Process Definition. Once defined, this

value cannot be modified.
Revision A mandatory number for the specific revision of the Process Definition.
Name An optional name for the Process Definition.
Description An optional description for the Process Definition.
4. Click on the browse icon in the Upload a bpmn file edit box a process definition model to import.
5. Click Save.
 If the uploaded bpmn file contains obsolete definitions for Work Center or Location in any user task
configuration, you will be notified that they have been removed from the model, and this information will
also be traced in ETW as a warning.
 Security Note
Bear in mind that after you have exported a Process Definition, strict measures should be taken to
guarantee that the exported information is correctly and securely stored until it is re-imported.
 If you are importing a BPMN file having the direction of parameter as Input/Output from version 3.1 or
earlier versions, then you must manually change the direction of parameter to Input/Output otherwise
the direction of parameter is saved as Input.
 The Process Definitions page provides common functionalities such as Group By, Quick
to Quick Search. You can filter Process Definitions by Id, Name, Revision and Is Current.
4.1.2.2.2 Creating a New Revision of a Process Definition

Revisions allow the user to decide when a specific revision of a Process Definition must be used.
Consequent revisions of the same Process Definition, with the same Id, can subsequently be created.
Parameters can be added to the new revision, and the parameters inherited from the original version can be
modified or deleted, without impacting the original revision in any way.
 Only one revision of each Process Definition can be current at any one time.
Procedure

Process Apps

2. In the Process Definitions page, select the Process Definition for which you want to create a new revision.
3. Click .
4. Enter a new revision ID.
5. Click Save.The new Process Definition is displayed in the Process Definitions page. You can now add or modify
4.1.2.2.3 Adding Process Definition Parameters

If Process Definitions are based on a Process template, they inherit its parameters, but these parameters can be
modified.
New parameters can also be created for a Process Definition.
Adding new Process Definition Parameters


2. In the Process Definitions page, select a Process Definition and click to open the Process Definition page.
3. Click the Parameters tab.
4. Click .
5. For each Process Definition Parameter add or modify the following information:
Id The unique identifier assigned to the Process Definition Parameter.

Once created, the Id value cannot be modified.
 The Process Definition Parameter Id must follow the

Type The data type of the Process Definition Parameter value. The
meter, kilogram). This is enabled only when Process
Definition Parameter's Type is Quantity.

Process Apps
Value (Optional) The default value of the Process Definition Parameter,

displayed at runtime. If you select the Read Only option, this value
cannot be overwritten at runtime. Depending on the Type selected, a
description of the format is provided next to the Value label for Bool,
Datetime and Guid. If this field is left blank when updating the value,
it will be set to null.
 If the value is not compliant with the data type (for

example, if an integer is supplied as a value for a Bool data
type) the Process Definition Parameter cannot be saved.
The maximum number of characters for a string value is
255.
Read only If selected, indicates that the default value of the parameter cannot
be modified or deleted at runtime.
6. Click Save. Parameters created for the Process Definition or those inherited from the Process Template are
listed in the Parameter tab.
Modifying existing Process Definition Parameters


3. Click the Parameters tab. Parameters that have been added to the Process Definition as well as those inherited
from the Process Template are displayed.
4. Select the parameter you want to modify from the list.
5. Click .
6. Modify the attributes as required. Only the Id cannot be modified.
7. Click Save.
4.1.2.2.4 Setting a Process Definition to Current

A specific revision of a Process Definition can be set as current in order to define which specific revision should be
used.
Only one revision for each Process Definition (i.e. all the revisions with the same Process Definition Id) may be set
the current at any one time.
You can remove this setting by clicking .
Procedure

Process Apps

2. In the Process Definitions page, select the Process Definition revision you want to set to current.
3. Click .
 This operation can also be performed from when configuring the Process Definition Model by selecting the
Process Definition and clicking Set Current.
4.1.2.2.5 Locking a Process Definition

A Process Definition revision can be locked in order to render it read-only, hence disabling all modifications and
deletion.
The only available operations for a locked process definition model, is to unlock the flow or export it.
Procedure

2. In the Process Definitions page, select the Process Definition revision you want to lock.
3. Click . Once locked, all operations and the relative icons will no longer be displayed and the only option
available will be to click to unlock the revision.
 This operation can also be performed from when configuring the Process Definition Model by selecting the
Process Definition and clicking .
BPMN entities cannot consequently be dragged and dropped onto locked process definition models, and
no changes can be made to the configuration of the elements or to the model itself.
4.1.2.2.6 Using Process Context Definitions

Process Contexts are structured tags, which can be associated to Process Definitions.
User fields with specific data types can be defined for each Process Context Definition, and values can be provided
for these user fields when they are created or at runtime during the configuration of the Work Process.
For example, in an ERP scenario, the following context user fields may be
defined: ERP_Order, Customer and Campaign.
Process Contexts can either be defined in two distinct ways:

Process Apps
Where How Advantages
From the BPF_MS Functional By populating the following base Allows contexts to be added to third-
Block entities in the dbinit file: party Functional Blocks
• ProcessContextDefinition Additional customization is possible to
• ProcessContextDefinitionUse improve query performance and
rField. provide property indexing by extending
the ContextEntityType.
Directly in the Business By using the Process Context Easy to use, with no code knowledge
Process Flow App Definition UI Screens provided by required.
the App
Provides the possibility to add
additional contexts without modifying
the underlying Functional Blocks.
For more information on the mentioned Functional Block, see BPF_MS Functional Block in the Opcenter Execution
Workflow
1. Create Process Contexts by either:
• Defining Process Contexts in Functional Blocks
• Defining Process Contexts in the Business Process Flow App
2. Associating Process Contexts to Process Definitions
4.1.2.2.6.1 Defining Process Contexts in Functional Blocks

Process contexts are structured tags, which can be associated to process definitions.
The information required to create process contexts is contained in two base entities in the BPF_MS Functional
Block (see also BPF_MS Functional Block in the Opcenter Execution Foundation Development and Configuration
Guide):
• ProcessContextDefinition
• ProcessContextDefinitionUserField
To ensure this association works correctly with third-party Functional Blocks, careful attention must be paid to the
structure of the two base entities.
A standard context entity type is provided, which can be physically or logically extended to allow further
customization, improve query performance and provide property indexing, if required.
ProcessContextDefinition
The structure of the ProcessContextDefinition base entity is as follows:
NId The unique identifier assigned to the Process Context Definition. Once

Process Apps
Name The name assigned to the Process Context Definition.
Description Additional information on the Process Context Definition.
ContextEntityType The value of the ContextEntityType can be one of the following:

• Siemens.SimaticIT.OperationalData.BPF_OP.OPModel.DataMode
l.IWorkProcessContext. At runtime, an instance of the Work Process
Context class will be created in the operational domain, with the user
fields as defined in the example below.
• NULL. At runtime no instances will be created in the operational
domain, but third-party Functional Blocks will be able to develop
their own logic using the parameter values passed.
• The full name of the physical extension (e.g.
Siemens.SimaticIT.<DomainName>.<FunctionalBlockName>.<Ac
ronym>Model.DataModel.<ExtendedEntityInterface>), defined in
a referenced Functional Block, of the IWorkProcessContext entity.
At runtime an instance of the extended class will be created in the
operational domain, with the custom user fields, as shown in the
example below. The values passed as context values will be used to
set the entity properties. If no values are passed, the value will be
NULL.
• The full name of the logical extension (facet) (e.g.
Siemens.SimaticIT.<DomainName>.<FunctionalBlockName>.<Ac
ronym>Model.DataModel.<ExtendedEntityInterface>), defined in
a referenced Functional Block, of the IWorkProcessContext entity.
At runtime an instance of the facet will be created in the operational
domain with the custom user fields, as shown in the example below.
The values passed as context values will be used to set the facet
properties. If no values are passed, the value will be NULL.
 The ProcessContextDefinition Id must follow the defined limitations.
The following is an example of a ProcessContextDefinition entity, where the ContextEntityType

is Siemens.SimaticIT.OperationalData.BPF_OP.OPModel.DataModel.IWorkProcessContext:
<Entity type="Siemens.SimaticIT.MasterData.BPF_MS.MSModel.DataModel.ProcessContex
tDefinition">
<Property name="NId" kind="Plain" value="ProcessDefinitionDataType" />
<Property name="Name" kind="Plain" value="ProcessDefinitionDataType" />
<Property name="Description" kind="Plain" value="Process Context Definition
with user fields each for type" />
<Property name="ContextEntityType" kind="Plain" value="Siemens.SimaticIT.Operat
ionalData.BPF_OP.OPModel.DataModel.IWorkProcessContext" />
<Property name="ProcessDefinitions" kind="ManyToManyReference" />
</Entity>
The following is an example of a ProcessContextDefinition entity, where the ContextEntityType is NULL:

Process Apps
tDefinition">
<Property name="NId" kind="Plain" value="ProcessDefinitionNULL" />
<Property name="Name" kind="Plain" value="ProcessDefinitionNULL" />
with Context Entity Type equal to NULL" />
<Property name="ContextEntityType" kind="Plain" value="NULL" />
</Entity>
The following is an example of a ProcessContextDefinition entity, where the ContextEntityType is an extended

entity:
tDefinition">
<Property name="NId" kind="Plain" value="ProcessDefinitionExtend" />
<Property name="Name" kind="Plain" value="ProcessDefinitionExtend" />
<Property name="Description" kind="Plain" value="Process Context Definition for
extended Work Process Context" />
ionalData.BPFLibOP.OPModel.DataModel.IMyWorkProcessContext" />
</Entity>
The following is an example of a ProcessContextDefinition entity, where the ContextEntityType is a logically

extended facet:
tDefinition">
<Property name="NId" kind="Plain" value="ProcessDefinitionFacet" />
<Property name="Name" kind="Plain" value="ProcessDefinitionFacet" />
Work Process Context Facet" />
ionalData.BPFLibOP.OPModel.DataModel.IMyFacetWorkProcessContext" />
</Entity>
ProcessContextDefinitionUserField
The structure of the ProcessContextDefinitionUserField base entity is as follows:
• NId, which acts as a unique identifier for the user field
• DefaultValue, a default value for the user field, which must be coherent with the specified DataType, even if it is
persisted as a string.
• DataType, the data type corresponds to same data types as those allowed for Task Parameters:
Data Type UserFieldType Example values and format
Bigint 5 -2^53 - 1 (-9007199254740991) to 2^53 - 1

(9007199254740991)

Process Apps
Data Type UserFieldType Example values and format
Bool 7 true/false
Datetime 8 yyyy-MM-dd HH:mm:ss, for example 2017-12-25

12:00:00

754-2008 standards.
Guid 9 according to the regular expression: ([a-f0-9]{8}

(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})
Int 4 -2^31 (-2,147,483,648) to 2^31-1 (2,147,483,647)
Smallint 3 -2^15 (-32,768) to 2^15-1 (32,767)
String 1 -
Tinyint 2 0 to 255
 The ProcessContextDefinitionUserField Id must follow the defined limitations.
The following is an example of ProcessContextDefinitionUserField entities:

Process Apps
tDefinitionUserField">
<Property name="NId" kind="Plain" value="PCDUFBool" />
<Property name="UserFieldValue" kind="Plain" value="false" />
<Property name="UserFieldType" kind="Plain" value="Bool" />
<Property name="ProcessContextDefinition" kind="SingleReferenceToParent">
<LogicalKey entityType="Siemens.SimaticIT.MasterData.BPF_MS.MSModel.DataModel
.ProcessContextDefinition_Siemens_SimaticIT_MasterData_BPF_MS_MSModel">
</LogicalKey>
</Property>
</Entity>
</Entity>
<Property name="NId" kind="Plain" value="PCDUFDatetime" />
<Property name="UserFieldValue" kind="Plain" value="2017-12-12T15:17:25" />
<Property name="UserFieldType" kind="Plain" value="Datetime" />
</LogicalKey>
</Property>
</Entity>
Database initialization (dbinit) file example

The following contains examples of
ProcessContextDefinition and ProcessContextDefinitionUserField entities, using the base entities, extended
entities and facets defined above as ContextEntityType:

Process Apps
<?xml version="1.0" encoding="utf-8" ?>

<Sections>
<Section engineeringLevel="LibraryFunctionalBlock" implementationName="MyImplementa
tion" domainName="MasterData">

tDefinition">
<Property name="Name" kind="Plain" value="ProcessDefinitionNULL" />
with Context Entity Type equal to NULL" />
</Entity>
tDefinition">
<Property name="Name" kind="Plain" value="ProcessDefinitionDataType" />
with user fields each for type" />
ionalData.BPF_OP.OPModel.DataModel.IWorkProcessContext" />
</Entity>
tDefinition">
<Property name="Name" kind="Plain" value="ProcessDefinitionExtend" />
extended Work Process Context" />
ionalData.BPFLibOP.OPModel.DataModel.IMyWorkProcessContext" />
</Entity>
tDefinition">
<Property name="Name" kind="Plain" value="ProcessDefinitionFacet" />
Work Process Context Facet" />
ionalData.BPFLibOP.OPModel.DataModel.IMyFacetWorkProcessContext" />
</Entity>

<Property name="NId" kind="Plain" value="PCDUFString" />
<Property name="UserFieldValue" kind="Plain" value="AAA" />
<Property name="UserFieldType" kind="Plain" value="String" />

Process Apps
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="PCDUFBool" />
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="PCDUFDatetime" />
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="PCDUFDecimal" />
<Property name="UserFieldValue" kind="Plain" value="123.456" />
<Property name="UserFieldType" kind="Plain" value="Decimal" />
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="PCDUFInt" />
<Property name="UserFieldValue" kind="Plain" value="123" />
<Property name="UserFieldType" kind="Plain" value="Int" />
</LogicalKey>

Process Apps
</Property>
</Entity>
<Property name="NId" kind="Plain" value="PCDUFString" />
<Property name="UserFieldValue" kind="Plain" value="ABC" />
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="MyBool" />
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="MyDatetime" />
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="MyDecimal" />
</LogicalKey>
</Property>
</Entity>

Process Apps
<Property name="NId" kind="Plain" value="MyInt" />

</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="MyGuid" />
<Property name="UserFieldValue" kind="Plain" value="B4EA46F7-40D8-42BD-9A4E-
D94BA407DD1C" />
<Property name="UserFieldType" kind="Plain" value="GUID" />
</LogicalKey>
</Property>
</Entity>
<Property name="NId" kind="Plain" value="MyString" />
</LogicalKey>
</Property>
</Entity>
</LogicalKey>
</Property>
</Entity>

Process Apps

</LogicalKey>
</Property>
</Entity>
</LogicalKey>
</Property>
</Entity>
</LogicalKey>
</Property>
</Entity>
D94BA407DD1C" />
</LogicalKey>
</Property>
</Entity>

Process Apps

</LogicalKey>
</Property>
</Entity>
</Section>
</Sections>
4.1.2.2.6.2 Defining Process Contexts in the Business Process Flow App

Process Contexts are structured tags, which can be associated to Process Definitions.
User fields with specific data types can be defined for each Process Context Definition, and values can be provided
for these user fields at runtime during the configuration of the Work Process.
Audit Trail is displayed in the Process Context Definition page to provide evidence of all the operations that have
been carried out on the specific Process Context Definition. Its records can be viewed by selecting the
particular Process Context Definition and clicking on Audit Trail tab.
 Process Contexts can be also be defined at Functional Block level.
Procedure
1. Do either of the following to open the Process Context Definitions page:
• Click the Process Context Definitions home tile.

• Click Process Engineering in the side menu bar and click Process Context Definitions.
2. In the Process Context Definitions page, click on .
Id The mandatory unique identifier of the process context.
 The Process Context Definition Id must follow the

Name An optional name for the process context.
Description Optional additional information on the process context.

3. Click Save.
4. Click on icon to navigate to Process Context Definition page.
5. Click the User Field tab.
6. Click , and enter the following information:

Process Apps
Id The mandatory unique identifier of the process context user field.
 The Process Context Definition User Field Id must follow

the defined limitations.
Type The data type of the user field. The following data types are
supported: Bigint, Bool, Datetime, Decimal, GUID, Int, Smallint,
String, Tinyint.
Value An optional value for the user field. This value can be set at runtime
during the configuration of the Work Process.
7. Click Save.
8. Repeat step 6 to create as many user fields as required for your process context definition. The new Process
Context will be displayed as a tile on the left hand side of the Process Context Definition page, along with any
Process Contexts that were defined in Functional Blocks.
 The Process Context Definition page provides common functionalities such as Group By, Quick Search,
Search. You can filter Process Context Definitions by Id, Name and Description.
Available Operations on Process Context Definitions

To modify Process Context Definitions attributes, apart from the Id.

Edit
To delete the Process Context Definition.

Delete

Export
downloaded locally and imported afterwards. See How to Export and
Import Data
4.1.2.2.6.3 Associating Process Contexts to Process Definitions

Contexts are structured tags, which can be associated to process definitions.
They are defined either:
• within Functional Blocks, or
• within the Business Process Flow App.
Procedure

Process Apps

3. Click the Context tab.
4. Click .
5. Select a context from the Process Context Definition drop down list.
6. Click Save.
 You can remove the association of the Process Definition to a Process Context Definition by selecting the
Process Context Definition in the Context tab and clicking Disassociate Process Context Definition.
4.1.2.3 Creating Process Definition Models

Process Definition Models are created using the Process Definition Editor, which provides the graphical elements
and toolboxes required to build up a workflow and allows the user to select, configure and link the elements
available from the Apps in the solution.
New flow objects, such as user activities and gateways, can be added to the Process Definition Model simply by
dragging and dropping them onto the canvas. You are then guided in the configuration of the flow object element
through appropriate toolboxes, which simplify the process of connecting these elements while respecting BPMN
standards.
The resulting models can be saved at engineering level or rendered executable if they satisfy the consistency checks
in the approval process.
Workflow
1. Add a new Process Flow Model. This involves:
• Configuring Start and End Events in a Process Definition Models.
• Configuring Timer Intermediate Event in a Process Definition Models.
• Configuring Gateways in Process Definition Models.
• Configuring User Tasks in Process Definition Models.
• Configuring Call Activities in Process Definition Models.
• Configuring Annotations in Process Definition Models.
• Transforming Events in Process Definition Models.
• Transforming Activities in Process Definition Models.
• Transforming Gateways in Process Definition Models
2. Set Process Definition Models as Executable.
 We suggest that you set at least 1366x768 screen resolution to better display the Process Definition Editor.
Available Operations on Process Definition Models

Edit To rename Process Definition Models.

Process Apps
To delete Process Definition Models.

Delete
Set Current To set a Process Definition Model to current in the same way as the
Process Definition itself.
• Lock To lock or unlock a Process Definition Model in the same way as the
Process Definition itself.
• Unlock
4.1.2.3.1 Adding a New Process Definition Model

Process Definition Models are built on Process Definitions in the Process Definition Editor.
A blank canvas is created, where BPMN 2.0 flow objects can be dragged and dropped, configured and connected
with sequence flows in order to create a working model.
Any inherent constraints are automatically applied by the Process Definition Editor to avoid making configuration
errors.
Available BPMN flow objects

Name Icon Description
Start The first element in the model, which indicates the

starting point of the process.
End The final element in the model, which indicates the end
of the process.
Timer Intermediate Event The Timer indicates a when a workflow must start,
either by specifying a particular date and time or by
specifying a countdown.
User Task A User Task is associated to a Task Definition, and

represents an action that an operator or a system must
carry out within the process definition flow.
Call Activity The Call Activity invokes a separate Process Definition.

Process Apps
Task Tasks represent activities that must be performed within

the Process Definition Model, but they are not
associated to any actual task definitions.
They can be used as placeholders for User Tasks during
the modeling phase, and can be included in imported/
exported models.
 No configuration is foreseen for tasks. You can

only give them custom ID and name.
Exclusive Gateway A gateway which selects a single outgoing sequence

flow based on configured condition expressions.
Inclusive Gateway A gateway which selects one or more outgoing sequence

flow based on configured condition expressions.
Parallel A condition-free gateway which represents a point in the

Gateway workflow where distinct two sequence flows are
followed simultaneously.
Available BPMN flow objects

Edge Two elements of BPMN flow present in the canvas can be connected to each other
with an edge. The edge can be resized or rearranged by dragging the waypoints
that appear by selecting the edge.
Text An annotation which adds written information to an element in the process

Annotation definition flow.
Procedure

2. Select a Process Definition from which you want to create a Process Definition Flow Diagram.
3. Click . If a diagram already exists for this Process Definition it will be opened, otherwise a blank canvas will
be displayed.

Process Apps
4. Drag and drop the required BPMN elements onto the canvas and configure the new element. Follow the specific
procedure for each element type:
• Start and Stop events
• Timer Intermediate Event
• Gateways
• User tasks
• Call activities
• Annotations
5. To connect elements with sequence flows, select the element and click on the blue icon which points towards
the next element. Then, drag the arrow to the next element.
6. Provide a name for the connecting sequence flow by selecting it and clicking . This avoids ambiguity when
configuring gateways.
7. When you are satisfied with your diagram, click .
 The label showing the name of the connecting sequence flow can be moved from the default position.
4.1.2.3.1.1 Configuring Start and End Events in Process Definition Models

Two events are used in Process Definition models:
• the Start event indicates where the Process Definition model will begin.
• the End event indicates where the Process Definition model will finish.
Every model must have a start and end event.
Start Each Process Definition must contain one, and only one, Start
Event, which is the first element in the process.
It does not have any predecessors, but can have any number of
successors.
End Each Process Definition must contain one, and only one, End Event,
which is the last element in the process.
It can have any number of predecessors, but no successors.
Procedure
1. In the Process Definition Editor, drag and drop the Start or End element onto the canvas.
2. If needed, modify the default ID and/or name of the element in the displayed dialog box and click Save.
3. Connect the Start event to its successor and the End event to its predecessor.
4. Click Save.
 The maximum number of characters for ID and name values is 255.

Process Apps
4.1.2.3.1.2 Configuring Timer Intermediate Events in Process Definition

Models
The Timer Intermediate Event (timer) is used in a process definition model to introduce a delay during the
execution of a process workflow by a defined time.
Timer Timers introduce a delay, the end of which can be configured

either by:
• selecting a date and time
• specifying a duration.
The following constraints apply:
• There must be at least one incoming sequence flow and one
or more outgoing sequence flows.
• The timer event must have a duration greater than 1 minute.
Procedure
1. In the Process Definition Editor, drag and drop the timer element onto the canvas.
3. Select the timer element and then click .

4. Select whether you want the timer to specify a time span (Duration) or particular time (Datetime).
5. Configure the timer in one of the following ways:
Configuration mode Description
UI guided approach For duration: Select the number of years, months, days, hours and/or
minutes the timer should expire. You can chose to specify only hours or
only minutes etc and the maximum value you can insert is 999. Seconds
cannot be specified and a default value of 00 is assigned. Then
click Generate duration.
For datetime: Specify the required date and time when the work process
should start. Seconds cannot be specified and a default value of 00 is
assigned. Then click Generate datetime.
Manually Insert an ISO 8601 compliant format value in the timer edit box
(PnYnMnDTnHnMnS for timespans and YYYYMMDDTHHMMSS for
datetimes). Validation checks are performed on all manually input
values.
Binding Select Process Content button, then select the required string or
datetime value and select Bind.

Process Apps
Configuration mode Description
Scripting Select Script button to insert custom code and click Bind.
A javascript formatAsISODuration (YYY, MMM, DDD, HHH, mmm) can be
used to facilitate this operation.
The function expresses a duration, which is then converted into an ISO
8601 format (i.e. PnnYnnMnnDTnnHnnMnnS).
Examples of use:
formatAsISODuration(1,3,7)
//Represents a duration of 1 year, 3 months and 7
days. It will be converted into the ISO format
'P1Y3M7D'.
formatAsISODuration(1,3,7,43,100)
//Represents a duration of 1 year, 3 months, 7 days,
43 hours and 100 minutes. It will be converted into
the ISO format 'P1Y3M7D43H100M'.
formatAsISODuration(MyYears, 4)
//Represents a duration where the years are defined
by the value represented by the bound variable
'MyYears', 4 months. It will be converted into the
ISO format 'P<MyYears>Y4M'.
Note that no validation checks are performed at this stage on custom

code.
6. Click Apply.
4.1.2.3.1.3 Configuring Gateways in Process Definition Models

Gateways control which sequence flows will be followed within a Process Definition Model. They do not perform
activities within the process, but control which activities will be performed according to condition expressions.
Process Definition Models can contain three different types of gateways:

Process Apps
Exclusive Gateway An exclusive gateway manages mutually exclusive alternative

paths in the process flow through conditional expressions.
Based on the result of the condition, only one of the outgoing
sequence flows will be followed.
• There must be at least one incoming and outgoing sequence
flow.
• There can be multiple incoming and outgoing sequence
flows, but only one outgoing sequence flow is followed
(mutually exclusive).
• There should be a default outgoing sequence flow, without
conditions, so that the workflow will not be blocked if the
conditions are not met. There should be no unconditioned
sequence flows besides the default one, but if there are they
are deemed true.
• Every time the process reaches an exclusive gateway an
execution is triggered, without waiting for input from each
incoming sequence flow.
Inclusive Gateway An inclusive gateway manages multiple alternative paths in the

process flow through conditional expressions.
Based on the result of the condition, one or more of the outgoing
sequence flows will be followed.
• There must be at least one incoming sequence flow and at
least one or more outgoing sequence flows, any number of
which may be followed.
• There should either be an outgoing sequence flow without a
condition or a default outgoing sequence flow.
Unconditioned sequence flows are followed.
• All executed incoming sequence flows must provide their
input before the inclusive gateway will trigger an execution.
Parallel A parallel gateway does not contain conditions, and simply

Gateway represents a point in the workflow where several outgoing
sequence flows and consequently several distinct activities will
be followed synchronously.
• There must be at least one incoming and outgoing sequence
flows.
• All incoming sequence flows must provide their input before
the parallel gateway triggers an execution.
 The Parallel Gateway does not require any specific

configuration, as it does not contain conditions.

Process Apps
Procedure
1. In the Process Definition Editor, drag and drop the Gateway element onto the canvas.
3. To facilitate the configuration of the gateway, select each outgoing sequence flow, click the edit icon and
provide a name for the sequence flow.
4. Only in case of Exclusive and Inclusive Gateways:
• Click the edit icon .
• Select an outgoing sequence flow, enter its condition using supported operators and data types in the
Condition edit box and click Set Condition using supported operators and data types.
 In the Scripting tab, the Unit of Measure of parameters is not managed. For this reason, the
supported operators/methods that are applied to a quantity data type parameter could result
in a not correct evaluation.
• (Exclusive gateway only) Modify the order in which each condition will be evaluated by using the Move
Up and Move Down buttons.
• Select the default outgoing sequence flow, which will be followed if none of the conditions are satisfied,
by checking Is Default on the corresponding row. A slash marker is displayed on the default sequence
flow. Any conditions specified for the sequence flow will be maintained, but not considered at runtime
for as long as the flow is set as default.
• Click Apply.
 The label showing the name of the connecting sequence flow can be moved from the default position.
4.1.2.3.1.4 Configuring User Tasks in Process Definition Models

Activities are the executable elements of a Process Definition Model.
User Tasks represent an action and are linked to a specific task definition.
Name Icon Description Constraints
User Task A User Task is associated to a Task There can be only one predecessor
Definition, and represents an action and one or more successors.
within the Process Definition flow.
A gateway of any kind can be inserted
before a User Task to model a merge
unambiguously.
Successors are executed in parallel.
Procedure
1. In the Process Definition Editor, drag and drop the User Task element onto the canvas.

Process Apps
3. Click the edit icon .

4. In the Association tab, associate the User Task to a Task Definition by clicking on the browse button next to
the Task Definition edit box and selecting a specific definition and version. If the version you have selected is
the current version it will be displayed in bold.
5. Provide values for Task Details, Input Parameters, Input/Output Parameters, Output Parameters and Task
Contexts in the Association tab, by clicking the corresponding tab, selecting the element to link and doing one
of the following:
 The Input/Output parameter is available in both Input and Output tabs for specifying input and
output values respectively.
• (not for output parameters) select Manual Edit button to enter a value in the text box and click
Assign. Validation checks are performed on all manually input values.
• (not for output parameters) select Script button to enter a javascript expression, using the supported
operators and data types and click Bind.
• select Process Content button, then select a value to bind with the selected element and click Bind.
Type Description Can be linked to:
Details Determine the source of the value to • A manually input value

be set for the task detail • Process Definition Contexts
user fields
• Process Definition Input or
Output parameters
• Input/output parameters and
context user fields of any
other element included in
the model
• Scripts
Input Determine the source of the value to • A manually input value

be set for the task input parameter • Process Definition Contexts
Output parameters
the model
• Scripts
Output Determine the destination, where the Process Definition output parameters
value will be set.

Process Apps
Type Description Can be linked to:
Context Determine the source of the value to • A manually input value

be set for the task context user fields. • Process Definition Contexts
Output parameters
the model
• Scripts
 When the data type of task input/output parameters is a quantity, the unit of measure is set in
the following ways:
- when inserting a manual value or script the UoM is selected from a drop down list
- when binding to another parameter or context user field, the UoM for the bound value is used,
and cannot be selected from a drop-down list.
In this way the source value always establishes the UoM.
6. In the Call tab, select One Way Asynch if you want the User Task to be performed asynchronously, so that the
workflow can continue and does not stop to wait for the end of the User Task.
7. If you want the User Task to be repeated more then once you can configure the looping behavior with
progressive complexity following these steps:
• Click the Loop tab.
• Select Looping: the Maximum Loops edit box will now be enabled. If looping is disabled, any looping
configuration is disabled but maintained.
• Specify how many times the loop can be repeated in the Maximum Loops edit box. The maximum
number of loops allowed is 9999. The Loop Condition edit box will now be enabled.
• Specify under which conditions the loop should be executed in the Loop Condition editor. The Execute
Before check box will now be enabled.
• Select Execute Before if you want any specified loop conditions to be evaluated before the loop
iteration is executed. By default loop conditions are evaluated after loop iteration execution.
8. Click Apply.
4.1.2.3.1.5 Configuring Call Activities in Process Definition Models

Call Activities invoke other Process Definition Models, as sub processes.
Name Icon Description Constraints
Call Activity The Call Activity invokes a separate A gateway of any kind can be
Process Definition, subscribing to the inserted before a user task to
event it triggers on completion in order model a merge unambiguously.
to resume the process.
There must be at least one
predecessor and successor.
In order to prevent excessive call
stacks the maximum number of
call stacks is 50.

Process Apps
Procedure
1. In the Process Definition Editor, drag and drop the Call Activity onto the canvas.
3. Click the edit icon .

4. In the Association tab, associate the Call Activity to a Process Definition by clicking on the browse button next
to the Process Definition edit box and selecting a specific definition and version. If the version you have
selected is the current version it will be displayed in bold.
5. Provide values for Process Definition Details, Input Parameters, Input/Output Parameters, Output Parameters
and Process Definition Contexts, in the Association tab, by selecting the element to link and doing one of the
following:
 The Input/Output parameter is available in both Input and Output tabs for specifying input and
output values respectively.
• (not for output parameters) select Manual Edit button to enter a value in the text box and click
Assign. Validation checks are performed on all manually input values.
• (not for output parameters) select Script button to enter a javascript expression, using the supported
operators and data types and click Bind.
• select Process Content button, then select a value to bind with the selected element and click Bind.
 Read-only elements are grayed out and cannot be modified.
Call Activity Binding Description Can be linked to:
Call Activity Details Determine the source of the value • A manually input value
to be set for the call activity • Process Definition
details. Contexts
• Process Definition
Input or Output
parameters
• Input/output
parameters and
context user fields of
any other element
included in the model
• Scripting

Process Apps
Call Activity Binding Description Can be linked to:
Input Parameters Determine the source of the value • A manually input value
to be set for the call activity input • Process Definition
parameters. Contexts
Input or Output
parameters
• Input/output
parameters and
any other element
• Scripting
Output Parameters Determine the destination, where Process Definition output

the value will be set for the output parameters
parameters.
Call Activity Contexts Determine the source of the value • A manually input value
User Fields to be set for the call activity • Process Definition
context user fields. Contexts
Input or Output
parameters
• Input/output
parameters and
any other element
• Scripts
 When the data type of process definition input/output parameters is a quantity, the unit of
measure is set in the following ways:
- when inserting a manual value or script the UoM is selected from a drop down list
- when binding to another parameter or context user field, the UoM for the bound value is used,
and cannot be selected from a drop-down list.
In this way the source value always establishes the UoM.
6. In the Call tab, select One Way Asynch if you want the Call Activity to be performed asynchronously, so that the
workflow can continue and does not stop to wait for the end of the Call Activity processes.
7. If you want the Call Activity to be repeated more then once you can configure the looping behavior with
progressive complexity following these steps:
• Click the Loop tab.
• Select Looping: the Maximum Loops edit box will now be enabled. If looping is disabled, any looping
configuration is disabled but maintained.
• Specify how many times the loop can be repeated in the Maximum Loops edit box. The maximum
number of loops allowed is 9999. The Loop Condition edit box will now be enabled.
• Specify under which conditions the loop should be executed in the Loop Condition editor. The Execute
Before check box will now be enabled.

Process Apps
• Select Execute Before if you want any specified loop conditions to be evaluated before the loop
iteration is executed. By default loop conditions are evaluated after loop iteration execution.
8. Click Apply.
4.1.2.3.1.6 Configuring Annotations in Process Definition Models

Text Annotation A text annotation adds written information to an

element in the process definition flow.
Procedure
1. In the Process Definition Editor, drag and drop the Text Annotation element onto the canvas.
2. Select the Text Annotation and click to modify the text displayed in the annotation.
3. Enter the new text.
4. Click outside the flow element to close it.
5. Click .
4.1.2.3.1.7 Operators and Data Types Supported for Conditions and

Scripting
You can use scripting in the following element configuration:
• user tasks and call activities (including loop conditions)
• gateways
• timer events
For these elements, a code autocomplete functionality is available in the Scripting tab.
Supported operators
The following arithmetic operators are supported:
• Addition +
• Subtraction -
• Multiplication *
• Division /
• Modulus %
• Increment ++
• Decrement --
The following comparison operators are supported:
• greater than >
• greater than or equal to >=
• less than <
• less than or equal to <=
• equal to ==
• not equal to !=
The following logical operators are supported:

Process Apps
• not !
• and &&
• or ||
Supported data types

The following data types are supported with the specified properties and methods:
Data type Properties Methods
String 0 Length: Returns the character at the • charAt(): Returns the character at the
specified index. specified index.
• charCodeAt(): Returns a number
indicating the Unicode value of the
character at the given index.
• concat(): Combines the text of two strings
and returns a new string.
• indexOf(): Returns the index within the
calling String object of the first occurrence
of the specified value, or -1 if not found.
• lastIndexOf(): Returns the index within the
calling String object of the last occurrence
of the specified value, or -1 if not found.
• * localeCompare(): Returns a number
indicating whether a reference string
comes before or after or is the same as the
given string in sort order.
• slice(): Extracts a section of a string and
returns a new string.
• split(): Splits a String object into an array
of strings by separating the string into
substrings.
• substr(): Returns the characters in a string
beginning at the specified location
through the specified number of
characters.
• substring(): Returns the characters in a
string between two indexes into the string.
• * toLocaleLowerCase(): The characters
within a string are converted to lower case
while respecting the current locale.
• * toLocaleUpperCase(): The characters
within a string are converted to upper case
while respecting the current locale.
• toLowerCase(): Returns the calling string
value converted to lower case.
• toString(): Returns a string representing
the specified object.
• toUpperCase(): Returns the calling string
value converted to uppercase.

Process Apps
Number • MAX_VALUE: Returns the largest • isFinite(): Checks whether a value is a

number possible in JavaScript finite number
• MIN_VALUE: Returns the smallest • isNaN(): Checks whether a value is
number possible in JavaScript Number.NaN
• NEGATIVE_INFINITY: Represents • Number.isInteger(): Checks whether a
negative infinity (returned on value is an integer
overflow) • toExponential(x): Converts a number into
• NaN: Represents a "Not-a-Number" an exponential notation
value • toFixed(x): Formats a number with x
• POSITIVE_INFINITY: Represents numbers of digits after the decimal point,
infinity (returned on overflow) returning a string
• toPrecision(x): Formats a number to x
length, returning a string
• toString(): Converts a number to a string
Boolean N/A N/A
Math • E: Returns Euler's number (approx. • abs(x): Returns the absolute value of x
2.718) • acos(x): Returns the arccosine of x, in
• LN2: Returns the natural logarithm radians
of 2 (approx. 0.693) • asin(x): Returns the arcsine of x, in radians
• LN10: Returns the natural logarithm • atan(x): Returns the arctangent of x as a
of 10 (approx. 2.302) numeric value between -PI/2 and PI/2
• LOG2E: Returns the base-2 radians
logarithm of E (approx. 1.442) • atan2(y, x): Returns the arctangent of the
• LOG10E: Returns the base-10 quotient of its arguments
logarithm of E (approx. 0.434) • ceil(x): Returns x, rounded upwards to the
• PI: Returns PI (approx. 3.14) nearest integer
• SQRT1_2: Returns the square root • cos(x): Returns the cosine of x (x is in
of 1/2 (approx. 0.707) radians)
• SQRT2: Returns the square root of 2 • exp(x): Returns the value of Ex
(approx. 1.414) • floor(x): Returns x, rounded downwards to
the nearest integer
• log(x): Returns the natural logarithm (base
E) of x
• max(x, y, z, ..., n): Returns the number with
the highest value
• min(x, y, z, ..., n): Returns the number with
the lowest value
• pow(x, y): Returns the value of x to the
power of y
• random(): Returns a random number
between 0 and 1
• round(x): Rounds x to the nearest integer
• sin(x): Returns the sine of x (x is in radians)
• sqrt(x):Returns the square root of x
• tan(x): Returns the tangent of an angle

Process Apps
Datetime N/A • Date.now() : Returns the number of

milliseconds since midnight Jan 1, 1970
• Date.parse() Parses a date string and
returns the number of milliseconds since
January 1, 1970
• Date.UTC() Returns the number of
milliseconds in a date since midnight of
January 1, 1970, according to UTC time
• getDate() Returns the day of the month
(from 1-31)
• getDay() Returns the day of the week
(from 0-6)
• getFullYear() Returns the year
• getHours() Returns the hour (from 0-23)
• getMilliseconds() Returns the milliseconds
(from 0-999)
• getMinutes() Returns the minutes (from
0-59)
• getMonth() Returns the month (from 0-11)
• getSeconds() Returns the seconds (from
0-59)
• getTime() Returns the number of
milliseconds between midnight Jan 1
1970, and a specified date
• getTimezoneOffset() Returns the time
difference between UTC time and local
time, in minutes
• getUTCDate() Returns the day of the
month, according to universal time (from
1-31)
• getUTCDay() Returns the day of the week,
according to universal time (from 0-6)
• getUTCFullYear() Returns the year,
according to universal time
• getUTCHours() Returns the hour,
• getUTCMilliseconds() Returns the
milliseconds, according to universal time
(from 0-999)
• getUTCMinutes() Returns the minutes,
• getUTCMonth() Returns the month,
• getUTCSeconds() Returns the seconds,
• setDate() Sets the day of the month of a
date object
• setFullYear() Sets the year of a date object
• setHours() Sets the hour of a date object

Process Apps

• setMilliseconds() Sets the milliseconds of a
date object
• setMinutes() Set the minutes of a date
object
• setMonth() Sets the month of a date object
• setSeconds() Sets the seconds of a date
object
• setTime() Sets a date to a specified
number of milliseconds after/before
January 1, 1970
• setUTCDate() Sets the day of the month of
a date object, according to universal time
• setUTCFullYear() Sets the year of a date
object, according to universal time
• setUTCHours() Sets the hour of a date
• setUTCMilliseconds() Sets the
milliseconds of a date object, according to
universal time
• setUTCMinutes() Set the minutes of a date
• setUTCMonth() Sets the month of a date
• setUTCSeconds() Set the seconds of a date
• toDateString() Converts the date portion
of a Date object into a readable string
• toISOString() Returns the date as a string,
using the ISO standard
• toJSON() Returns the date as a string,
formatted as a JSON date
• toLocaleDateString() Returns the date
portion of a Date object as a string, using
locale conventions
• toLocaleTimeString() Returns the time
portion of a Date object as a string, using
locale conventions
• toLocaleString() Converts a Date object to
a string, using locale conventions
• toString() Converts a Date object to a
string
• toTimeString() Converts the time portion
of a Date object to a string
• toUTCString() Converts a Date object to a
string, according to universal time

Process Apps
Global • Infinity A numeric value that • decodeURI() Decodes a URI

represents positive/negative infinity • decodeURIComponent() Decodes a URI
• NaN "Not-a-Number" value component
• undefined Indicates that a variable • encodeURI() Encodes a URI
has not been assigned a value • encodeURIComponent() Encodes a URI
component
• isFinite() Determines whether a value is a
finite, legal number
• isNaN() Determines whether a value is an
illegal number
• Number() Converts an object's value to a
number
• parseFloat() Parses a string and returns a
floating point number
• parseInt() Parses a string and returns an
integer
• String() Converts an object's value to a
string
4.1.2.3.1.8 Transforming Events in Process Definition Models

In a Process Definition Model, an event (Start Event, End Event or Timer Intermediate Event) can be transformed
into another event, as described below.
From From Icon To To Icon
Start event End event
Timer event
End event Start event
Timer event
Timer event Start event
End event

Process Apps
Since there can only be one Start Event and one End Event in a Process Definition Model
• You cannot transform any Event to Start Event when a Start Event already exists.
• You cannot transform any Event to End Event when an End Event already exists.
Procedure
1. In the Process Definition Editor, select the event in the canvas.
2. Click .
3. From the drop down list box, select the target event of the transformation you want to perform.
4. Configure the target event as described in Configuring Start and End Events in Process Definition Models
or Configuring Timer Intermediate Events in Process Definition Models.
Loss of configuration while transforming events

Event transformations can cause loss of configuration. In such cases, a warning popup will appear asking you for
confirmation. The table below shows whether the warning popup will appear and how edges are transformed.
From To Warning Note
Start Event End Event No Outgoing edges are deleted.
Start Event Timer Event No Outgoing edges are maintained.
End Event Start Event No Incoming edges are deleted.
End Event Timer Event No Incoming edges are maintained.
Timer Event Start Event Yes Outgoing edges are maintained while
incoming edges are deleted.
Timer Event End Event Yes Outgoing edges are deleted while incoming
edges are maintained.
4.1.2.3.1.9 Transforming Activities in Process Definition Models

In a Process Definition Model, an activity (Task, User Task or Call Activity) can be transformed into another activity,
as described below.
Task User Task
Call Activity

Process Apps
User Task Task
Call Activity
Call Activity User Task
Task
Procedure
1. In the Process Definition Editor, select the activity in the canvas.
2. Click .
3. From the drop down list box, select the target activity of the transformation you want to perform.
4. Configure the target activity as described at pages Configuring Call Activities in Process Definition Models or
Configuring User Tasks in Process Definition Models (for Tasks, see description in Adding a New Process
Definition Model).
Loss of configuration while transforming activities

Activity transformations can cause loss of configuration. In such cases, a warning popup will appear asking you for
confirmation. The table below shows whether the warning popup will appear.
Task User Task No A task has no

configuration to be
maintained.
Task Call Activity No A task has no

configuration to be
maintained.
User Task Task Yes All the configuration is

lost.
User Task Call Activity Yes Only loop and call

configuration is
maintained.
Call Activity Task Yes All the configuration is

lost.

Process Apps
Call Activity User Task Yes Only loop and call

configuration is
maintained.
 In all of the activity transformations, all the incoming and outgoing edges are maintained.
4.1.2.3.1.10 Transforming Gateways in Process Definition Models

In a Process Definition Model, a gateway (Exclusive Gateway, Inclusive Gateway or Parallel Gateway) can be
transformed into another gateway, as described below.
Exclusive Gateway Parallel

Gateway
Inclusive
Gateway
Inclusive Gateway Parallel

Gateway
Exclusive
Gateway
Parallel Gateway Exclusive

Gateway
Inclusive
Gateway
Procedure
1. In the Process Definition Editor, select the gateway in the canvas.
2. Click .
3. From the drop down list box, select the target gateway of the transformation you want to perform.
4. Configure the target gateway as described in Configuring Gateways in Process Definition Models.
Loss of configuration while transforming gateways

Gateway transformations can cause loss of configuration. In such cases, a warning popup will appear asking you for
confirmation. The table below shows whether the warning popup will appear.

Process Apps
Exclusive Parallel Yes As parallel gateway is not configurable, no

Gateway Gateway configuration is maintained.
Exclusive Inclusive No All configuration is maintained. But, ordering of

Gateway Gateway conditions will not be available after the
transformation
Inclusive Parallel Yes As parallel gateway is not configurable, no

Gateway Gateway configuration is maintained.
Inclusive Exclusive No All the configuration is maintained.

Gateway Gateway
Parallel Gateway Exclusive No As parallel gateway is not configurable, no

Gateway configuration will be available to maintain.
Parallel Gateway Inclusive No As parallel gateway is not configurable, no

Gateway configuration will be available to maintain.
 In all of the gateway transformations, all the incoming and outgoing edges are maintained.
4.1.2.3.2 Setting Process Definition Models as Executable

When a Process Definition Model is set as executable a series of consistency checks are performed.
Consistency Checks define the conditions that must be satisfied before a Process Definition Model can be deemed
ready for execution.
If all the consistency checks are not satisfied a set of corresponding errors or warnings will be returned as a list of
messages. Errors will not permit the model to be set as executable, while warnings will not block this process.
Available consistency checks

Constraint Type
Variables must have a valid dot separated alphanumeric ID with a valid scope. Error
All Task Definitions and Process Definitions referenced in the flow diagram exist. Error
Used parameters are present in the Task Definition Parameters and their read-only Error
settings, direction and datatypes match.
A used parameter is present in the Task Definition Parameters, matching read-only setting Warning
and datatype, but its direction is Input and the corresponding Task Definition Parameter is
Input/Output.

Process Apps
Constraint Type
Used parameters are present in the Call Activity Process Parameters and their read-only Error
settings, direction and datatypes match.
A used parameter is present in the Process Definition Parameters, matching read-only Warning
setting and datatype, but its direction is Input and the corresponding Process Definition
Parameter is Input/Output.
Exclusive gateways must have at least one default or unconditional exit. Error
Exclusive gateways does not have more than one unconditional exit. Warning
Inclusive gateways must have at least one default or unconditional exit. Error
Property/Parameter data types of the variables used for binding must match. Error
All vertices have at least one outgoing edge. Error
All vertices have at least one incoming edge. Warning
User Tasks must be bound to a Task Definition and Call Activities to a Process Definition. Warning
The output parameters of one-way asynchronous activities should not be used as a data Warning
source when binding. They will be disregarded at runtime to avoid unpredictable behavior.
The output parameters of one-way asynchronous activities should not have a destination. Warning
They will be disregarded at runtime to avoid unpredictable behavior.
All the process definitions referenced by a call activity must have been set as executable. Error
Process Context Definition User Fields declared as Call Activity variables must exist and be Error
compatible.
Task Context Definition User Fields declared as User Task variables must exist and be Error
compatible.
If the uploaded bpmn file contains obsolete definitions for Work Center or Location in any Warning
user task configuration, you will be notified that they have been removed from the model,
and this information will also be traced in ETW as a warning.
Procedure

2. In the Process Definitions page, select the Process Definition whose model you want to set to executable and
click .
3. In the Process Definition Editor, click .

Process Apps
4. Click Yes when prompted to save your diagram. The process definition will be set as executable if no errors are
returned: once the Process Definition is set as executable, the Work Process drop down is displayed in the
command bar.
Result
The Process Definition Model is ready to be executed as a Work Process. You can perform this operation:
• from the current environment, selecting either of the following options from the Work Process drop down list
box:
• Create, to create a new Work Process to be started at a later time from the Process Runtime page.
• Create and Start, to create and immediately start a new Work Process.
• from the Process Runtime page.
4.1.2.4 Exporting and Importing Process Definition Data

The Business Process Flow App allows you to export and import its own master data entities. Unlike the Export
operation, the Import procedure depends on the exported entities and has to be performed carefully as described
in the following section.

The Business Process Flow app could be modeled in one of the following ways:
• using only Process Definitions and/or Process Context Definitions, which refer to Activities (no Tasks)
• using both Process Definitions and Tasks Definitions.
If you are interested in using Process Context Definitions and/or Process Definitions in combination with Tasks and/
or Tasks based on Work Instructions, all the needed entities must be present on the target database for properly
configuring the Process Definitions and setting them as executable.
Let us assume that you have defined a Process Definition, associated to a Process Context Definition, which uses
Tasks and some of these Tasks are created from Work Instruction Definitions. To properly export and import this
configuration perform the following actions:
• Export Process Context Definitions (if any) with Include Descendants = True. The import of the corresponding
export package will include both Process Context Definitions and the related Process Definitions. This is a
consequence of the Include Descendants = True, otherwise you should have imported first Process Context
Definitions and then Process Definitions via Creating Process Definitions.
• Export Task Definitions used by the target Process Definition. The import of the corresponding package is
necessary to create in the new system the Tasks referred by the Process Definition we want to use. If the Tasks
referred by the Process Definition do not exist, the Process Definition itself will not be set as executable.
• Export Work Instruction Definitions referred by the target Task Definition. This step is necessary since we
assumed that some of the Tasks used by your target Process Definition are defined starting from a Work
Instruction Definition. In this case, if the Work Instruction Definition does not exist, the entire Process Definition
cannot be considered valid.
As described above, remember that Process Definitions must be exported and imported not by following the
current section, but using the procedure documented at Creating Process Definitions, which leverages BPMN file
format.
 While importing, if the user task configuration contains obsolete definitions for either Work Center or
Location then the information will be traced in ETW and these obsolete definitions will not be utilized for
Task initialization.

Process Apps
 Note that Process Context Definitions are parent entities.
Process Process Process Notes

Context Definition from Template
Definition BPMN file
Process Context If Process Context Definition is

Definition & exported by setting Include
Descendants to True
Process Definiti
on Note: Only Process Definition
entities that are associated to
Process Context Definition entities
are exported.
Process Context If Process Context Definition is

Definition & exported selecting Include
Descendants = False and Process
Process Definiti
Definition is imported via Creating
on
Process Definitions.
Process Definiti Process Definition is imported

on via Creating Process Definitions.
Process
Template
Process Context Export Process Context Definition

Definition by setting Include Descendants to
False
4.1.3 How to Manage Work Processes

At runtime a Process Definition is called a Work Process.
When a Process Definition has been created and configured, it is ready to be made executable when the
corresponding Work Process runtime instance is created and run.
During the creation of the Work Process the system applies a set of consistency rules. If the outcome of the check is
positive, you can then instantiate runtime Work Process from that Process Definition, otherwise a meaningful set of
errors are proposed to the user in order to fix any configuration issues found.
Then several runtime actions can be performed on the Work Process instance, such a stopping, resuming, aborting
it and so on (see table below).

Process Apps
Add To create and execute Work Processes.
 Work Processes can also be created and run

automatically by defining specific actions
triggered by Signal Rules
Overview of the selected Work Process To view the details of an individual Work Process,
including input and output parameters and contexts.
Edit To edit name and description of the Work Process.
To delete a Work Process.

Delete
Hide/Unhide Filter To apply filters to the Work Process list.
Open the Runtime Monitor for the selected To monitor Work Processes.
Work Process
Pause To temporarily stop the runtime execution.
Resume To restart a runtime execution that has been paused.
Abort To abort a Work Process while it is in progress or paused.
Recover all the Work Processes To restore the status of all the Work Processes.
4.1.3.1 Creating and Executing Work Processes

Work Processes are based on Process Definitions created in the Business Process Flow App.
They represent the practical execution of a Process Definition Model.
According to your needs, you can choose to create Work Processes to be started immediately or you can create
Work Processes and then start them at a later time.
All Work Processes are displayed in the Work Process List page, along with their basic configuration details and
when they were created and last updated. Filters can be applied to this list, when required.
Work Processes can be also created and run automatically by defining specific actions triggered by Signal Rules.

Process Apps
 Work Process can contain up to 50 levels of internal Work Processes.

To avoid infinite recursion, it is recommended to use the looping function during the modeling phase to
improve maintainability and performance.
Procedure
1. Do either of the following to open the Work Process List page:
• Click the Work Process List home tile.

• Click Process Runtime in the side menu bar and then select Work Process List.
2. In the Work Process List page, click the button and then select either of the following options:
• Create Work Process, to create a Work Process and start later.
• Create and Start Work Process, to create and start a Work Process immediately.
3. In the Select Process Definition page, select the Process Definition on which the Work Process will be based.
4. Insert a mandatory unique Id for the new Work Process.
5. Provide the optional name and description (the maximum number of characters for both of them is 255).
6. If you are creating a Work Process to be started immediately, click the Parameter tab and then set the values of
the input parameters of your Process Definition. Default values are displayed by default but can be modified.
Only parameters set as read-only they cannot be modified.
7. Click the Context tab and enter values for the user fields of the process contexts that were associated with the
Process Definition. When the Work Process is executed, an instance of the Work Process Context class is created
in the operational domain, with the related user fields.
• if the Work Process has been created to be started immediately, click Start.
• if the Work Process has been created to be started at a later time, click Save. When necessary, select the
previously saved Work Process in the list and then click Start.
Result
The Work Process execution starts, if any errors arise, its status changes to Error, and you can check the Runtime
Monitor to identify and fix the problem.
 For more information, see the SetExecutable command in the BPFlow App Reference Guide.
4.1.3.2 Configuring Signal Rules with Start New Work Process Action
From the Signal App, when you configure a Signal Rule, you can define an action that creates and runs a new Work
Process and that will be triggered by the Signal Rule.
Procedure
1. From the Signal Rule Editor, open the Action Block (as documented at page Configuring the Action for Signal
Rule).
2. In the Action Type side panel select the Start New Work Process tile.
3. In the Properties side panel, insert the following parameters:

Process Apps
Option Description
BPDefinition A mandatory ID to identify the Process Definition (only Process

Definitions that have been set to Executable can be selected from the
drop down list box).
BPRevision A mandatory ID to identify the specific revision of the Process

Definition.
BPContext To identify the Process Definition Context which defines how to

contextualize runtime work processes.
4. Click Save. The system calls the StartNewWorkProcess command which creates and runs a new Work Process
(see also BPFlow App Reference Guide).
What to do next
You must now wire the parameters of the Signal Rule. In the Transform Editor the system will display in the grid
both the parameters belonging to the command defined in the action block and the following:
• All parameters of the selected Process Definition and of the related Process Template. When you will save the
configuration, the Process Definition parameters will be wired in the Transform Block configuration, as well as
Work Process NId, Work Process name and Work Process Description.
• If you have selected the related Process Definition Context, the User Fields related to the selected Context, with
the naming convention: ProcessContextDefinition name/UserField name.
4.1.3.3 Applying Filters to the Work Process List

When many Work Processes have been created, it may be useful to filter the list according to specific criteria to find
the required Work Process quicker.
Procedure

• Click Process Runtime in the side menu bar and click Work Process List: the page is loaded,
displaying the last 10 Work Processes modified.
2. In the Work Process List page, click the icon to open the Filters panel.
3. Select any of the following from the corresponding drop down lists to filter the Work Processes:
• Process Definition Revision
• Work Process
• Work Process Status
4. To filter by context select one or more contexts from the Process Definition Context drop down list. All
selected contexts must be present in the Work Process. To further filter by context user field values, click Search
User Fields, and provide a required value for the user fields you want to filter by.
5. Click Apply.
4.1.3.4 Monitoring Work Processes

Work Processes are based on Process Definitions created in the BPFlow App.

Process Apps
when they were created and last updated.
Each element in the Work Process is displayed with colors and symbols to easily identify which elements are active,
have already been activated, contain active or past errors.
As the work process moves through its various steps, one or more tokens are displayed showing the progress point.
The configuration of the elements in the flow can be checked by clicking the info icon either next to the
element. User Tasks display the status of their tasks. Call Activities also display the status of their sub-processes,
when they have triggered only one instance, otherwise a stacked folders icon is displayed in the element, and
clicking on this will display a grid listing each instance and its corresponding status.
If errors occur during the execution of the Work Process, an error icon is displayed next to the corresponding
element. Clicking on this icon allows you to examine and solve the underlying issue. Once the error is solved the
error icon remains but its color changes to orange .
 If one of the Work Process elements is a Call Activity that refers to another Process Definition, you can
select the block and click the icon to view the underlying Process Definition.
Procedure

2. In the Work Process List page, select the Work Process you want to monitor from the list and click the open
icon, filtering the list if required.

Process Apps
3. To monitor the execution and resolve possible errors of individual elements, click either the Info or
error icon in the following elements:
• inclusive and exclusive gateways
• user tasks
• call activities
• timers.
4.1.3.4.1 Solving Gateway Errors in the Runtime Monitor

The Runtime Monitor provides details on how an inclusive/exclusive gateway has been configured, and allows you
to solve any execution errors that may arise in the execution of the work process, by either selecting which
branches should be forced, or definitively making the entire work process fail.
The Runtime monitor pane is displayed by clicking one of the following icons displayed next to the gateway:
• the info icon

• the active error icon, displayed when the gateway contains an active error, which needs to be solved
• the resolved error icon, displayed when an error occurred, which has already been solved.
Procedure

2. In the Work Process List page, select the Work Process you want to monitor, filtering the list if required, and
click the icon.
3. Click either the info icon or the error icon, which is displayed if an error has occurred, next to the
gateway element.
4. Click on the Configuration tab to view in read-only mode how the gateway has been configured.
5. Click on the Errors tab to check which errors have arisen. Do one of the following to solve the error situation:
• to definitively cause the entire work process to fail click Fail Work Process
• to force specific paths to be executed select them in the force column and click Force Gateway Paths.
The Force Gateway Paths button is enabled for exclusive gateways when one and only one outgoing
sequence flow is selected and for inclusive gateways when at least one outgoing sequence flow is
selected.
 Once the error has been solved, the error icon will then become orange, and the solved error will be
displayed in the Amended Errors section. This section displays a list of all solved errors, with the date and
time when they occurred and a description of the error.
4.1.3.4.2 Monitoring and Skipping Call Activities in the Runtime Monitor

The Runtime Monitor panel displays the configuration details of the call activity, the execution status of the
associated sub work processes and any errors that may have arisen during their execution. These errors can be
solved either forcing the failure of the Work Process, or skipping the activity.
The Runtime Monitor pane is displayed by clicking one of the following icons displayed next to the call activity:
• the info icon

• the active error icon, displayed when the call activity contains an active error, which needs to be solved

Process Apps
Procedure

click the open icon.
3. Click either the info icon or the error icon, which is displayed if an error has occurred, next to the call
activity element.
4. Click on the Configuration tab to view in read-only mode how the call activity has been configured, including
the process definition the call activity is based on, its revision and parameters.
5. Click on the Execution tab to view details on all the sub-processes in the call activity, such as their status and
when they were created, and the process definition they are associated with. You can order the grid by Work
Process Id, Status or date of creation. This data is displayed if the call activity has been executed at least once.
6. Click on the Execution Errors tab to check which errors have arisen. Do one of the following to solve the error
situation:
• to skip a particular call activity and to move the workflow forward click Skip Activity. If the Call Activity
is in the middle of a loop, the current loop-iteration will be skipped, and the loop will continue with the
next iteration, if there is one.
4.1.3.4.3 Monitoring and Skipping User Tasks in the Runtime Monitor

The Runtime Monitor panel displays the configuration details of the user task, the execution status of task
instances, and any errors that may have arisen during their execution. These errors can be solved by either forcing
the failure of the Work Process, or skipping the user task.
The Runtime Monitor pane is displayed by clicking one of the following icons displayed next to the user task:
• the info icon

• the active error icon, displayed when the user task contains an active error, which needs to be solved
Procedure

3. Click either the info icon or the error icon, which is displayed if an error has occurred, next to the user
task element.

Process Apps
4. Click on the Configuration tab to view in read-only mode how the user task has been configured, including the
task definition the user task is based on, its revision and parameters.
5. Click on the Execution tab to view details on all the associated task instances, such as their status and when
they were created, and the process definition they are associated with. You can order the grid by Task Id, Status
or date of creation. This data is displayed if the user task has been executed at least once.
6. Click on the Execution Errors tab to check which errors have arisen. Do one of the following to solve the error
situation:
• to skip a particular user task and to move the workflow forward click Skip Activity. If the User Task is in
the middle of a loop, the current loop-iteration will be skipped, and the loop will continue with the next
iteration, if there is one.
4.1.3.4.4 Monitoring Timer Countdowns in the Runtime Monitor

The Runtime Monitor panel displays the configuration and execution details of the timer intermediate event and
any errors that may have arisen during their execution. These errors can be solved by either forcing the failure of the
Work Process, or skipping the timer element.
The Runtime Monitor pane is displayed by clicking one of the following icons displayed next to the timer:
• the info icon.

• the active error icon, displayed when the user task contains an active error, which needs to be solved.
Procedure

3. Click either the info icon or the error icon, which is displayed if an error has occurred, next to the timer
element.
4. Click on the Configuration tab to view in read-only mode how the timer has been configured, either by duration
or datetime.
5. Click on the Execution tab to view how long the timer will wait. This data is displayed if the timer is in execution,
otherwise this tab will be empty.
6. If needed, trigger the expiration of the timer manually by clicking the Expire Timer button.
7. Click on the Error tab to check which errors have arisen. Do one of the following to solve the error situation:
• to definitively cause the entire work process to fail click Fail Work Process.
• to skip the timer and to move the workflow forward click Skip Timer.

Process Apps
 • The system verifies the timer has been configured correctly. Otherwise, a warning returns.
• If the timer expires when the system running the workflow engine is down, then the system will
properly notify of the expiration as soon as it will resume. The work process can continue its execution
anyway.
Executing multiple timer instances

In a work-process, if a timer event is triggered more than once, a separate instance is created each time the timer
event is executed. At a time, only the most recent timer instance is shown.
On clicking the timer countdown, the path followed from start till the timer is shown.
You can change the shown countdown by following below steps.
1. Click on the info icon of the timer event.

2. Navigate to Execution tab
3. Click on the Show button.
4.1.3.5 Modifying the Status of a Work Process

The Runtime Monitor allows you to decide whether to solve Work Process errors or definitively fail the whole
process, but other intermediate operations can also be performed on the Work Process, such as pausing and
resuming its execution.
The possible transitions are as follows:

Process Apps
Pause To temporarily stop the runtime execution.
Resume To restart a runtime execution that has been paused.
Cancel/Abort To cancel a Work Process while it is created or to abort a Work

Process while it is in progress or paused.
Recover all the Work Processes To restore the status of all the Work Processes.
4.1.3.5.1 Pausing and Resuming Work Processes

A running Work Process can be paused and subsequently resumed during its execution from the Runtime Monitor.
Procedure


Process Apps
2. In the Work Process List page, select the Work Process from the list. If you have a high number of Work
processes, you can apply a filter to the list. Multi-selection is supported, but the Pause or Resume button may
be disabled if not all selected Work Processes are in a status which can be paused or resumed.
3. (Optionally) If you prefer to work in the Runtime Monitor with a visual display of the Work Process execution,
click to open the monitor.
4. Click either:
• to temporarily stop the runtime execution.
• to restart a runtime execution that has been paused.
 Pause and resume requests are not propagated to sub-processes referenced by any Call Activities included
in the Work Process.
Result
• After pausing a Work Process: the status of the Work Process is immediately changed to Paused. Any elements
within the Work Process that were in progress will complete their activity, but the workflow will not continue
any further.
• After resuming a Work Process: the status of the Work Process is immediately changed to Running. The
evaluation of the path and condition will then continue from the point where the work process was paused.
• If more than one Work Process was selected, and the required operation fails on any of these items, the
requested operation will be executed on the remaining Work Processes, and at the end of the operation a
warning message will be displayed, informing you which items failed. The Work Processes that generated errors
will remain flagged.
4.1.3.5.2 Canceling or Aborting Work Processes

A Work Process can be:
• cancelled while it is created
• aborted while it is in progress or paused.
Procedure

2. In the Work Process List page, select the Work Process to be cancelled or aborted from the list. If you have a
high number of Work processes, you can apply a filter to the list. Multi-selection is supported, but the Cancel/
Abort button may be disabled if not all selected Work Processes are in a status which can be cancelled/aborted.
3. (Optionally) If you prefer to work in the Runtime Monitor with a visual display of the Work Process execution,
click to open the monitor.
4. Click .
 Cancel/abort requests are not propagated to sub-processes referenced by any Call Activities included in
the Work Process.

Process Apps
Task App
Result
The status of the Work Process is immediately changed to Cancelled or Aborted, depending on the initial status.
Any elements within the Work Process that were in progress will complete their activity, but the workflow will not
continue any further.
If more than one Work Process was selected, and the required operation fails on any of these items, the requested
operation will be executed on the remaining Work Processes, and at the end of the operation, a warning message
will be displayed, informing you which items failed. The Work Processes that generated errors will remain flagged.
4.1.3.5.3 Recovering Work Processes

If the execution of Work Process is stopped for external causes, for example due to an uncontrolled shutdown of the
machine, the Work Process may be inconsistent when execution restarts.
The recover operation can be used to restore the status of all the Work Processes.
Procedure

2. In the Work Process List click .
4.2 Task App

The Task App provides pages where you can configure tasks in a user-friendly environment as well as UI
components to customize your own task runtime pages.
• UDM_RF
• TSK_MS
• TSK_OP
• EQU_MS
• EQU_OP
For detailed information on the artifacts and the back-end logic contained in these Functional Blocks, see
the Reference Documentation of the Functional Block.
Task App UI contents

In addition to the back-end functionalities, the Task App provides the following front-end artifacts:
• the Task Engineering UI screen, where you can define task definitions and task parameters
• the Task Runtime UI screen, where you can manage tasks at runtime (Task Administration screen)
• Two UI components that can be embedded in custom UI screens and that are specifically designed for operator
dashboards (i.e. to offer a simple user interface, with large colored icons and buttons with summarized
information). These UI Components are:

Process Apps
Task App
• TaskListViewComponent, which displays a list of tasks and work order tasks

• TaskInfoComponent, which displays details on a specific task (identified by its Id or NId).
The operations you can perform in the standard Task Administration screen and the ones you can perform in a
custom page containing the TaskListViewComponent UI Component are similar, except for some small
difference. The matrix below compares the runtime operations you can perform in the two environments:
Environme Create View Manage Manage Repeatin Modify Unhide

nt Tasks Tasks Task Task g Tasks Task Tasks in
Statuses Sequencin Parameter Final Status
g s
Task
Administra
tion screen
(supervisor
s)
TaskListVi
ewCompon
ent
(operators)
What can I do with the Task App?

• You can find useful conceptual information at What Are Tasks?
• For the engineering configuration workflow see How to Engineer Tasks
• For the runtime phase of the task management see How to Manage Tasks at Runtime
• For information on how to customize task management see How to Customize Task Management.
4.2.1 What Are Tasks?

Tasks can be used to represent individual activities.
Tasks (runtime Tasks) are based on templates, called Task Definitions, which are defined in the engineering phase.
Consequently, you must define these templates (along with their parameters) before creating runtime Tasks.
Tasks inherit the Task Definition properties and parameters and represent Task Definition instances.
Task Sequencing, Statuses and Completion Checks

Sequence numbers specify the order in which tasks should be activated at runtime. In order to specify a sequence
order, the tasks must be part of a task flow.
For example, if Task A and Task B belong to the same task flow, and their sequence numbers are 100 and 110
respectively, Task A will be proposed first at runtime.
When a task completes, it can have one of the following outcomes:
• Skip
• Failure
• Success
When sequencing is applied, completion checks can be performed in order to compare the exit condition
(e.g. ContinueOnFailure or ContinueOnSuccess) expected for a certain task with the actual outcome status of the
task (e.g. Failure or Success).

Process Apps
Task App
The result of this check is called 'contribution'. If the status expected by the exit condition and the status outcome
match, the contribution is considered 'positive'. Skippable tasks always have a positive contribution.
The following table sums up the completion check logic and the relative contribution results.
IsSkippable ContinueOnSuccess ContinueOnFailure Status Outcome Contribution
Success Positive: can

proceed
Failure Negative:
must stop
Success Negative:
must stop
Failure Positive: can

proceed
Success or Failure Positive: can

proceed
or or Skip Positive: can

proceed
If several Tasks have the same sequence number, all the exit conditions must be verified before the subsequent
tasks can be executed. In other words, the contribution of all the tasks with the same sequence number must be
positive before the execution can proceed.
For example, given the task sequence below, tasks with sequence number 200 (Tasks 3, 4 and 5) will be activated
once the contribution of the tasks in the previous step (tasks 1 and 2) is positive. If the contribution of any of the
tasks with sequence number 200 is negative, all the tasks in the successive step (level 300) will be in
Canceled status. This check is carried out at each of following steps, until the final step is reached.

Process Apps
Task App
These attributes (sequence number, completion checks, skippable) are all defined when the runtime task is
created.
Repeating Tasks
Tasks can be repeated. This action corresponds to creating a new instance of the task definition on which the task is
based.
You can repeat a Task if the MaxIterations property is properly set during when creating a task. The task will then
be repeated until the maximum number of iterations is reached.
The contribution logic, applied to task sequencing, is also applied to repeatable tasks. The successive task in a task
flow is activated when the contribution of any of its iterations has a positive result. If the task reaches its maximum
number of iterations, and the contribution is continually negative, the status of the successive task
becomes Canceled.
4.2.2 How to Engineer Tasks

You must create and configure Task Definitions and Parameters (engineering phase) before you can use Tasks at
runtime.
Workflow
1. Create Task Definitions.
2. Add Task Definition Parameters.
3. Define Task Context Definitions.
4. Create a New Revision of a Task Definition.
5. Set a Task Definition Revision to Current.

Process Apps
Task App
4.2.2.1 Creating Task Definitions

Task definitions act as templates for tasks in the Task App. Consequently it is necessary to create task definitions
before creating tasks.
As these entities belong to the Master Data domain, task definitions support revision management.
There are two ways to create new Task Definition:
• From scratch
• By copying an existing Task Definition Revision
Audit Trail is displayed in the Task Definition page to provide evidence of all the operations that have been carried
out on the specific Task Definition. Its records can be viewed by selecting the particular Task Definition and clicking
on Audit Trail tab.
 If you have added both Work Instruction App and WITask Extension App to your Solution, after deploying
the Solution, a default Task Definition, named Inspection, will be created and displayed in the Task
Definition page. It is required to configure and use the Quality Execution functionality. For more
information, see Quality Execution.
Creating a Task Definition from scratch
 If you have developed custom Task Types in Project Studio, and have developed custom web pages for
configuring Task Definitions, when you click the Add button in the Task Definition page and select the
custom task type, the system directs you to the custom Task Definition web page, instead of the standard
page provided by the Task App. In this case, the parameters requested may not correspond to those listed
below.
1. Do either of the following to open the Task Definitions page:
• Click the Task Definitions home tile.

• Click Task Engineering in the side menu bar and click Task Definitions.
2. Click . The system automatically opens the Add Task Definition page, unless custom pages for managing
task definitions have been developed (in this case, a drop-down list box is displayed where you can choose the
required custom page).
Id The unique identifier assigned to the task definition. Once created,

the Id value cannot be modified.
Revision The revision of the task definition. Once created, the Revision value
cannot be modified.
Name (Optional) The name assigned to the task definition. If this field is left
blank when updating the value, it will be set to null.

Process Apps
Task App
Description (Optional) Additional information on the task definition. If this field

is left blank when updating the value, it will be set to null.
4. Click Save. The new task definition is displayed in a tile in the Task Definitions page.
 The Task Definitions page provides common functionalities such as Group By, Quick Search, Filter and
can filter Task Definitions by Id, Revision, Name and Is Current.
Copying an existing Task Definition Revision

While copying an existing Task Definition Revision, you can create a new Task Definition instance based on the
selected Task Definition with a newly assigned Id and Revision. The contents (such as parameters, contexts and so
on) are copied from the selected Task Definition.

2. In the Task Definitions page, select the tile of the Task Definition you want to copy.
3. Click .
4. Enter a new Id for the copied Task Definition. Once defined, this value cannot be modified.
5. Enter a new Revision for the copied Task Definition. Once defined, this value cannot be modified.
6. Click Save.
Available operations on Task Definitions

To delete the Task Definition.

Delete
To edit name and description of the Task Definition.

Edit
Lock To lock or unlock the Task Definition, so that it cannot be modified

or deleted.
Unlock
Set Current To set or unset a specific Task Definition Revision to current.
Unset Current
Copy Revision To copy an existing revision of the Task Definition.
Create New Revision To create a new revision of the Task Definition.

Process Apps
Task App

Export
can be downloaded locally and imported afterwards. See How To
Export and Import Data
4.2.2.2 Adding Task Definition Parameters

You can add parameters to a Task Definition, which can be used for the following purposes:
• to model input, output or input/output information required to correctly initialize the task,
• to provide any required feedback when the task completes.
Procedure

2. In the Task Definitions page, select a Task Definition and click to open the Task Definition page.
4. In the Add Task Definition Parameter page, set the following attributes:
Id The unique identifier assigned to the task parameter. Once created,

the Id value cannot be modified.
 The Task Definition Parameter Id must follow the defined

limitations, if the Task Definition is then used within the
Business Process Flow App.
Type The data type of the parameter value. The following data types are
Unit of Measure The UoM is to be set according to the Type chosen.
Value (Optional) The parameter value. This value is the default value
displayed in the runtime Task. If you select the Read Only option,
this value cannot be overwritten at runtime. Depending on the Type
selected, a description of the format is provided next to the Value
label for Bool, Datetime and Guid. If this field is left blank when
updating the value, it will be set to null.
Read Only If selected, indicates that the value cannot be modified at runtime.
5. Click Save. The task parameter is added to the task definition.

Process Apps
Task App
4.2.2.3 Creating a New Revision of a Task Definition

A Revision is used to identify a form of a Task Definition that is slightly different in certain aspects from other forms
of the same Task Definition.
Revisions prevent you from creating the entire Task Definition from scratch if any artifacts of the earlier Task
Definition have been changed or upgraded.
After creating a new Revision of a Task Definition, you can change it, not only defining new parameters but also
modifying or deleting those that have been inherited.
Procedure

2. In the Task Definitions page, select the tile of the Task Definition for which you want to create a new revision.
3. Click .
4. Enter a value for the New Revision. Once defined, this value cannot be modified.
5. Click Save. You can add or modify Task Definition Parameters.
4.2.2.4 How to Define Task Context Definitions

Task Contexts are structured tags, which can be associated to Task Definitions.
You can define User field, with specific data types, for each Task Context Definition and you can provide values for
these User Fields as follows:
• at Task Context Definitions level, during the creation of the User Fields themselves (for instance, to assign a
default value)
• at Task Definitions level, after having associated a Task Context Definition to the Task Definition itself (this
action will lead you to directly modify the value of User Fields at Task Context Definitions level)
• at Tasks level, during the creation phase of a Task
 Note
Once Task Context Definition User Fields has been actualized at Task creation time, those values cannot
be modified anymore.
For example, in a scenario where Tasks are strictly related to Work Order Operations, the following context user
fields may be defined: Work Order, Work Order Operation and Operation.
Task Contexts can either be defined in two distinct ways:

Process Apps
Task App
Where How Advantages
From the TSK_MS By populating the following base Allows contexts to be added to third-party
Functional Block entities in the dbinit file: Functional Blocks
• TaskContextDefinition Additional customization is possible to
• TaskContextDefinitionUserFie improve query performance and provide
ld property indexing by extending the
ContextEntityType.
Directly in the Task App By using the Task Context Definition Easy to use, with no code knowledge
UI Screens provided by the App required.
Provides the possibility to add additional
contexts without modifying the
underlying Functional Blocks.
For more information on the mentioned Functional Block, see TSK_MS Functional Block in the Opcenter Execution
Workflow
1. Create Task Contexts by either:
• Defining Task Contexts in Functional Blocks.
• Defining Task Contexts in the Task App.
2. Associate Task Contexts to Task Definitions.
4.2.2.4.1 Defining Task Contexts in Functional Blocks

Contexts are structured tags, which can be associated to task definitions.
The information required to create task contexts is contained in two base entities in the TSK_MS Functional
Block (see also TSK_MS Functional Block in the Opcenter Execution Foundation Development and Configuration
Guide):
• TaskContextDefinition
• TaskContextDefinitionUserField
To ensure this association works correctly with third-party Functional Blocks, careful attention must be paid to the
structure of the two base entities.
A standard context entity type is provided, which can be physically or logically extended to allow further
customization, improve query performance and provide property indexing, if required.
TaskContextDefinition
The structure of the TaskContextDefinition base entity is as follows:
NId The unique identifier assigned to the Task Context Definition. Once

Process Apps
Task App
Name The name assigned to the Task Context Definition.
Description Additional information on the Task Context Definition.
ContextEntityType The value of the ContextEntityType can be one of the following:

• Siemens.SimaticIT.OperationalData.TSK_OP.OPModel.DataModel
.ITaskContext. At runtime, an instance of the Task Context class will
be created in the operational domain, with the user fields as defined
in the example below.
• NULL. At runtime no instances will be created in the operational
domain, but third-party Functional Blocks will be able to develop
their own logic using the parameter values passed.
• The full name of the physical extension (e.g.
Siemens.SimaticIT.<DomainName>.<FunctionalBlockName>.<Acr
onym>Model.DataModel.<ExtendedEntityInterface>), defined in a
referenced Functional Block, of the ITaskContext entity. At
runtime an instance of the extended class will be created in the
operational domain, with the custom user fields, as shown in the
example below. The values passed as context values will be used to
set the entity properties. If no values are passed, the value will be
NULL.
• The full name of the logical extension (e.g.
Siemens.SimaticIT.<DomainName>.<FunctionalBlockName>.<Acr
onym>Model.DataModel.<ExtendedEntityInterface>), defined in a
referenced Functional Block, of the ITaskContext entity. At
runtime an instance of the facet will be created in the operational
domain with the custom user fields, as shown in the example below.
The values passed as context values will be used to set the facet
properties. If no values are passed, the value will be NULL.
 The TaskContextDefinition Id must follow the defined limitations, if the TaskContextDefinition is then
used within the Business Process Flow App.
The following is an example of a TaskContextDefinition entity, where

the ContextEntityType is Siemens.SimaticIT.OperationalData.TSK_OP.OPModel.DataModel.ITaskContext:
<Entity type="Siemens.SimaticIT.MasterData.TSK_MS.MSModel.DataModel.TaskContextDefini
tion">
<Property name="NId" kind="Plain" value="TaskContextDataType" />
<Property name="Name" kind="Plain" value="TaskContextDataType" />
<Property name="Description" kind="Plain" value="Task Context Definition with user
fields each for type" />
<Property name="ContextEntityType" kind="Plain" value="Siemens.SimaticIT.OperationalD
ata.TSK_OP.OPModel.DataModel.ITaskContext" />
<Property name="TaskDefinitions" kind="ManyToManyReference" />
</Entity>

Process Apps
Task App
The following is an example of a TaskContextDefinition entity, where the ContextEntityType is NULL:
tion">
<Property name="NId" kind="Plain" value="TaskContextNULL" />
<Property name="Name" kind="Plain" value="TaskContextNULL" />
<Property name="Description" kind="Plain" value="Task Context Definition with Context
Entity Type equal to NULL" />
</Entity>
The following is an example of a TaskContextDefinition entity, where the ContextEntityType is an extended

entity:
tion">
<Property name="NId" kind="Plain" value="TaskContextExtend" />
<Property name="Name" kind="Plain" value="TaskContextExtend" />
<Property name="Description" kind="Plain" value="Task Context Definition for extended
Task Context" />
ata.BPFLibOP.OPModel.DataModel.IMyTaskContext" />
</Entity>
The following is an example of a TaskContextDefinition entity, where the ContextEntityType is a logically

extended facet:
tion">
<Property name="NId" kind="Plain" value="TaskContextFacet" />
<Property name="Name" kind="Plain" value="TaskContextFacet" />
<Property name="Description" kind="Plain" value="Task Context Definition for Task
Context Facet" />
ata.BPFLibOP.OPModel.DataModel.IMyFacetTaskContext" />
</Entity>
TaskContextDefinitionUserField
The structure of the TaskContextDefinitionUserField base entity is as follows: NId, DataType and DefaultValue,
where:
• NId, which acts as a unique identifier for the user field. In case of entity extensions, the NId property value must
be set to the name of the extended entity.
• DefaultValue, a default value for the user field, which must be coherent with the specified DataType, even if it is
persisted as a string.
• DataType, one of the following data types:

Process Apps
Task App
Data Type User Field Type Example values and format
Bigint 5 • from -2^53 (i.e.

-9,007,199,254,740,992)
• to (2^53)-1 (i.e.
9,007,199,254,740,991)
Bool 7 true/false
Datetime 8 'yyyy'-'MM'-'dd' 'HH':'mm':'ss', for example

2017-12-25 12:00:00

754-2008 standards.
Guid 9 example: ([a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]

{12})
Int 4 • from -2^31 (i.e. -2,147,483,648)

• to (2^31) -1 (i.e. 2,147,483,647)
Smallint 3 • to (2^15)-1 (i.e. 32,767)
String 1 -
Tinyint 2 0 to 255
 The TaskContextDefinitionUserField Id must follow the defined limitations, if the

TaskContextDefinitionUserField is then used within the Business Process Flow App.
The following is an example of a TaskContextDefinitionUserField base entity:
tionUserField">
<Property name="NId" kind="Plain" value="TCDUFBool" />
<Property name="TaskContextDefinition" kind="SingleReferenceToParent">
<LogicalKey entityType="Siemens.SimaticIT.MasterData.TSK_MS.MSModel.DataModel.TaskCon
textDefinition_Siemens_SimaticIT_MasterData_TSK_MS_MSModel">
</LogicalKey>
</Property>
</Entity>
Database initialization (dbinit) file example

The following contains examples of TaskContextDefinition and TaskContextDefinitionUserField entities, using
the base entities, extended entities and facets defined above as ContextEntityType:

Process Apps
Task App
<?xml version="1.0" encoding="utf-8" ?>

<Sections>
<Section engineeringLevel="LibraryFunctionalBlock" implementationName="MyImplementati
on" domainName="MasterData">

tion">
<Property name="Name" kind="Plain" value="TaskContextNULL" />
<Property name="Description" kind="Plain" value="Task Context Definition with Context
Entity Type equal to NULL" />
</Entity>
tion">
<Property name="Name" kind="Plain" value="TaskContextDataType" />
<Property name="Description" kind="Plain" value="Task Context Definition with user
fields each for type" />
ata.TSK_OP.OPModel.DataModel.ITaskContext" />
</Entity>
tion">
<Property name="Name" kind="Plain" value="TaskContextExtend" />
<Property name="Description" kind="Plain" value="Task Context Definition for extended
Task Context" />
ata.BPFLibOP.OPModel.DataModel.IMyTaskContext" />
</Entity>
tion">
<Property name="Name" kind="Plain" value="TaskContextFacet" />
<Property name="Description" kind="Plain" value="Task Context Definition for Task
Context Facet" />
ata.BPFLibOP.OPModel.DataModel.IMyFacetTaskContext" />
</Entity>

tionUserField">
<Property name="NId" kind="Plain" value="TCDUFString" />
<Property name="UserFieldValue" kind="Plain" value="AAA" />

Process Apps
Task App
</LogicalKey>
</Property>
</Entity>
tionUserField">
<Property name="NId" kind="Plain" value="TCDUFBool" />
</LogicalKey>
</Property>
</Entity>
tionUserField">
<Property name="NId" kind="Plain" value="TCDUFDatetime" />
</LogicalKey>
</Property>
</Entity>
tionUserField">
<Property name="NId" kind="Plain" value="TCDUFDecimal" />
</LogicalKey>
</Property>
</Entity>
tionUserField">
<Property name="NId" kind="Plain" value="TCDUFInt" />
</LogicalKey>

Process Apps
Task App
</Property>
</Entity>
tionUserField">
<Property name="NId" kind="Plain" value="TCDUFString" />
</LogicalKey>
</Property>
</Entity>
tionUserField">
<Property name="NId" kind="Plain" value="TCDUFNULL" />
<Property name="UserFieldValue" kind="Plain" value="NULL" />
</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
tionUserField">

Process Apps
Task App

</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
tionUserField">
D94BA407DD1C" />
</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
tionUserField">

Process Apps
Task App

</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
tionUserField">
D94BA407DD1C" />

Process Apps
Task App

</LogicalKey>
</Property>
</Entity>
tionUserField">
</LogicalKey>
</Property>
</Entity>
</Section>
</Sections>
4.2.2.4.2 Defining Task Contexts in the Task App

Task Contexts are structured tags, which can be associated to Task Definitions.
User fields with specific data types and values can be defined for each Task Context Definition.
Audit Trail is displayed in the Task Context Definition page to provide evidence of all the operations that have
been carried out on the specific Task Context Definition. Its records can be viewed by selecting the particular Task
Context Definition and clicking on Audit Trail tab.
 Task Contexts can be also be defined at Functional Block level.
Procedure
1. Do either of the following to open the Task Context Definitions page:
• Click the Task Context Definitions home tile.

• Click Task Engineering in the side menu bar and click Task Context Definitions.
2. In the Task Context Definitions page, click .
3. In the Add Task Context Definition page enter the following information:
Id The mandatory unique identifier of the task context.
 The Task Context Definition Id must follow the defined

limitations, if the Task Context Definition is then used
within the Business Process Flow App.
Name An optional name for the task context.

Process Apps
Task App
Description Optional additional information on the task context.

4. Click Save.
5. To add User Fields to the Task Context Definition, select a Task Context Definition in Task Context Definitions
page and click to open the Task Context Definition page.
6. In the User Field tab, click .
7. In the Add Task Context Definition User Field page enter the following information:
Id The mandatory unique identifier of the task context user field.
 The Task Context Definition User Field Id must follow

the defined limitations, if the Task Context Definition User
Field is then used within the Business Process Flow App.
Type The data type of the user field. The following data types are
supported: Bigint, Bool, Datetime, Decimal, GUID, Int, Smallint,
String, Tinyint.
Value An optional value for the user field.

8. Click Save.
9. Repeat steps 6 and 7 to create as many user fields as required for your task context definition. The new Task
Context will be displayed as a tile on the left hand side of the Task Context Definition page, along with any
Task Contexts that were defined in Functional Blocks.
 The Task Context Definitions page provides common functionalities such as Group By, Quick Search,
Search. You can filter Task Context Definitions by Id and Name.
Available Operations on Task Context Definitions

To edit name and description of the Task Context Definition.

Edit
To permanently delete the Task Context Definition.

Delete

Export
downloaded locally and imported afterwards. See How To Export and
Import Data.

Process Apps
Task App
4.2.2.4.3 Associating Task Context Definitions

Contexts are structured tags, which can be associated to task definitions.
They are defined either:
• within Functional Blocks, or
• within the Task App.
 Currently contexts cannot be explicitly managed at runtime. However custom logic can be implemented
by third-parties, using the task definition / context association when creating tasks.
Procedure

2. In the Task Definitions page, select the Task Definition you want to associate to a Task Context Definition.
3. Click to open the Task Definition page.
4. In the Context tab, click and select the Task Context Definition you want to associate to the Task Definition.
5. Click Save. The Task Context Definition is associated to the Task Definition.
 You can remove the association of the Task Definition to a Task Context Definition by selecting the Task
Context Definition in the Context tab and clicking Disassociate Task Context Definition.
4.2.2.5 Setting a Task Definition Revision to Current

A specific revision of a Task Definition can be set to current in order to define which specific revision should be used
to create a Task.
Only one revision for each Task Definition (i.e. all the revisions with the same Task Definition Id) may be set the
current at any one time.
Procedure

2. In the Task Definitions page, select the tile of the Task Definition you want to set to current.
3. Click .
4.2.2.6 Exporting and Importing Task Data

The Task App allows you to export and import its own master data entities. Unlike the Export operation, the Import
procedure depends on the exported entities and has to be performed as described in the following section.

Process Apps
Task App

Example: If you want to import Task Definition and Task Context Definition entities, and the Task Context
Definition entities were exported by setting Include Descendants to False, you must first import the Task Context
Definition package and then the Task Definition one.
 Note that Task Context Definition are parent entities.
Task Context Task Notes

Definition Definition
Task Context If Task Context Definition is exported by

Definition setting Include Descendants to False.
If you export any Task Context Definition the related
user fields are also automatically exported.

Definition setting Include Descendants to False
&
Task Definition

Definition setting Include Descendants to True
& Note that only Task Definition entities that are
associated to Task Context Definition entities are
Task Definition
exported.
Task Definition • If you export any Task Definition the related

parameters are also automatically exported.
• If the export package contains Task Definition
entities associated to Task Context Definition
entities, the Task Context Definition entities must
be already present in the target environment, so
that referential integrity is fulfilled.
4.2.3 How to Manage Tasks at Runtime

You can perform the following operations in the Task Administration page to manage tasks at runtime.
Available Operations on Tasks

Process Apps
Task App
Add To create Tasks.
Edit To modify Task attributes (apart from the Id, Task Definition and Task Definition Revision
fields).
Edit To modify existing Task Parameters (and/or add new ones in a standard or custom page).
Parameters
Hide To hide (or display) a Task.

Unhide
Freeze To make a Task read-only. When read-only, the Task is visible and it cannot be edited, but it
can be deleted.
Unfreeze
To delete Tasks. Only tasks in a final status can be deleted. More than one task can be
Delete
deleted at a time.
(Operations vary To manage Task Statuses

according to the
Task State)
Repeat To repeat Tasks.
Enable To enable or disable Auto Refresh of the Task Administration page. See Managing Task
Auto Refresh States.
Disable
Auto Refresh
Hide/ To apply Filters to the Task Administration page.

Unhide Filter
4.2.3.1 Creating Tasks

When a Task Definition has been created and configured, it is ready to be instantiated and consequently executed.
At runtime, Task Definitions are called Tasks.
Tasks are displayed in the Task Administration page, along with their basic configuration details and when they
were created and last updated. This list can be filtered to find required tasks quicker.
Procedure

Process Apps
Task App
 If you have developed custom Task Types in Project Studio, and have developed custom web pages for
configuring Tasks, if you select a Task Definition based on a custom type, the system directs you to the
custom Add Task web page, instead of the standard page provided by the Task App. In this case, the
parameters requested may not correspond to those listed below.
1. Do either of the following to open the Task Administration page:
• Click the Task Administration home tile.

• Click Task Runtime in the side menu bar and click Task Administration.
2. Click to create a Task.
3. In the Select Task Definition page, you can optionally filter the task definitions displayed by clicking the
filter icon and either:
• select the Show only Current check box to display only Task Definitions in current status and click
Apply.
• specify the Id of the specific Task Definition you want to display, and click Apply.
4. Open the Task Definition node, and click on the required revision.
5. In the Add Task page, set the following attributes (these attributes may vary in a custom Task page) in the
Details tab:
Autogenerated Id If selected, the unique identifier of the Task to be added will be

autogenerated using the Numbering Pattern defined for Task Id.
Id The unique identifier assigned to the Task. Once the Task is created,
the Id value cannot be modified. If you have selected
Autogenerated Id, this field will be disabled.
Autogenerated Name If selected, the name of the Task to be added will be autogenerated
using the Numbering Pattern defined for the Task Name. If you are
modifying an existing Task, you can automatically generate (or re-
generate) the Task Name by selecting this check box (see the note
below on Edit operations).
Name (Optional) The name assigned to the Task. If you have selected
Autogenerated Name, this field will be disabled. If this field is left
Description (Optional) Additional information on the Task. If this field is left

Task Definition The Task Definition you want to associate with the Task. This field is
read-only.
Task Definition Revision The Task Definition revision associated with the Task. This field is
read-only.
Equipment The Equipment associated with the Task.
Is Skippable Defines if the Task can be skipped.

Process Apps
Task App
Is part of TaskFlow To apply sequencing to a task it must be part of a work flow,

consequently this field must be flagged and the subsequent work
flow fields must be completed (TaskFlow, Sequence,
MaxIterations, Continue on Success and Continue on Failure).
TaskFlow The name assigned to the Task Flow.
Sequence A sequence number must be provided for a task if you want to

implement sequencing, otherwise it is optional. This number is used
at runtime to assign an ascending sequence order to the Task within
a Task Flow. For example, Task A with sequence number 100 will be
proposed at runtime before Task B with sequence number 110.
Max iterations Defines the maximum number of times the task can be repeated.
The repetition of a task implies the creation of a new instance of the
original Task. This value is mandatory if you are implementing
sequencing. Note that if the task has been repeated at least once, its
Continue on Success, Continue on Failure, Is Skippable and Max
iterations fields cannot be updated.
Continue on Success Defines if the subsequent task in the sequence can be activated once
the current task has reached its final status and has Success as
Outcome property value. The Outcome of a task status is defined in
the standard Task App task state machine.
Continue on Failure Defines if the subsequent task in the sequence can be activated once
the current task has reached its final status and has Failure as
Outcome property value.
6. Click the Parameter tab, enter values for the input parameters specified for your Task Definitions. Default
values are displayed and can be modified. If parameters were set as read-only they cannot be modified.
7. Click the Context tab and enter values for the user fields of the task contexts that were associated to the Task
Definition. When the Task is executed an instance of the Task Context class will be created in the operational
domain, with its defined user fields.
8. Click Save. The new Task is created and displayed in the Task Administration page, along with the details on
when it was created and last updated. Its full details can be viewed from this page by clicking .
 Note
Once Task Context Definition User Fields have been actualized at Task creation time, their values cannot
be modified anymore.
4.2.3.2 Modifying Tasks and Task Parameters

In the Task Administration page in the Task App, you can:
• Modify Task Details
• Modify Task Parameters
• Add new Task Parameters

Process Apps
Task App
However, you cannot delete Task Parameters.
 If you have developed custom Task Types in Project Studio, and have developed custom web pages, and
the task to which you are adding Task Parameters is based on a custom task type, the system may direct
you to the custom Task Parameters page, instead of the standard page provided by the Task App.
Procedure

2. Select a task in the list and click . The list can be filtered/sorted to make it easier to find the task you want to
modify.
3. In the Details tab modify the task as required.
4. Click Save.
5. Select a task in the list and click . The list can be filtered/sorted to make it easier to find the task you want to
modify.
• To modify an existing parameter, select it, click and change its values as required. If the parameter
was set as read-only during its creation modifications will not be allowed.
• To add a new Task Parameter, click , and set the following values:
Id The unique identifier assigned to the Task Parameter. Once

Type The data type of the Task Parameter value. The following data
types are
supported: Bigint, Bool, Datetime, Decimal, GUID, Int,
Quantity, Smallint, String, Tinyint.
Unit of Measure It represents the base unit for measuring a physical quantity
(such as meter, kilogram). This is enabled only
when Parameter's Type is Quantity.
Value (Optional) The value of the Task Parameter. This value is the
default value displayed in the runtime Task. If you select the
Read Only option, this value cannot be overwritten at runtime.
Depending on the Type selected, a description of the format is
provided next to the Value label for Bool, Datetime and Guid. If
this field is left blank when updating the value, it will be set to
null.
Read Only If selected, indicates if the value of the parameter can be

modified at runtime or not.
6. Click Save.

Process Apps
Task App
4.2.3.3 Managing Task States

The status of tasks can be changed in the Task Administration page, according to the transitions allowed within
the Task State Machine:

Process Apps
Task App
 • If a custom UI has been defined for the task execution, the custom UI will be displayed when the task
status is activated.
• If an error occurs in the task lifecycle (the value of the attribute Error Count is different from 0) and the
task is related to a Task Type for which a custom Task Message UI has been defined, a custom button
is displayed for activating the custom Task Message UI.
• Multi-selection is supported for all status transitions, except for the actions Start and Resume.
• The data within the Task Administration page can be automatically refreshed if a filter in the page is
configured and the auto refresh button is properly enabled. You can enable or disable the auto refresh
option of the Task Administration page by applying any filter to the list and clicking either to
enable the auto refresh or to disable the auto refresh. The auto refresh option is disabled by
default on page load. If the auto refresh is disabled, click Apply in Filters panel to view the updated
list.
• Should the status of the tasks change frequently, any Task Administration page where the auto
refresh option is enabled, could cause a high refresh rate. Therefore, to reduce the refresh rate, you
need to set the proper values for the filter fields.
Procedure

2. Select tasks in the list and click the icon that corresponds to the required action. The new status depends on the
starting status of the selected tasks:
Icon Action Required Starting Target Notes

Status Status
Activate • Created Ready

• Not Ready
• Suspended
Suspend • Ready Suspended
Start • Ready In Progress The Start action is not supported

when more than one task is
selected.
Pause • In progress Paused
Resume • Paused In Progress The Resume action is not

supported
when more than one task is
selected.
Complete • In Progress Completed

Process Apps
Task App
Icon Action Required Starting Target Notes

Status Status
Skip • Created Skipped

• Not Ready
• Ready
• Suspended
Cancel • Created Canceled

• Not Ready
• Ready
• Suspended
Recover • Error In Progress
Set in status Fail • Error Failed
Abort • In Progress Aborted

• Paused
Set in status • In Progress Error

Error
4.2.3.4 Repeating Tasks

You can repeat Tasks if you have properly set the MaxIterations property (see Creating Tasks).
For more information on repeating tasks and the relative contribution logic see What Are Tasks?
Procedure

2. Select the task that you want to repeat and click Repeat.
4.2.3.5 Applying Filters to Task Administration

When many Tasks have been created, it may be useful to filter the list according to specific criteria to find the
required Tasks quicker.
 To filter records, we recommend that you configure up to 5 context fields at a time in the Advanced
Search panel. If you set up a higher number of context fields at the same time, you can run into system
errors because the search query string length may exceed the default allowed value.
To set up a higher number of context fields, apply some specific custom configurations such as increasing
the query string length on the web server, as explained at Applying Custom Configurations to the Opcenter
EX FN Service Layer of the Opcenter EX FN Development and Configuration Guide.

Process Apps
Task App
Procedure

2. In the Task Administration page, click the icon to open the Filters panel.
3. Select the required option from any of the following drop-down lists to filter the Tasks:
• Task Definition
• Task Definition Revision
• Task
• Task Status
• Equipment
• Task Flow
4. To filter by context, select one or more contexts from the Task Context drop down list. All selected contexts
must be present in the Task. To further filter by context user field values, click Search User Fields, and provide a
required value for the user fields you want to filter by.
5. Click Apply. Once the filter is applied, click either to enable or to disable the auto refresh option.
4.2.4 How to Customize Task Management

Opcenter EX FN supports task management through:
• TSK_MS Functional Block, with basic artifacts for defining and configuring predefined task types (Task
Definitions and Task Definition Parameters).
• TSK_OP Functional Block, with basic artifacts for managing runtime instances of task definitions (Tasks, Task
Parameters), basic commands for managing entities and task lifecycles and events related to task lifecycles.
• Task App, with a predefined User Interface (UI) for creating task definitions and managing tasks.
For a Functional Block overview, see Overview of Functional Blocks in the Opcenter Execution
Foundation Development and Configuration Guide
Possible customization operations

According to project requirements, a system integrator can customize task management in the following ways:
• Extending the TSK_MS and/or TSK_OP Functional Blocks, by creating data model extensions and business logic
and releasing new Functional Block packages. See How to Extend Referenced Functional Blocks in the Opcenter
Execution Foundation Development and Configuration Guide for further information on how to extend Functional
Blocks.
• Creating custom task types and task definitions.
• Creating custom UIs (optional), delivered in an App package.
• Configuring Mashup UI Modules using the components provided by the Task App:
• Task List View component.
• Task Info component.
4.2.4.1 Creating Custom Task Types and Task Definitions

Custom task types and task definitions can be defined in Project Studio by inserting task type and task definition
data in the database initialization file. For example, custom UI component references, entity property values,
parameter values etc.

Process Apps
Task App
For each Task Type and Task Definition, the system integrator must implement the business logic related to the
task statuses. Business logic usually interacts with the 'internal' events, which are the events related to the non-
final Task statuses.
This logic is implemented as command handlers in a Functional Block (typically in the same Functional Block where
the event handlers are implemented), which can be activated upon the notification of events. Consequently, the
system integrator must configure the event subscriptions necessary to activate the custom business logic.
The following events are fired:
• ActionOnTaskRequest - This event is fired when an action (e.g. Activate, Pause, Complete, etc.) on the task is
requested from a pre-defined command provided by Task Management (such as ActivateTask, PauseTask,
CompleteTask).
• StatusChanged - This event is fired when the status of the task has been changed successfully after invoking the
command SetTaskStatus.
• TaskEquipmentStatusChanged - This event is fired when a status of a task has been changed successfully after
invoking the command SetTaskStatus. It contains information on the Equipment to which the Task belongs to.
• StatusForced - This event is fired when the status of the task has been forced successfully after invoking the
command ForceTaskStatus.
• SequenceStepCompleted - This event is fired when an entire sequence step has been completed regardless of
whether it has completed successfully or not.
These events are all fired with a specific envelope on which you can filter while configuring the subscription.
State Machine
Runtime tasks follow a specific lifecycle based on the state machine described below:
No custom extensions can be applied to the Task State Machine provided by the Task App.

Process Apps
Task App
Task Flow for runtime tasks

The Task flow does not interfere with the logic defined for internal events (i.e. the logic specified for the non-final
statuses).
The Task flow integrates operations such as task creation and activation. These status changes can be manually
activated (i.e. without event handlers) or automatically (i.e. with event handlers).
The system integrator also configures the final statuses of the Task flow. The Task sequencing or the possibility to
iterate a task represent possible configurations of the Task flow.
4.2.4.2 Creating Custom User Interfaces for Task Management

When custom task types are defined, you can implement custom web pages to manage these task types.
In this way the user will be automatically piloted to the custom user interface pages when a task definition or task
uses the custom task type.
Procedure
For each custom task type:
1. Create a UI Component for managing task definitions, along with screens for creating, editing and viewing the
details of task definitions. You can use the following stateParams provided in input:
• $stateParams.componentStateParams.action: the corresponding action to be performed in the
screen, i.e. 'add'/'edit'/'view'.
• $stateParams.componentStateParams.taskTypeId: the selected Task Type Id
• $stateParams.componentStateParams.taskDefinitionId: the selected Task Definition Id (used in edit/
view)
• $stateParams.componentStateParams.previousStateName: the previous $state, used to return to
the previous UI page from the custom component.
• $stateParams.componentStateParams.commandBarType: the type of command bar previously used
before reloading for the action 'view', whose values can be "overview", "parameter" or "context".
It is possible to change the actions on the command bar of the Task Definition page depending on the selected
tab (Overview, Parameter and Context) within the Third Party UI Component.
To trigger the changes in the command bar it is possible to fire two events from the Third Party Component:
• "TaskDefinition:commandBarTypeChanged" with parameter "commandBarType" whose values can be
"overview", "parameter" or "context".
Example to change the command bar in order to view the actions corresponding to the Parameter tab:
$rootScope.$emit('TaskDefinition:commandBarTypeChanged', { commandBarType:
'parameter' });
• "TaskDefinition:selectionChanged" with the selected "row" as parameter:

Example to change the command bar after the selection/deselection of a row in the currently displayed tab:
function onSelectionChangeCallback(rows, row) {

$rootScope.$emit('TaskDefinition:selectionChanged', { row: row });
}
• Create a UI Component for managing tasks, along with screens for creating, editing and adding tasks. You can
use the following stateParams provided in input:

Process Apps
Task App
• $stateParams.componentStateParams.action: the corresponding action to be performed in the

screen, i.e. 'add'/'edit'/'view'
• $stateParams.componentStateParams.taskDefinitionId: the selected Task Definition Id
• $stateParams.componentStateParams.taskId: the selected Task Id (used in edit/view)
• $stateParams.componentStateParams.previousStateName: the previous $state, used to return to
the previous UI page from the custom component.
• Create a UI Component for managing the task status transitions, along with a screen which is displayed when the
status of tasks is set to In Progress. You can use the following stateParams provided in input:
• $stateParams.componentStateParams.taskId: the Task Id. It allows you to access, through an oData
query, the information related to the current task.
• $stateParams.componentStateParams.previousStateName: the name of the state (corresponding to
the Task Administration page) from which the custom UI is invoked. This parameter can be used to
change the state and close the UI and then go back to the Task Administration.
• Build the solution.
• Insert the custom task type with its corresponding UI components in the database initialization dbinit file, where:
• The TaskDefininitionUI property specifies the component to be used for creating, editing and viewing
the details of task definitions based on the custom task type.
• The TaskUI property specifies the component to be used when the status of tasks is set to In Progress.
Note: the contents of the command bar of the screen hosting the component cannot be driven
programmatically.
• The TaskInstanceUI property specifies the component to be used when creating, editing and adding
tasks based on your custom task type.
• The TaskMessagUI property specifies the component to be used, when an ErrorCode is set for a task and
the icon to view the information on the error is clicked.
<Entity type="Siemens.SimaticIT.MasterData.TSK_MS.MSModel.DataModel.TaskType">
<Property name="NId" kind="Plain" value="PartAndScrapCheckTaskType" />
<Property name="Name" kind="Plain" value="Part and Scrap Check" />
<Property name="Description" kind="Plain" value="Type of task for Part and
Scrap Check" />
<Property name="TaskEntityType" kind="Plain"
value="Siemens.SimaticIT.OperationalData.TSK_OP.OPModel.DataModel.ITask" />
<Property name="TaskDefinitionUI" kind="Plain"
value="Siemens.SimaticIT.TaskCUApp/
siemensSimaticitTaskcuappPartandscrapchecktaskdefinitioncomponent" />
<Property name="TaskMessageUI" kind="Plain" value="NULL" />
<Property name="TaskUI" kind="Plain" value="Siemens.SimaticIT.TaskCUApp/
siemensSimaticitTaskcuappPartandscrapcheckv2component" />
<Property name="TaskInstanceUI" kind="Plain"
value="Siemens.SimaticIT.TaskCUApp/
siemensSimaticitTaskcuappPartandscrapchecktaskcomponent" />
</Entity>
4.2.4.3 Configuring the Task List View Component

The Task App provides two UI Components which can be embedded in Mashup UI modules: Task List View
and Task Info.
These components are used for dashboard operator views, with clear schematic information and limited task
details, and are usually used together.

Process Apps
Task App
The Task List View component provides a dashboard view of the Task Administration, displaying all the tasks
within the system (whether created manually from the Task Administration, referred to as Tasks, or via Work
Orders, referred to as Work Order Tasks in versions prior to 3.0), their description, task type, date of creation and
last update, along with an icon and its color to represent their status.
It exposes two methods:
Command Mandatory Function
refresh Refreshes the grid that displays the tasks selected via
a filter.
It requires the oDataFilter string as an attribute,
which can be set to an oData $filter expression, for
example "NId eq 000000000000004" or "Name eq
\'Move Material\'" or "Status/StatusNId eq
\'InProgress\'".
If the string is empty, then all the tasks are displayed.
setCommandBarVisible Displays the command bar if its boolean attribute

visible is set to true.
If it is set to false, the command bar is not displayed
even if a task has been selected.
Procedure
1. Create a Mashup UI Module within your Solution in Solution studio, by clicking or Create New in the Mashup
page.
2. Provide a name, title and icon for the mashup UI module, and specify whether it will be securable or not.
3. Click Save.
4. Select the new Mashup UI Module and click .
5. In the UI Screen page, select your module and click .
6. In the UI Components tab, select the TaskListViewComponent in your App node in the toolbox and drag and
drop it into the layout design grid.
7. Click on the component and change its dimensions and position within the grid as required.
8. To define the mandatory Refresh method, click on the Wiring tab.
9. Click Add New and provide a name and optional description for the wiring.
10. Click Save.
11. From the Input-Output Components tile in the Components tab drag:
• the default mashup component to the Input Component section
• the siemensSimaticitTaskTaskListViewComponent to the Output Component section.
12. Click to create parameters for the module.
13. In the Parameters tab click Add New Parameter, and define its properties, as in the example:
Attribute Value
Name filter
Type String

Process Apps
Task App
Attribute Value
Default Status/StatusNId eq \'InProgress\' If a filter value is not specified, all

tasks are displayed.
14. Click Save.
15. In the Working Area click on the siemensSimaticitTaskTaskListViewComponent in the Output
Component section.
16. Click on the Configuration tab on the right-hand side, and select the following values from the drop-down lists:
Parameter Value
Source Event onLoad
Destination Method refresh
Parameter Binding filter

17. Click Apply.
18. Click .
19. Click Mashups in the sidebar.
20. Select your UI Module and click .
21. Click UI Applications in the sidebar.
22. Select your UI Application and click .
23. Click Associate UI Modules and select your new UI Module from the list.
24. Click Associate.
Optional procedure for removing the command bar

By default, the command bar is displayed in the UI Module. If you don't want to display the command bar, you must
create a new wiring for the setCommandBarVisible method as follows:
1. Select your Mashup UI Module and click .

2. Click on the Wiring tab.
3. Click Add New and provide a name and optional description for the wiring.
4. Click Save.
5. From the Input-Output Components tile in the Components tab drag:
• the default mashup component to the Input Component section
• the siemensSimaticitTaskTaskListViewComponent to the Output Component section.
6. Click to create parameters for the module.
7. In the Parameters tab click Add New Parameter, and define its properties as in the example:
Parameter Value
Name visible
Type boolean
Default false
8. Click Save.

Process Apps
Task App
9. In the working Area click on the siemensSimaticitTaskTaskListViewComponent in the Output

Component section.
Parameter Value
Source Event onLoad
Destination Method setCommandBarVisible
Parameter Binding visible

11. Click Apply.
12. Click .
4.2.4.4 Configuring the Task Info Component

The Task App provides two UI components, which can be embedded into a UI Mashup Module in Solution Studio:
Task List View and Task Info components.
These components provide a dashboard view of the task details, with clear, schematic information and limited task
details, and is appropriate for users such as operators.
The Task Info component provides information on a specific task, and is usually configured together with the Task
List View, so that when a task is selected in the Task List View, its details are displayed in the Task Info component.
The following information is displayed for each task, where available:
• NId
• Name
• Description
• TaskDefinition
• Status
• Sequence
• Task Flow
The task to be displayed can be identified by its Id or NId, and the component consequently exposes two methods,
one of which must be implemented:
Command Function
displayByTaskNId Identifies which task must be displayed, by specifying its NId.
displayByTaskId Identifies which task must be displayed, by specifying its Id.

This is the method to use, when the component is used together
with the Task List component.
Procedure
1. Select the Mashup UI Module you created for the Task List View component and click .
2. Drag the Siemens.SimaticIT.TaskInfoComponent into the layout design grid. Adjust dimensions as required
and save.

Process Apps
Work Instruction App
3. In the Wiring tab, click and provide a name and optional description for the wiring.
4. Click Save.
5. From the Input Components tile in the Components tab drag
the siemensSimaticitTaskTaskListViewComponent component to the Input Component section.
6. From the Output Components tile in the Components tab drag the
siemensSimaticitTaskTaskinfocomponent to the Output Component section.
Parameter Value
Source Event selectionChanged
Destination Method displayByTaskId or displayByTaskNId
Parameter Binding taskId > Id

8. Click Apply.
9. Click .
4.3 Work Instruction App

The Work Instruction App provides pages where it is possible to manage both work instructions in a user-friendly
environment and quality characteristics.
• UDM_RF
• WI_MS
• WI_OP
• ES_MS
• ES_SD
• CHR_MS
• CHR_OP
• DEF_MS
What can I do in the Work Instruction App?

• What are Work Instructions? provides useful conceptual information on Work Instructions.
• How to Manage Work Instruction Definitions describes how to create and configure Work Instruction Definitions.
• How to Manage Work Instructions describes how to create and execute Work Instructions.
• How to Promote a Work Instruction Definition to Task Definition describes the procedure to promote a Work
Instruction Definition to Task Definition by using WITask Extension App.
• What is Quality Execution? provides useful conceptual information on Quality Execution functionality.
• How to Configure Quality Execution describes how to configure Quality Execution functionality.

Process Apps
• How to Integrate and Use Quality Execution describes how to integrate and use Quality Execution functionality.
4.3.1 Work Instruction

Work Instructions are "documents" that provide specific instructions to carry out a specific activity, or task, by
means of a step by step guide.
In the manufacturing system, Work Instructions can be either instruction procedures which require an
acknowledgement from the user, or data collections/data captures which require an end user manual prompt.
4.3.1.1 What are Work Instructions?

A Work Instruction is a "document" that provides specific instructions to carry out a specific activity. It is usually
structured as a step by step guide that help you perform a specific task.
You can configure and use the following instruction types:
• Acknowledgement: It represents an instruction procedure that can be linked, for instance, to a work operation.
The instruction procedure can require an acknowledgment from the user.
• Data Collection/Data Capture: It represents a form used to collect data that requires end user prompts. The data
is then stored in the Manufacturing Solution repository.
Concepts
Work Instructions are based on the following:
• Work Instruction Templates - Master Data domain entities which act as templates for the creation of Work
Instruction Definitions.
• Work Instruction Context Definitions - Metadata which describes how to contextualize (i.e. link to operational
entities) runtime Work Instruction Instances.
• Work Instruction Definitions - Master Data domain entities that contain the information required to describe a
specific Work Instruction. Work Instruction Definitions can optionally be based on Work Instruction Templates
or linked to Work Instruction Contexts.
• Work Instruction Authoring Tool - A graphical editor used to create and modify a Work Instruction starting
from a specific Work Instruction Definition.
• Work Instructions - Operational domain entities, which are used to execute instances of Work Instruction
Definitions.
• Work Instruction Contexts - The actual context of a specific Work Instruction instance.
4.3.1.2 How to Manage Work Instruction Definitions

The creation of Work Instruction Definitions is made up of three main phases. First of all you will create a Work
Instruction Template, which can be reused as often as possible. Then, you will go through a more specific Work
Instruction Definition, based on the generic Work Instruction Template.
Once the Work Instruction Definition is correctly defined, you can detail its content, consisting of Work Instruction
Sections and Steps.
Workflow
1. Create Work Instruction Templates.
2. Create Work Instruction Definitions.
3. Manage Work Instruction Definition Contents.

Process Apps
4.3.1.2.1 How to Create Work Instruction Templates

Work Instruction Templates are templates for the definition of input/output parameters, which are inherited by
all Work Instruction Definitions that have used the Work Instruction template as a starting point.
Work Instruction Definitions can be based either on the default Work Instruction Template, or on any custom
defined Work Instruction Template or created from scratch without a template.
If the Audit Trail app is installed and configured to track Work Instruction Template data, the system will provide
evidence of all the operations that have been carried out on a specific Work Instruction Template. These records
can be viewed by selecting the particular Work Instruction Template and clicking on the Audit Trail tab of the Work
Instruction Template page.
Workflow
1. Add a new Work Instruction Template.
2. Set a Work Instruction Template as default.
3. Add Work Instruction Template Parameters.
Available Operations on Work Instruction Templates

To modify Work Instruction Template attributes, apart from the Id.

Edit
To delete the Work Instruction Template.

Delete
To export selected entities and instances in an export package that can be downloaded locally
Export
and imported afterwards. See How to Export and Import Data.
Available Operations on Work Instruction Template Parameters

To modify Work Instruction Templates Parameters, apart from the Id.

Edit
To delete the Work Instruction Template Parameters.

Delete

Process Apps
4.3.1.2.1.1 Adding a new Work Instruction Template

Work Instruction Templates are templates for the definition of predefined input/output parameters common to
more Work Instruction Definitions.
The parameters assigned to a Work Instruction Template are inherited by the Work Instruction Definitions that will
be based on that template, but you will have the possibility to modify the inherited parameters while configuring
the Work Instruction Definitions.
Procedure
1. Do either of the following to open the Work Instruction Templates page:
• Click the Work Instruction Templates home tile.

• Click Work Instruction Engineering in the side menu bar and click Work Instruction Templates.
2. In the Work Instruction Templates page, click .
3. Insert a mandatory unique Id for the new Work Instruction Template.
5. Click Save. The new Work Instruction Template is displayed in its own tile in the Work
Instruction Templates page.
 The Work Instruction Template page provides common functionalities such as Group By, Quick Search,
Filter and Mode. The Filter functionality provides a more refined search in addition to Quick Search. You
can filter Work Instruction Templates by Id, Name, Description, Created On, Last Updated On and Is
Default.
4.3.1.2.1.2 Setting a Work Instruction Template as default

If necessary, a Work Instruction Template can be set as default to facilitate the creation of Work
Instruction Definitions, as the user does not need to explicitly define which template must be used.
Only one Work Instruction Template at a time can be set to default, consequently this operation cannot be undone,
it is sufficient to set a different Work Instruction Template to default to remove the previously selected one.
Procedure

2. In the Work Instruction Templates page, click on the tile of the Work Instruction Template you want to set as
default.
3. Click .
4.3.1.2.1.3 Adding Work Instruction Template Parameters

After creating a Work Instruction Template, it is possible to define a set of predefined Parameters that must be
shared by all Work Instruction Definitions based on the template.
However, the inherited parameters can subsequently be either modified or deleted while configuring the Work
Instruction Definitions without impacting the original parameters assigned to the Work Instruction Template.
After being created, Work Instruction Template Parameters can be edited ( ) or deleted ( ).

Process Apps
Procedure

2. In the Work Instruction Templates page, select a Work Instruction Template and click to open the Work
Instruction Template Management page.
4. Add the following information:
Id The unique identifier assigned to the Work Instruction Template

Parameter. Once created, the Id value cannot be modified.
Type The data type of the Work Instruction Template Parameter value. The
meter, kilogram). This is enabled only when Work Instruction
Template Parameter's Type is Quantity.
Value (Optional) The default value of the Work Instruction Template

Parameter, displayed at runtime. If you select the Read Only option,
this value cannot be overwritten at runtime.
provided below for Bool, Datetime and Guid. If this field is left blank
when updating the value, it will be set to null.
• Bool - true/false
• DateTime - YYYY-MM-DD HH:mm:ss
• Guid - [a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}
Work Instruction Template Parameter cannot be saved.
Read Only If selected, indicates that the value of the parameter cannot be
modified or deleted when inherited by a Work Instruction Definition.
5. Click Save.

Process Apps
4.3.1.2.2 How to Create Work Instruction Definitions

Work Instruction Definitions contain the information required to describe a specific Work Instruction. Each Work
Instruction Definition consists of one or more Sections, that are organized as a sequence of Steps to be executed in
a given order.
Audit Trail is displayed in the Work Instruction Definition page to provide evidence of all the operations that have
been carried out on the specific Work Instruction Definition. Its records can be viewed by selecting the
particular Work Instruction Definition and clicking the Audit Trail tab.
Workflow
1. Add a new Work Instruction Definition.
2. Create a New Revision of a Work Instruction Definition.
3. Add Work Instruction Definition Parameters.
4. Set a Work Instruction Definition to Current.
Available Operations on Work Instruction Definitions

Edit To modify Work Instruction Definition attributes, apart from the Id and
Revision.
To delete a Work Instruction Definition.

Delete
Export (available from the To export a Work Instruction Definition to a JSON file.
command bar) Note: Electronic Signature Scenario associated to the Work Instruction
Definition Steps will not be exported along with their structures.
Export (available from the Allows you to export selected entities and instances in an export package
contextual command bar) that can be downloaded locally and imported afterwards.
exchange and Exporting and Importing Work Instruction Data for further
information on the import sequence of Work Instruction data.
Import To import a Work Instruction Definition from a JSON file.
Copy Revision To copy an existing Work Instruction Definition Revision.
Create new Revision To create a new revision of a Work Instruction Definition.
Set Current To set or unset a specific Work Instruction Definition Revision to current.
Unset Current

Process Apps
Lock To lock or unlock a specific Work Instruction Definition Revision, for

example to ensure that the one in use is not modified.
Unlock
4.3.1.2.2.1 Adding a New Work Instruction Definition

Work Instruction Definition is a blueprint of a Work Instruction instance where you can configure Steps to perform a
specific activity.
There are three ways to create new Work Instruction Definitions:
Creation Mode Details
From scratch A Work Instruction Definition can be created with or without

using a Work Instruction Template.
By copying an existing Work Instruction The newly created Work Instruction Definition inherits the
Definition Revision attributes of the original Work Instruction Definition, but has its
own Id and Revision. The inherited attributes, apart from the
base Work Instruction Template, can be modified and no
dynamic link exists with the source Work Instruction Definition.
By importing a Work Instruction Definition Work Instruction Definition files can be imported, along with
from a JSON file their content and parameters. Imported Work Instruction
Definition inherits all the contents and parameters of the
exported Work Instruction Definition.
The import action will either create or update a Work
Instruction Definition depending upon the below scenarios:
• If the Id and Revision do not correspond to any
existing Work Instruction Definition, the import
action will create a new Work Instruction Definition.
• If only the Id (not the Revision) corresponds to an
existing Work Instruction Definition, the import
action will create a new revision of the Work
Instruction Definition.
• If the Id and Revision correspond to an existing
Work Instruction Definition, the import action will
update by overwriting the existing one on
confirmation.
Note: If you want to import an existing Work Instruction
Definition in order to update it, do not modify the Id and/or
Revision displayed. If you change the Id and/or Revision, the
result is that a new Work Instruction Definition (or Revision) is
created instead of the existing one to be updated.
Once a Work Instruction Definition is created, you can add or modify Work Instruction Definition parameters.
It is also possible to modify a Work Instruction Definition by clicking on Edit.

Process Apps
Creating a Work Instruction Definition from scratch

1. Do either of the following to open the Work Instruction Definitions page:
• Click the Work Instruction Definitions home tile.

• Click Work Instruction Engineering in the side menu bar and click Work Instruction Definitions.
2. In the Work Instruction Definitions page, click .
3. For each Work Instruction Definition enter the following information:
Id A mandatory field to identify the Work Instruction Definition.

Once defined, this value cannot be modified.
Revision A mandatory field to identify the specific revision of the Work

Instruction Definition. Once defined, this value cannot be
modified.
Name An optional name for the Work Instruction Definition.
Description An optional description for the Work Instruction Definition.
Use Default Template (Optional) If selected, the Work Instruction Definition is based
on the Work Instruction Template defined as default.
Template (Optional) The Work Instruction Template on which the Work

Instruction Definition is based. If Use Default Template is
selected, this field is disabled.
4. Click Save. The new Work Instruction Definition is displayed in the Work Instruction Definitions page.
Copying an existing Work Instruction Definition Revision


2. In the Work Instruction Definitions page, select the tile of the Work Instruction Definition you want to copy.
3. Click .
4. Enter a new Id for the copied Work Instruction Definition. Once defined, this value cannot be modified.
5. Enter a new Revision for the copied Work Instruction Definition. Once defined, this value cannot be modified.
6. Click Save. The new Work Instruction Definition is displayed in the Work Instruction Definitions page.
Importing a Work Instruction Definition from a JSON file

Process Apps
2. In the Work Instruction Definitions page, click .
3. Enter the following information:
Upload a json file A mandatory field to select and upload a valid json file. Once you
upload a valid json file, the Id and Revision fields are
automatically populated, but if necessary you can modify the
displayed values.
Id A mandatory field to identify the Work Instruction Definition. Once

you import the Work Instruction Definition, this value cannot be
modified.
Revision A mandatory field to identify the specific revision of the Work

Instruction Definition. Once you import the Work Instruction
Definition, this value cannot be modified.
Name An optional name for the Work Instruction Definition.
Description An optional description for the Work Instruction Definition.

4. Click Import. The imported Work Instruction Definition is displayed in the Work Instruction Definitions page.
 The Work Instruction Definition page provides common functionalities such as Group By, Quick Search,
Search. You can filter Work Instruction Definitions by Id, Name, Revision and Is Current.
4.3.1.2.2.2 Creating a New Revision of a Work Instruction Definition

A Revision is used to identify a form of a Work Instruction Definition that is slightly different in certain aspects from
other forms of the same Work Instruction Definition.
Revisions prevent you from creating the entire Work Instruction Definition from scratch if any artifacts of the earlier
Work Instruction Definition have been changed or upgraded.
After creating a new Revision of a Work Instruction Definition, you can change it, not only defining new parameters
but also modifying or deleting those that have been inherited.
Procedure

2. In the Work Instruction Definitions page, select the tile of the Work Instruction Definition for which you want to
create a new revision.
3. Click .
4. Enter a new revision ID. Once defined, this value cannot be modified.
5. Click Save. The new Work Instruction Definition is displayed in its own tile in the Work
Instruction Definitions page. You can now add or modify Work Instruction Definition parameters.

Process Apps
4.3.1.2.2.3 Adding Work Instruction Definition Parameters

If Work Instruction Definitions are based on a Work Instruction template, they inherit its parameters.
New parameters can also be created for a Work Instruction Definition. Both, newly created parameters and
inherited parameters, can be modified by clicking on Edit.
Procedure

2. In the Work Instruction Definitions page, select a Work Instruction Definition and click to open the Work
Instruction Definition Management page.
4. For each Work Instruction Definition Parameter, add or modify the following information:
Id The unique identifier assigned to the Work Instruction Definition

Parameter. Once created, the Id value cannot be modified.
 The Work Instruction Definition Parameter Id must not

contain the keywords Contexts or Parameters and must
begin with a letter.
Type The data type of the Work Instruction Definition Parameter value. The
meter, kilogram). This is enabled only when Work Instruction
Definition Parameter's Type is Quantity.

Process Apps
Value (Optional) The default value of the Work Instruction Definition

Parameter, displayed at runtime. If you select the Read Only option,
this value cannot be overwritten at runtime.
provided below for Bool, Datetime and Guid. If this field is left blank
when updating the value, it will be set to null.
• Bool - true/false
• DateTime - YYYY-MM-DD HH:mm:ss
• Guid - [a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}
Work Instruction Definition Parameter cannot be saved.
The maximum number of characters for a string value is 255.
Read Only If selected, indicates that the default value of the parameter cannot be
modified or deleted at runtime.
5. Click Save. Parameters created for the Work Instruction Definition or those inherited from the Work Instruction
Template are listed in the Parameter tab.
4.3.1.2.2.4 Setting a Work Instruction Definition to Current

A specific revision of a Work Instruction Definition can be set to current in order to define which specific revision
should be used to create a Work Instruction.
Only one revision for each Work Instruction Definition (i.e. all the revisions with the same Work
Instruction Definition Id) may be set the current at any one time.
Procedure

2. In the Work Instruction Definitions page, click on the tile of the Work Instruction Definition revision you want
to set to current.
3. Click .
4.3.1.2.3 How to Manage Work Instruction Definition Contents

The Work Instruction system provides a dedicated environment to manage Work Instruction Contents. The contents
include Work Instruction Sections and Work Instruction Steps which can be defined, in the Work

Process Apps
Instruction Authoring Tool, once a Work Instruction Definition is created. You can provide the detailed steps of a
specific activity under Work Instruction Section.
To make the Work Instruction Definition executable, each Work Instruction Content must contain at least one
Section and each Section must have at least one Step.
A Work Instruction Step is a detailed instruction for performing a specific activity. You can define one or more steps
within a Work Instruction Section.
It can be of two types:
• Acknowledge containing detailed instructions that can be acknowledged by the user at runtime.
• Data Collection containing detailed instructions with data collection form which will be filled in by the user at
runtime.
Workflow
1. Add a new Work Instruction Section.
2. Create one of the following Work Instruction Steps:
• New Acknowledge Step
• New Data Collection Step
4.3.1.2.3.1 Adding a new Work Instruction Section

A Work Instruction Section is a collection of Work Instruction Steps. It provides you with an overall representation of
the activity you have to perform.
It must contain at least one Work Instruction Step.
You can create new Work Instruction Sections in two ways:
Creation Mode Details
From scratch A Work Instruction Section can be created by setting all

parameters one by one.
By copying an existing Work Instruction The copied Work Instruction Section inherits the attributes of
Section the original Work Instruction Section, but has a unique Id (auto
generated) which can be modified only once after copying.
The inherited attributes, except for the Id, can be modified and
no dynamic link exists with the source Work
Instruction Section.
A Work Instruction Section can be deleted by clicking . Deleting a Work Instruction Section will delete all the
steps created in the particular Work Instruction Section.
Creating a Work Instruction Section from scratch


create a Work Instruction Section and click .

Process Apps
3. Click to open the authoring tool.

4. Click in the navigation panel of the authoring tool, make sure that the Section option is selected, and then
click Add.
5. Provide the following information:
Id A mandatory field to identify the Work Instruction Section. Once

defined, this value cannot be modified.
The field value admits letters, digits and underscore character,
starting with a letter.
Title An optional title for the Work Instruction Section. Can be modified
after the creation of section.
6. Click Apply. The new section is displayed below the previously existing Section. You can now add Work
Instruction Steps to it (see Adding a New Acknowledge Step and Adding a New Data Collection Step).
7. If necessary, drag and drop the sections to re-order them.
8. Click Save.
Copying an existing Work Instruction Section


create a Work Instruction Section and then click .
3. Select an existing Work Instruction Section from the navigation panel of the authoring tool and click Copy
Section.
Copying a Work Instruction Section will copy all the steps of the selected Work Instruction Section. The copied
section is displayed below the previously selected Section.
4. Edit the following information (Optional):
Id A mandatory field to identify the Work Instruction Section. Once

edited, this value cannot be modified.
Title An optional title for the Work Instruction Section. Can be modified
after the copying the section.
5. Click Apply.
6. If necessary, drag and drop the sections to re-order them.
7. You can add / delete Work Instruction Steps in the copied Work Instruction Section.
8. Click Save.
4.3.1.2.3.2 Adding a New Acknowledge Step

An Acknowledge Step is a type of Work Instruction Step which contains detailed instructions to perform a particular
activity and needs to be acknowledged by the user at runtime. If required, you can associate a properly
configured Electronic Signature Scenario to a Work Instruction Step.

Process Apps
Once defined, Acknowledge Step attributes can be modified except for the Id.
Procedure

2. In the Work Instruction Definitions page, select the Work Instruction Definition for which you want to create a
Work Instruction Step and then click .
3. Select the Work Instruction Section to which you want to add the Work Instruction Step.
4. Click . The Step option is selected by default, click Add.
5. Provide the following information:
Attribute Definition
Type The type of a Work Instruction Step. Select the Acknowledge option.
Id A mandatory field to identify the Work Instruction Step. Once saved, this value
cannot be modified.
The field value admits letters, digits and underscore character, starting with a letter.
Title (Optional) The title to be displayed at runtime for the Work Instruction Step.
Instructions (Optional) Detailed information which is required by the user at runtime to

accomplish the step. Format the text using the buttons displayed in the toolbar. If
necessary:
• add images by clicking the icon.
• insert placeholders for Work Instruction Definition parameters by clicking
the icon. At runtime each placeholder will be replaced by the value of
the respective parameter.
Signature Scenario (Optional) The Electronic Signature Scenario that is necessary to complete the step.
This option is available only if Audit Trail app is installed in your Solution.
6. Click Apply. the new step is displayed under the previously selected Work Instruction Section.
7. If necessary, re-order the configured steps within the section.
8. Click .
4.3.1.2.3.3 Adding a New Data Collection Step

A Data Collection Step is a type of Work Instruction Step which contains detailed instructions to perform a
particular activity and prompts user to provide data at runtime.
This page describes how to configure new Data Collection Steps to be displayed at runtime to insert collected data.
If required, you can associate a properly configured Electronic Signature Scenario to a Work Instruction Step.
Once defined, Data Collection Steps can also be modified, apart from their Id.
Procedure

Process Apps

2. In the Work Instruction Definitions page, select the Work Instruction Definition for which you want to create a
Work Instruction Step and then click .
3. Select the Work Instruction Section to which you want to add the Work Instruction Step.
4. Click , make sure that the Step option is selected, and click Add.
5. Provide the following information in the Step Details tab:
Attribu Definition
te
Type The type of a Work Instruction Step. Select the Data Collection option.
Id A mandatory field to identify the Work Instruction Step. Once saved, this value cannot be
modified.
The field value admits letters, digits and underscore character, starting with a letter.
Title (Optional) The title to be displayed at runtime for the Work Instruction Step.
Instruc (Optional) Detailed information which is required by the user at runtime to accomplish the step.
tions Format the text using the buttons displayed in the toolbar. If necessary
• add images by clicking the icon.
• insert placeholders for Work Instruction Definition parameters by clicking the
icon. At runtime each placeholder will be replaced by the value of the respective
parameter.
Signat (Optional) The Electronic Signature Scenario grouping the signatures that are necessary to
ure complete the step. This option is available only if Audit Trail app is installed in your Solution.
Scenari
o
6. Click on the Data Collection Form tab.
7. Define the layout and content of the data collection form by dragging and dropping the Element Types of
interest. Each Data Collection Step can be composed of one or more Element Types. From a functional
perspective, Element Types can be grouped into four main categories: Elements for textual information,
Elements for numerical information, an Element for datetime information and Elements for custom
selection among a set of fixed values.
Functional Element Type Description
Category
Multiline Text You should use this Element when a multi-line text is expected to be
inserted at runtime. With this Element you can define Default Value, a
Element for
maximum allowed text Length and a Format to match the correctness of
textual
the runtime value.
information

Process Apps
Functional Element Type Description

Category
Single Input You should use this Element when you need to provide the runtime user
Text with a single-line input box. With this Element you can define Default
Value, a maximum allowed text Length and a Format to match the
correctness of the runtime value.
Single Input You should use this Element when either Integer or Decimal values are
Decimal needed to be hosted and managed; this Element provides the localization
support for decimal and thousands separator. You can define Default
Value, Low/High Limits, Target and associate a Unit of Measure to the
value.
Element for
numerical
Single Input You should use this Element when only Integer values are needed to be
information
Integer hosted and managed; this Element provides the localization support for
thousands separator. With this Element you can define Default Value,
Low/High Limits, Target and associate a Unit of Measure to the value.
Single Input You should use this Element when an Integer or a Decimal or a value
Numeric represented in exponential notation could be needed; this Element is not
taking into consideration any localization aspect like decimal or
thousands separators. With this Element you can define Default Value,
Low/High Limits, Target and associate a Unit of Measure to the value.
Element Datetime You should use this Element when a datetime information is expected; this
for datetim Element support the localization for managed values. With this Element
e you can define Default Value, Low/High Limits, Target and Format. The
information Format specifies how the datetime value will be shown at runtime.
Checkbox You should use this Element when a true/false choice is expected; this
Element supports the definition of the Default Value and Target (true |
Element
false).
for custom
selections
among a set Dropdown You should use this Element when you want to provide a fixed set of
of fixed possible values without providing a target value.
values
Multiple You should use this Element when you want to provide a fixed set of
Choice possible values by means of option buttons; this Element supports the
definition of the Target.
8. Configure the Element Type attributes by clicking next to the label of the required Element Type and then by
clicking .
9. Provide the needed information according to the selected Element Type. See Element Types of Data Collection
Steps.
 If necessary, it is possible to copy the existing Element Types in the form by clicking icon, instead of
inserting and then configuring new Element Types from scratch.

Process Apps
10. Click Apply: the new step is displayed under the previously selected Work Instruction Section.
11. If necessary re-order the configured steps within the section.
12. Click .
4.3.1.2.3.4 Element Types of Data Collection Steps

While configuring the Data Collection Step and after inserting the Element Type, you need to configure its common
and specific attributes.
For each of these attributes you can set values either manually or, only if specified, automatically, by means of a
binding operation between the attribute value itself and Work Instruction Definition Parameters.
What is Binding between Attributes and Work Instruction Definition Parameters

While configuring specific attributes of an Element Type, you can decide to bind their runtime value to a Work
Instruction Parameter.
In exploiting this configuration way, you can grant an higher flexibility in the usage of the same Work Instruction
Definition at runtime, consequently reducing the number of Work Instruction Definition needed at engineering
time. Indeed such a Work Instruction Definition will generate runtime Work Instruction Instances with Data
Collection Steps whose layout and content will be actualized in respect of the runtime values of the Work
Instruction Definition Parameters configured for the bound attributes.
When performing a binding, the system will support you in setting the association with the proper Work Instruction
Parameter by pre filtering only those Parameters that are eligible for the selected attributes taking into
consideration the Parameter direction (only Input and Input/Output directions are allowed) and datatype.
Element Type Common Attributes

Common attributes are mainly aimed to identify and drive the common characteristics of each Element, such as its
visibility at runtime and whether a value will be required at runtime or not.
Field Id A mandatory field to identify the Element Type. This field cannot be updated further.
Field (Optional) A brief explanation for the Element Type.

Caption
Field Label An alias name for the Element Type.
Required (Optional) If true, indicates that the value must be provided at runtime. You can select the
Required checkbox by selecting the Manual Value option or bind a parameter by selecting
the Binding option.
Binding Note: this attribute can be bound with Parameters whose datatype is Bool.
Read Only (Optional) If true, indicates that the value cannot be edited at runtime. You can select the Read
Only checkbox by selecting the Manual Value option or bind a parameter by selecting
the Binding option.
Binding Note: this attribute can be bound with Parameters whose datatype is Bool.

Process Apps
Element Type Specific Attributes

For each Element Type, specific attributes can be configured to specifically drive the runtime behavior. These
attributes are specific for each Element Type and depend on the scope of the Element Type they belong to:
• Element Types for Textual Information
• Element Types for Numerical Information
• Element Types for Datetime Information
• Element Types for Custom Selection
Element Types for Textual Information
This page describes the allowed configuration for Single Input Text and Multiline Text Element Types.
Single Input Text

With the Element Type selected in edit mode (see Element Types of Data Collection Steps), you can provide the
following information:
Placeholder Text (Optional) The text to be displayed within the Element Type when no runtime
value has been inserted.
Default Value The value to be auto populated in the corresponding Element Type at runtime.
You can provide the value by selecting the Manual Value option or bind a
parameter by selecting the Binding option.
The Binding attribute can be bound with Parameters whose datatype is String.
Format (Optional) Specify a valid JavaScript regular expression to be verified against

the format of the input value at runtime (see section below). You can provide
the value by selecting the Manual Value option or bind a parameter by
selecting the Binding option.
Binding Note: this attribute can be bound with Parameters whose datatype
is String.
Length (Optional) The maximum number of characters that can be inserted into the
Element Type. You can provide the value by selecting the Manual Value option
or bind a parameter by selecting the Binding option.
The Binding attribute can be bound with Parameters whose datatype is BigInt,
Int, SmallInt and TinyInt.
Multiline Text

Process Apps
Placeholder Text (Optional) The text to be displayed within the Element Type when no runtime value has
been inserted.
Default Value The value to be auto populated in the corresponding Element Type at runtime. You can
provide the value by selecting the Manual Value option or bind a parameter by selecting
the Binding option.
Format (Optional) Specify a valid JavaScript regular expression to be verified against the format of
the input value at runtime (see section below). You can provide the value by selecting
the Manual Value option or bind a parameter by selecting the Binding option.
Size (Optional) The size of the text-box which will be displayed at runtime. The following
options are available:
• Small
• Medium
• Large
Length (Optional) The maximum number of characters that can be inserted into the Element
Type. You can provide the value by selecting the Manual Value option or bind a
The Binding attribute can be bound with Parameters whose datatype is BigInt, Int,
SmallInt and TinyInt
Basic examples of a Regular Expression Definition

This section provides simple examples on how to define a regular expression to be applied against a Simple Input
Text or a Multiline Text value.
Use Case Example
I want to be sure that every entered value for my • Prefix: Siemens

textual attribute is respecting a well defined • A 6-digit serial number: 123456
pattern • Suffix: Test
Resulting Code: Siemens123456Test
Regular Expression: (Siemens)\d{6}(Test)

Process Apps
Use Case Example
I want to be sure that every entered phone • Could start with '+'
number is respecting a well defined pattern • Could be from 10 to 16 chars and digits length
• Must be composed by only space char and digits from 0
to 9
An accepted phone number: +49 123 456 7890
Regular Expression: ^(\+)?([ 0-9]){10,16}$
Use Case: I want to be sure every entered value for my textual attribute is respecting a well defined pattern
• Prefix: Siemens
• A 6-digit serial number: 123456
• Suffix: Test
Resulting Code: Siemens123456Test
Regular Expression: (Siemens)\d{6}(Test)
Use Case: I want to be sure every entered phone number is respecting a well defined pattern
• Could start with '+'
• Could be from 10 to 16 chars and digits length
• Must be composed by only space char and digits from 0 to 9
An accepted phone number: +49 123 456 7890
Regular Expression: ^(\+)?([ 0-9]){10,16}$
Element Types for Numerical Information
This page describes the allowed configuration for Single Input Numeric, Single Input Integer and Single Input
Decimal Element Types.
 The maximum number of supported digits is 15 for Low Limit, High Limit and Target fields (applicable
only for Single Input Numeric, Single Input Integer and Single Input Decimal) as the value might get
rounded-off automatically after 15 digits. A warning message appears for the same when the value
exceeds this limit.
Single Input Numeric


Process Apps
Default The value to be auto populated in the corresponding Element Type at runtime. You can provide
Value the value by selecting the Manual Value option or bind a parameter by selecting the Binding
option.
The Binding attribute can be bound with parameters whose datatype is Decimal, Integer,
SmallInt, TinyInt and Quantity.
You can clear the binding value as well as the pre filled and automatically selected UoM value by
clicking the Clear Binding button.
UoM (Optional) The base unit for measuring a physical quantity for the Element Type. You can provide
the value by selecting the Manual Value option or bind a parameter by selecting the Binding
option.
The Binding attribute can be bound with parameters whose datatype is String
You can remove the Manual and Binding values by clicking the Clear button.
Low Limit (Optional) The minimum value that can be inserted into the Element Type. It is visible at runtime
when its Visible check box is selected. You can provide the value by selecting the Manual Value
option or bind a parameter by selecting the Binding option.
At runtime, if the actual value will exceed this limit, a warning message will inform the user but
the user will not be prevented from saving the value.
Target (Optional) The expected value to be collected at runtime. It is visible at runtime when its Visible
check box is selected. You can provide the value by selecting the Manual Value option or bind a
High Limit (Optional) The maximum value that can be inserted into the Element Type. It is visible at runtime
when its Visible check box is selected. You can provide the value by selecting the Manual Value
At runtime, if the actual value will exceed this limit, a Warning message will inform the user but
the user will not be prevented from saving the value.
Single Input Integer


Process Apps
the Binding option.
The Binding attribute can be bound with parameters whose datatype is Integer, SmallInt,
TinyInt and Quantity.
You can clear the binding value as well as the pre-filled and automatically selected UoM
value by clicking the Clear Binding button.
UoM (Optional) The base unit for measuring a physical quantity for the Element Type. You can
the Binding option.
The Binding attribute can be bound with parameters whose datatype is String
Low Limit (Optional) The minimum value that can be inserted into the Element Type. It is visible at
runtime when its Visible check box is selected. You can provide the value by selecting
At runtime, if the actual value will exceed this limit, a warning message will inform the user
but the user will not be prevented from saving the value.
Target (Optional) The expected value to be collected at runtime. It is visible at runtime when its
Visible check box is selected. You can provide the value by selecting the Manual Value
High Limit (Optional) The maximum value that can be inserted into the Element Type. It is visible at
Single Input Decimal


Process Apps
provide the value by selecting the Manual Value option or bind a parameter by
The Binding attribute can be bound with parameters whose datatype is Decimal,
Integer, SmallInt, TinyInt and Quantity.
You can clear the binding value as well as the pre-filled and automatically selected
UoM value by clicking the Clear Binding button.
UoM (Optional) The base unit for measuring a physical quantity for the Element Type. You
can provide the value by selecting the Manual Value option or bind a parameter by
The Binding attribute can be bound with parameters whose datatype is String.
Low Limit (Optional) The minimum value that can be inserted into the Element Type. It is visible
at runtime when its Visible check box is selected. You can provide the value by
selecting the Manual Value option or bind a parameter by selecting the Binding
option.
At runtime, if the actual value will exceed this limit, a warning message will inform the
user but the user will not be prevented from saving the value.
Target (Optional) The expected value to be collected at runtime. It is visible at runtime when
its Visible check box is selected. You can provide the value by selecting the Manual
Value option or bind a parameter by selecting the Binding option.
High Limit (Optional) The maximum value that can be inserted into the Element Type. It is visible
at runtime when its Visible check box is selected. You can provide the value by
selecting the Manual Value option or bind a parameter by selecting the Binding
option.
At runtime, if the actual value will exceed this limit, a warning message will inform the
user but the user will not be prevented from saving the value.
Number of Decimal Truncates the Value, Limits and Target field values after their decimal point with the
Digits inserted value.
Element Types for Datetime Information

This page describes the allowed configuration for Datetime Element Type.

Process Apps
 The value set for Low Limit is Current Date and 12:00:00 AM as time, while the value set for High Limit is
Current Date and 11:59:59 PM as time, referring to when the date time picker is opened.
Datetime attributes
Default Value The value to be auto-populated in the corresponding Element Type at runtime. You can
the Binding option.
Binding Note: this attribute can be bound with parameters whose datatype is Datetime.
Format (Optional) You can specify a datetime format with the Format field of the Element Type (see
dedicated section below). A preview of the specified format is displayed below the textbox,
as you type. The format will be applied at runtime to the selected datetime value.
You can provide the value by selecting the Manual Value option or bind a parameter by
Binding Note: this attribute can be bound with parameters whose datatype is String.
Low Limit (Optional) The minimum value that can be inserted into the Element Type. It is visible at
High Limit (Optional) The maximum value that can be inserted into the Element Type. It is visible at
At runtime, if the actual value will exceed this limit, a Warning message will inform the user
Target (Optional) The expected value to be collected at runtime. It is visible at runtime when
its Visible check box is selected. You can provide the value by selecting
Details about supported Datetime formats

Format specifier can contain literals that will be output as-is. If you want to use one of the element as literal, you
can escape it using single quote character.

Process Apps
Example date and time: Thursday, Nov 12th, 1970 at 4:20:00 AM in Genoa, Italy UTC+1, following the en-EN culture
Syntax element Description Exampl

e
yyyy 4 digit representation of the year 1970
yy 2 digit representation of the year 70
MMMM Month in the year (full name, according to culture) Novemb

er
MMM Month in the year (abbreviation, according to culture) Nov
MM Month in the year (padded 01-12) 11
M Month in the year (1-12) 11
dd Day in the month (padded 01-31) 12
d Day in the month (1-31) 12
HH Hour in the day (padded 00-23) 04
H Hour in the day (0-23) 4
hh Hour in AM/PM (padded 01-12) 04
h Hour in AM/PM (1-12) 4
mm Minute in hour (padded 00-59) 20
m Minute in hour (0-59) 20
ss Second in minute (padded 00-59) 00
s Second in minute (0-59) 0
a AM/PM marker AM
Z 4 digits timezone offset (with sign) +01:00
ww Week of the year (padded 00-53) 46
w Week of the year (0-53) 46

Element Types for Custom Selection
This page describes the allowed configuration for Checkbox, Dropdown and Multiple Choice Element Types.
Checkbox

Process Apps
Default Value The value to be auto populated in the corresponding Element Type at runtime.
You can provide the value by selecting the Manual Value option or bind a
The Binding attribute can be bound with parameters whose datatype is Bool.
Target (Optional) The expected value to be collected at runtime. It is visible at runtime

when its Visible check box is selected. You can provide the value by selecting
The Binding attribute can be bound with parameters whose datatype is Bool.
Dropdown
Placeholder Text (Optional) The text to be displayed within the Element Type when no runtime value
has been inserted.
Labels - Values A set of options to be displayed at runtime. For each option specify:
• Label: the string identifying the option in the UI at runtime.
• Value: the value to be saved on the database when the user selects the
corresponding string.
Multiple Choice
Value A list of options to be displayed at runtime. Available only for Multiple

Choice.
4.3.1.2.4 Exporting and Importing Work Instruction Data

The Work Instruction App allows you to export and import its own master data entities. Unlike the Work Instruction
Template, you can import/export Work Instruction Definitions as documented at Adding a New Work Instruction
Definition.

Work Instruction Definitions must be exported and imported not by following the current section, but using the
procedure documented at How to Create Work Instruction Definitions, which leverages JSON file format.

Process Apps
Work Instruction Work Notes

Template Instruct
ion
Definiti
on from
JSON
file
Work Instruction If you export any Work Instruction Template the

Template related parameters are also automatically exported.
Work Instruction
Definition
4.3.1.3 How to Manage Work Instructions

When a Work Instruction Definition has been created and configured, it is ready to be instantiated and consequently
executed.
At runtime Work Instruction Definitions are called Work Instructions.
Available Operations on Work Instructions

Abort To abort a Work Instruction.
Add To create Work Instructions.
Enable Auto Refresh To enable or disable Auto Refresh of the Work Instruction list.
See Executing Work Instructions.
Disable Auto Refresh
To delete a Work Instruction.

Delete
Hide/Unhide Filter To load Work Instructions.
Open Work Instruction Execution To open and execute Work Instructions.
4.3.1.3.1 Creating Work Instructions

Work Instructions represent the runtime instances of the Work Instruction Definitions.
The Work Instructions of interest can be displayed in the Work Instruction List page after setting the proper filters.

Process Apps
Prerequisites
A Work Instruction Definitions that contains at least one Step already exists.
Procedure
1. Do either of the following to open the Work Instruction List page:
• Click the Work Instruction List home tile.

• Click Work Instruction Runtime in the side menu bar and click Work Instruction List.
2. In the Work Instruction List page, click .
3. In the Select Work Instruction Definition page select the Work Instruction Definition on which the Work
Instruction will be based.
4. Insert a mandatory unique Id for the new Work Instruction.
6. If required, select the Re-Edit check box to re-edit the step after acknowledgment.
7. Click the Input Parameter tab, enter values for the input parameters specified for your Work Instruction
Definitions. Default values are displayed and can be modified. If parameters have been set as read-only they
cannot be modified.
8. Click Save.
4.3.1.3.2 Loading Work Instructions

Since the production execution requires configuring a huge amount of Work Instructions, it is necessary to set some
fields in order to identify the Work Instructions of interest among all those that have been created.
Procedure

2. In the Work Instance List page, click the icon to open the Filters panel.
3. Set the following parameters, or a subset of them, in order to define the Work Instructions to be displayed:
• Definition Id, the Identifier of the Work Instruction Definition whose instances you want to display.
• Revision, the Revision of the Work Instruction Definition whose instances you want to display.
• Id, insert a string corresponding to the initial part of the Work Instructions Ids you want to display.
• Status, select the check boxes relative to the statuses to be displayed.
4. Click Apply.
4.3.1.3.3 Executing Work Instructions

Each Work Instruction can consist of multiple Sections which, in turn, can consist of multiple Steps of different type.
At runtime, Sections and Steps are displayed according to the configured sequence and the user is forced to
manage them to complete the assigned work. All Work Instruction Sections can be expanded ( button ) or
collapsed ( button ) for better readability.
If the Electronic Signature Scenario is associated with any of the Steps, the relevant users must sign that
particular step to complete it.
When one Step is completed, the system automatically displays the next step either belonging to the same section
or starting the next section (if the previous section has been completed).

Process Apps
Work Instruction Step Items configured as semi-automatic are characterized by an Acquire button, that allows the
user to acquire data automatically.
The values entered by the user in a Data Collection Step are saved automatically and the user's name is recorded
(over written if another user confirms with a different value).
When a Work Instruction is opened for the first time in the Work Instruction Execution screen, the status of the
Work Instruction is changed to In Editing, and once all the Sections are completed, it is changed to Completed.
The data within the Work Instruction List page can be automatically refreshed if the auto refresh button is
properly enabled. You can enable or disable the auto refresh option of the Work Instruction List by clicking
button to enable or button to disable the auto refresh. The auto refresh option is disabled by default on page
load. If the auto refresh is disabled, click Apply in Filters panel to view the updated list.
A Work Instruction with state In Editing, can be aborted by clicking the icon.
Procedure
 The following procedure describes how to use the Work Instruction List page which can be used as a test
page to verify the final layout and content of the configured Work Instruction.
In a real scenario, the Work Instruction runtime functionality will be embedded in a custom screen by
means of the sitWorkInstructionInstanceViewer widget in the final UI Application.

2. In the Work Instruction List page, set the provided filters to load the Work Instructions of interest.
3. Select the Work Instruction to be executed.
4. Click Open Work Instruction Execution: the sections within the Work Instruction and its related steps are
displayed.
5. According to the Step type which is displayed, perform one of the following operations:
• Acknowledge type: read the provided instructions and then click Acknowledge.
• Data Collection type: read the provided instructions; click the Acquire button (if available) to
automatically populate the data, enter or modify the required data, and then click Confirm.

Process Apps
 • A warning icon appears beside the field label whenever the binding of any parameter
resolution fails, and once you click the icon, the list of warning messages will be
displayed.
• The maximum number of digits supported is 15 for the inserted value (applicable only
for Single Input Numeric, Single Input Integer and Single Input Decimal) as the value
might get rounded-off automatically after 15 digits. A warning message appears for the
same when the value exceeds this limit.
• When for a value Low Limit and High Limit are defined, and the value exceeds these
limits, a warning message will inform the user for the same, but it will not prevent the
user from saving the value.
• The latest change to the value of the Data Collection Item is automatically inherited by
the bound Work Instruction Parameter when the Work Instruction is completed, unless
the Parameter is defined as Read Only or its Direction is set to Input.
• Necessary modifications can be made for an acknowledged/confirmed Step by clicking
Re-Edit.
6. If the Electronic Signature Scenario is associated with the Step, click the Sign button and provide the User
Credential along with the comment (optional) to approve or reject the Step. It logs the Electronic Signature
details along with the status and inserted comments in the Audit Trail Records.
 The Step will complete only if all the relevant users approve it. If the Step is rejected, then the user
should repeat step 5.
7. Repeat step 5 for each displayed Step, until all sections are executed.
4.3.1.4 How to Promote a Work Instruction Definition to Task Definition

A Work Instruction Definition can be promoted to Task Definition (of Work Instruction Task Type). To do this, you
have to add the WITask Extension App to your Solution.
The WITask App references the following Functional Blocks:
• EQU_MS
• EQU_OP
• ES_MS
• ES_SD
• TSK_OP
• UDM_RF
• WI_MS
• WI_OP
• WI_TSK_MS
• WI_TSK_OP
• CHR_MS
• CHR_OP
Once you have added the WITask App to your Solution, you will be able to manage the Task Definitions of Work
Instruction Task Type.

Process Apps
Workflow
1. Add the WITask App to your Solution.
2. Add a Mashup UI Module for WITask App to your Solution.
3. Reconfigure your UI Application by associating the Mashup UI Module added in step 2, as described in
Configuring UI Applications in the Opcenter Execution Foundation Development and Configuration Guide.
4. Redeploy your Solution, as described in How to Deploy a Manufacturing Solution in the Opcenter Execution
5. Once your Solution has been redeployed, the following operations can be performed:
• Creating a Task Definition of Work Instruction Task Type.
• Creating and Executing a Task of Work Instruction Task Type.
• Executing a Work Instruction Linked to Task.
Adding the WITask App to your Solution

2. In the Installed tab, click the icon on the WorkInstruction App.
3. In the Extensions tab, click Refresh Extensions. The system displays the WITask tile.
4. Click in the tile of the WITask Extension App to add it to your solution.
Adding a Mashup UI Module for WITask App to your Solution

1. Create a Mashup UI Module (see Creating a Mashup UI Module in the Opcenter Execution
2. Click within the tile of the newly created Mashup UI Module.
3. In the UI Screen page, select the screen you want to configure and click the arrow icon .
4. Click on the UI Components tab in the toolbox on the right-hand side and click on
the Siemens.SimaticIT.WITask.
5. Drag and drop the WorkInstructionComponent and WITaskDefinitionComponent onto the editor.
6. Click to save the Mashup UI Module.
7. Navigate to the Mashups page and select the Mashup UI Module which you configured in the above steps. For
this step refer to Designing Mashup UI Modules in the Opcenter Execution Foundation Development and
8. Click .
9. Hide the Mashup UI Module from the sidebar (the module must then not be directly accessed at runtime). For
adding or removing items from the sidebar, see Configuring the UI Application Menu in the Opcenter Execution
4.3.1.4.1 Creating a Task Definition of Work Instruction Task Type

A Work Instruction Definition can be promoted to Task Definition by creating a Task Definition of a custom task type
i.e WorkInstructionTask type.

Process Apps
Once a Task Definition of WorkInstructionTask type is created, all the parameters of the linked Work Instruction
Definition are inherited by the Task Definition. These parameters can be modified or new parameters can be added
to it.
A Task Definition of WorkInstructionTask type can be modified by clicking on Edit.
 Once the Work Instruction Definition Id and/or Work Instruction Definition Revision of the Task
Definition are modified, all the existing parameters will be replaced by the parameters of the newly linked
Work Instruction Definition.
Procedure

2. In the Task Definitions page, click the button and select Add Work Instruction Task Type.
3. For each Task Definition of type WorkInstructionTask, enter the following information:
Id The unique identifier of the Task Definition. Once defined,

Revision The specific revision of the Task Definition. Once defined,

Name (Optional) A name assigned to the Task Definition.
Description (Optional) An additional information on the Task

Definition.
Work Instruction Definition Id The Id of the Work Instruction Definition which will be
linked to the Task Definition.
Work Instruction Definition Revision The Revision of the Work Instruction Definition which will
be linked to the Task Definition.
4. Click Save. The new Task Definition is displayed in the Task Definitions page.
5. Click to open the Task Definition page, the linked Work Instruction Definition details are displayed in
Overview tab, and parameters of the linked Work Instruction Definition are listed in the Parameter tab.
4.3.1.4.2 Creating and Executing a Task of Work Instruction Task Type

A Work Instruction instance can be created from Task instance at runtime, to get the instructions to perform the
specific task.
User can acknowledge/confirm the Steps of the Work Instruction during Task Execution.
Prerequisites
A Task Definition of type Work Instruction Task with fully configured Work Instruction Definition (i.e. having at
least one Section and one Step) should exist.

Process Apps
Procedure
1. Create a Task from a Task Definition of type Work Instruction Task in Task Administration page.
2. Select a task (of type Work Instruction Task) and click the icon that corresponds to the required action.
Icon Action Required starting status Target status Outcome
for WI Task
Activate • Created Ready A Work Instruction instance

• Not Ready will be created with
the Id, Name and Description
of the Task in Work
Instruction List page and can
be executed.
 If any error occurs

while creating the
Work Instruction
instance, the Task will
be moved to Not
Ready state.
Start • Ready In Progress A Task Execution screen will be

displayed with the
contents(i.e., Sections and
Steps) of the linked Work
Instruction, changing its state
from Created to In Editing, to
perform the task accordingly.
Complete • In Progress Completed Completes the Task only if the

linked Work Instruction or all its
sections are completed.
Cancel • Created Canceled No change in the status of the

• Ready linked Work Instruction.
Abort • In Progress Aborted Aborts the linked Work

Instruction.
 If the Task Execution screen of a WI Task is closed and its state is In Progress, the Task will be moved
to Paused state.
4.3.1.4.3 Executing a Work Instruction Linked to Task

A Work Instruction can be executed in the Work Instruction List page once it is created by activating a Task in Task
Administration page.

Process Apps
 When a Work Instruction, linked to a Task, is deleted, the status of the Task will be changed to Aborted/
Canceled/Failed according to its current status.
Prerequisites
A Work Instruction linked to a Task should exist.
Procedure

2. In the Work Instruction List page, set the provided filters to load the Work Instructions of interest.
3. Select a Work Instruction (linked to any Task) and click the icon that corresponds to the required action.
Icon Action Required starting Target status Outcome
status for Work
Instruction
Open Work Created In Editing Opens the Work

Instruction Execution Instruction Execution
screen and changes the
status of the linked Task
from Created to In
Progress.
Abort In Editing Aborted Aborts the linked Task

only if it is either in In
Progress or Paused
state.
 Once the linked Work Instruction is completed,

• The status of the Task will be changed from In Progress to Completed.
The Task parameter values will be updated with the same values of the linked Work Instruction
• parameters belonging to the same configuration.
4.3.2 Quality Execution

Quality Execution is the Opcenter Execution Foundation functionality which allows you to verify the quality of
products in an industrial environment, managing specific quality characteristics and potential problems that can be
detected during the life cycle of a product or process. In case of detected defects, Quality Execution
functionality allows correcting the causes of defective products by applying appropriate quality actions.
At runtime, Quality Execution functionality allows acquiring samples, during the life cycle of a product or process,
for each produced item or at the specified interval of them.

Process Apps
4.3.2.1 What is Quality Execution?

Quality Execution is the Opcenter Execution Foundation functionality which allows you to verify the quality of
products in an industrial environment.
In the engineering phase, you can manage specific quality characteristics that can concern:
• whether a produced material respects a specific characteristic or not
• any measurement with respect to allowed tolerances
• whether visual defects have been detected in a produced material.
It is also possible to manage potential problems that can be detected during the life cycle of a product or process. In
case of detected defects, you can correct the causes of defective products by applying appropriate quality actions.
Once defined how the quality characteristics must be acquired at runtime, in the runtime phase Quality Execution
allows you to acquire samples during the life cycle of a product or process.
Before approaching Quality Execution functionality, you need to know some useful base concepts which are the
groundwork to using Quality Execution.
What are Quality Characteristics and Inspection Definitions

The Work Instruction app provides a dedicated environment where you can manage quality characteristics
(Quality Characteristics) that allows you to verify the quality of your products.
Quality Characteristics allows you to:
• Define whether a produced material respects a specific characteristic or not (Attributive
Characteristics). Example: you are inspecting a car and checking whether the paint is used to paint the car (the
paint is available) or not.
• Get information on measurements and allowed tolerances, indicating whether a produced material respects a
specific measurement, like length, weight, thickness (Variable Characteristics). Example: you are inspecting a
car and checking that the paint thickness is the required one, according to defined tolerances.
• Know whether visual defects (scuff marks, paint drops) have been detected in a produced material (Visual
Characteristics). Example: you are inspecting a car and checking whether scuff marks are detected in the car
paint.
Any potential problem (Failure), which can be occurred during the life cycle of a product or process, can be
associated with Quality Characteristics.
How Quality Characteristics must be acquired at runtime is defined by the Inspection Definitions that are
associated with Quality Characteristics.
The Inspection Definition is an entity that defines how the Quality Characteristics are acquired at runtime. The
Quality Characteristic must be acquired mainly through the definition of the Sample Size, to determine the number
of measures allowed for each Sample and of the Frequency, to describe how often a Quality Characteristic must be
collected. If you assign a Signature Scenario, then a set of Electronic Signatures is requested to configure the
related Signatures (according to the Electronic Signature Scenario configuration).
The Inspection Definition also supports the definition of Revision and the related capabilities (Copy Revision,
Create New Revision, Lock Revision).
What are Failures and Quality Actions

The Defect App provides a dedicated environment to manage potential problems (Failures), which can occur
during the life cycle of a product or process, and all operations required to resolve them (Quality Actions).
Detected Failures can be assigned to Quality Characteristics and organized in more specific Sub-Failures, as well
as Quality Actions can be organized in Quality Sub-Actions, representing more specific actions to be performed.

Process Apps
the detected Failures. Attachments can be text files, videos and images and can be created and assigned to Failures.
For more information, see Defect App.
4.3.2.2 How to Configure Quality Execution

Here is an outline of the main macro-steps required to configure Quality Execution functionality properly. The
guideline also provides the following information:
• Which Apps are required for Quality Execution?
• What is an Inspection Task Definition?
Prerequisites
In Solution Studio, your Solution has been correctly configured installing all required Apps listed in Which Apps are
required for Quality Execution?.
Workflow
1. From the Defect App, create the required Failures and Quality Actions, with the related Sub-Failures and Sub-
Quality Actions (if needed), and associate Failures/Sub-Failures with Quality Actions, as described in How to
Manage Failures and Quality Actions. You can also create Attachments and associate them with Failures.
2. From the Work Instruction App, create the required Quality Characteristics, assign Failures to Quality
Characteristics and create Inspection Definitions, as described in How to Manage Quality Characteristics and
Inspection Definitions.
3. From the Task App, configure an Inspection Task. The system will populate your custom runtime
environment with all required data.
Diagram
The following diagrams show the described workflow. It has been split in different phases to make the
configuration easier.
Phase 1
Phase 2

Process Apps
Phase 3
4.3.2.2.1 Which Apps are required for Quality Execution?

To correctly configure and use Quality Execution functionalities, the following Apps need to be installed in your
Solution.
App Name Why you need to install it
Defect Required to manage Failures and Quality Actions, with the related Sub-Failures and
Sub-Quality Actions, and Attachments in the engineering phase.

Process Apps
App Name Why you need to install it
QEMigration Optional. It is required only if you want to migrate existing Failures (created in
platform version 3.0) from Work Instruction App to Defect App.
(Extension of Defect
App)
Work Instruction Required to manage Quality Characteristics and Inspection Definitions in the
engineering phase.
WITask Required to manage Inspection Definitions at runtime.

(Extension of Work To add the WITask App to your Solution, see Adding WITask App to your Solution.
Instruction App)
Task Required to manage the Inspection Task Definition and the related Task.
Material Required to manage the Material and the Material Tracking Unit, needed to move
the Material, to be configured in the Task.
Equipment Required to create the Equipment to be associated with the Task.
Reference Required due to references to all the other Apps.
BPFlow Optional. It is required only if you want to use the Inspection Task Definition within
a Business Process Flow.
Data Segregation Optional. It is required only if you want to assign segregation tags to Quality
Characteristics, Failures or Quality Actions.
4.3.2.2.1.1 Adding WITask App to your Solution

In order to manage Inspection Definition at runtime, you need to add an Extension App as a customized extension
of the Work Instruction App to your Solution. For this purpose, a dedicated Extension App, WITask named, is
provided.
The WITask App references the following Functional Blocks:
• UDM_RF
• WI_MS
• WI_OP
• TSK_MS
• TSK_OP
• WI_TASK_MS
• WI_TASK_OP

Process Apps
Once you have added the WITask App to your Solution and redeployed the Solution, a dedicated Task Definition,
named Inspection, will be created and displayed in the Task Definition page of the Task App.
From the Inspection Task Definition, you can create a runtime Task in the Task Administration of the Task App.
Once activated, this Task will populate your custom runtime environment with all required data.
Procedure
2. In the Installed tab, click on the WorkInstruction App.
3. In the Extensions tab, click . The system displays the WITask tile.
4. Click in the tile of the WITask Extension App to add it to your solution.
4.3.2.2.2 What is an Inspection Task Definition?

The Inspection Task Definition is a dedicated Task Definition that the system creates in the Task Definition page of
the Task App by default when both Work Instruction App and WITask Extension App are installed in your Solution.
The Inspection Task Definition is created with a defined structure during the Solution deployment via database
initialization (dbinit) file. For information on the structures of the Inspection Task Definition and the dbinit file,
see Inspection Task Definition Structure and DbInit File Structure respectively.
From the Inspection Task Definition, you can create a runtime Task (Inspection Task) to populate your custom
runtime environment with all required data.
Inspection Task Definition Structure

The Inspection Task Definition consists of the following:
Tab/Page Involved Data Description
Parameter tab of the Task MTU The Material Tracking Unit required to move
Definition page Materials. For more information, see
Material App.
RTInspectionDefContainer The container of the runtime Inspection

Definitions.
Context tab of the Task InspectionContext The context of the Inspection Task
Definition page Definition. For more information, see How
to Define Task Context Definitions.
User Field tab of the Task MaterialNId The Material you want to associate with the
Context Definition page Material Tracking Unit.

Process Apps
Tab/Page Involved Data Description
MaterialRevision The Material revision associated with the

Material Tracking Unit.
 We suggest that you do not either modify parameters or remove the association between context and Task
Definition to avoid malfunctions.
DbInit File Structure

Process Apps
DBINIT File Structure
<Entity type="Siemens.SimaticIT.MasterData.TSK_MS.MSModel.DataModel.TaskContextDe
finition">
<Property name="NId" kind="Plain" value="InspectionContext" />
<Property name="Name" kind="Plain" value="InspectionContext" />
<Property name="Description" kind="Plain" value="Quality Execution Inspection
Context" />
ionalData.TSK_OP.OPModel.DataModel.ITaskContext" />
</Entity>
finitionUserField">
<Property name="NId" kind="Plain" value="MaterialNId" />
<LogicalKey entityType="Siemens.SimaticIT.MasterData.TSK_MS.MSModel.DataModel
.TaskContextDefinition">
</LogicalKey>
</Property>
</Entity>
finitionUserField">
<Property name="NId" kind="Plain" value="MaterialRevision" />
</LogicalKey>
</Property>
</Entity>
<Entity type="Siemens.SimaticIT.MasterData.TSK_MS.MSModel.DataModel.TaskDefinitio
n">
<Property name="Revision" kind="Plain" value="1" />
<Property name="Name" kind="Plain" value="Inspection" />
<Property name="Description" kind="Plain" value="Quality Execution Inspection
Task Definition" />
<Property name="TaskDefinitionUI" kind="Plain" value="NULL" />
<Property name="TaskMessageUI" kind="Plain" value="NULL" />
<Property name="TaskTypeNId" kind="Plain" value="TSKType" />
<Property name="NId" kind="Plain" value="Inspection" />
<Property name="TaskUI" kind="Plain" value="Siemens.SimaticIT.WITask/
siemensSimaticitWitaskQualityexecution" />
<Property name="TaskEntityType" kind="Plain" value="Siemens.SimaticIT.MasterDat
a.TSK_MS.MSModel.DataModel.TaskDefinition" />
<Property name="TaskInstanceUI" kind="Plain" value="NULL" />

Process Apps
<Property name="TaskTypeIcon" kind="Plain" value="NULL" />

<Property name="TaskContextDefinitions" kind="ManyToManyReference">
</LogicalKey>
</Property>
</Entity>
nParameter">
<Property name="NId" kind="Plain" value="RTInspectionDefContainer" />
<Property name="ParameterValue" kind="Plain" value="NULL" />
<Property name="ParameterUoMNId" kind="Plain" value="NULL" />
<Property name="Direction" kind="Plain" value="Input_Output" />
<Property name="IsReadOnly" kind="Plain" value="False" />
<Property name="ParameterType" kind="Plain" value="String" />
<Property name="TaskDefinition" kind="SingleReferenceToParent">
.TaskDefinition">
</LogicalKey>
</Property>
</Entity>
nParameter">
<Property name="NId" kind="Plain" value="MTU" />
<Property name="ParameterValue" kind="Plain" value="NULL" />
<Property name="ParameterUoMNId" kind="Plain" value="NULL" />
<Property name="Direction" kind="Plain" value="Input_Output" />
<Property name="IsReadOnly" kind="Plain" value="False" />
<Property name="ParameterType" kind="Plain" value="String" />
<Property name="TaskDefinition" kind="SingleReferenceToParent">
.TaskDefinition">
</LogicalKey>
</Property>
</Entity>
4.3.2.2.3 How to Manage Quality Characteristics and Inspection Definitions

The Work Instruction app allows you to manage Quality Characteristics that allows you to verify the quality of your
products. For this purpose, it provides a dedicated engineering environment where Quality Characteristics can be
created, updated and deleted.
The Quality Characteristics that you can manage are the following:
• Attributive Characteristic: defines whether a produced material respects a specific characteristic or not.
Example: you are inspecting a car and checking whether the paint is used to paint the car (the paint is available)
or not.

Process Apps
• Variable Characteristic: contains information on measurements and allowed tolerances, indicating whether a
produced material respects a specific measurement (length, weight, thickness). Example: you are inspecting a
car and checking that the paint thickness is the required one, according to defined tolerances.
• Visual Characteristic: indicates whether visual defects (scuff marks, paint drops) have been detected in a
produced material. Example: you are inspecting a car and checking whether scuff marks are detected in the car
paint.
Audit Trail is displayed in the each page to provide evidence of all the operations that have been carried out on a
specific Quality Characteristic. Its records can be viewed by selecting the Quality Characteristic and clicking
on Audit Trail tab.
Workflow
1. Create one or more of the following Quality Characteristics:
• Attributive
• Variable
• Visual
2. Assign failures to Quality Characteristics.
3. Create Inspection Definitions.
Edit To edit Quality Characteristics.
To delete:
Delete
• Quality Characteristics.
• Failures assigned to Visual Characteristics.
Disassociate To remove the association between Quality Characteristics and Failures.
To export selected entities and instances in an export package that can

Export
be downloaded locally and imported afterwards. See How to Export and
Import Data
4.3.2.2.3.1 Creating Attributive Characteristics

Attributive Characteristics define if a produced material respects a specific characteristic or not. Example: you are
inspecting a car and checking if the right paint is used to paint the car or not.
Each Attributive Characteristic can be associated with Failures, defined in the Defect App.
Procedure
1. Do either of the following to open the Characteristics page:
• Click the Characteristics home tile.

• Click Quality Execution Engineering in the side menu bar and click Characteristics.
2. In the Characteristics page, click and then choose Add Attributive Characteristic from the command
menu

Process Apps

Id The identifier assigned to the Attributive Characteristic.

Once the Attributive Characteristic is created, the Id value cannot be modified.
The Id value cannot contain the following special characters: & (ampersand), ' (quote), #
(hashtag).
Revision The revision associated to the Attributive Characteristic.

Once the Attributive Characteristic is created, the Revision value cannot be modified.
Unique The identifier required to distinguish different instances of the same Attributive
Identifier Characteristic revision.
If the value is left blank, the system will automatically set the field with the Id and
Revision pair.
Once the Attributive Characteristic is created, the Unique Identifier value cannot be
modified.
Name (Optional) The name assigned to the Attributive Characteristic.
Description (Optional) Additional information on the Attributive Characteristic.
Criticality The importance of the Attributive Characteristic in context of the production or process.
Possible values are:
• Critical
• Main
• Minor
Context The context of an Attributive Characteristic. Possible values are:

• Process
• Product
Not OK Description defining that the Attributive Characteristic is not available during the product
Description inspection.
OK Description Description defining that the Attributive Characteristic is available during the product
inspection.
4. Click Save.
4.3.2.2.3.2 Creating Variable Characteristics

Variable Characteristics contain information on measurements and allowed tolerances and indicates if a produced
material respects the allowed tolerances. Example: you are inspecting a car and checking that the paint thickness is
the required one, according to defined tolerances.
Each Variable Characteristic can be associated with Failures, defined in the Defect App.

Process Apps
Procedure

2. In the Characteristics page, click and then choose Add Variable Characteristic from the command menu.
Id The identifier assigned to the Variable Characteristic.

Once the Variable Characteristic is created, the Id value cannot
be modified.
(ampersand), ' (quote), # (hashtag).
Revision The revision associated to the Variable Characteristic.

Once the Variable Characteristic is created, the Revision value
cannot be modified.
Unique Identifier The identifier required to distinguish different instances of the

same Variable Characteristic revision.
If the value is left blank, the system will automatically set the
field with the Id and Revision pair.
Once the Variable Characteristic is created, the Unique
Name (Optional) The name assigned to the Variable Characteristic.
Description (Optional) Additional information on the Variable Characteristic.
Criticality The importance of the Variable Characteristic in context of the

production or process. Possible values are:
• Critical
• Main
• Minor
Context The context of a Variable Characteristic. Possible values are:

• Process
• Product
UoM The Unit of Measure of the Variable Characteristic.
Nominal Value Contains Nominal Value for measurements and inspections.

Process Apps
Lower Tolerance Value (Optional) Contains the Lower Tolerance limit of measurements
and inspections.
Upper Tolerance Value (Optional) Contains the Upper Tolerance limit of measurements
and inspections.
4. Click Save.
4.3.2.2.3.3 Creating Visual Characteristics

Visual Characteristics indicate if visual defects have been detected in a produced material (for example, scuff marks
and paint drops). Example: you are inspecting a car and checking if scuff marks are detected in the car paint.
Each Visual Characteristic can be associated with Failures, defined in the Defect App.
When creating a Visual Characteristic, you can also insert an image and define a grid to pinpoint the area where a
failure is detected. At runtime, the visual image used to defect acquisition will be frozen, after the first defect is
detected. This avoids the misalignment if a new image is loaded in the engineering phase.
 You can define a Visual Characteristic without specifying any Image (and consequently no values for
neither Rows nor Columns). In this case, the runtime Sample offers to the user the capability to save the
number of each associated failure. Pay attention to an Image which is specified afterwards, when samples
of that specific Visual Characteristic have already been created. In this case, those samples will reflect any
Image at runtime which is specified in Visual Characteristic at engineering level.
Procedure

2. In the Characteristics page, click and then choose Add Visual Characteristic from the command menu.
Id The identifier assigned to the Visual Characteristic.

Once the Visual Characteristic is created, the Id value cannot be
modified.
(ampersand), ' (quote), # (hashtag).
Revision The revision associated to the Visual Characteristic.

Once the Visual Characteristic is created, the Revision value
cannot be modified.

Process Apps
Unique Identifier The identifier required to distinguish different instances of the

same Visual Characteristic revision.
If the value is left blank, the system will automatically set the field
with the Id and Revision pair.
Once the Visual Characteristic is created, the Unique
Name (Optional) The name assigned to the Visual Characteristic.
Description (Optional) Additional information on the Visual Characteristic.
Criticality The importance of the Visual Characteristic in context of the

production or process. Possible values are:
• Critical
• Main
• Minor
Context The context of a Visual Characteristic Specification. Possible

values are:
• Process
• Product
Image Image displaying the Visual Characteristic.
Rows Number of rows to be displayed in the image grid. The maximum

value is 20.
Columns Number of columns to be displayed in the image grid. The

maximum value is 20.
4. Click Save.
4.3.2.2.3.4 Assigning Failures to Quality Characteristics

After creating Quality Characteristics (Attributive Characteristic, Variable Characteristic or Visual Characteristic) and
after creating Failures in the Defect App, you can assign a list of possible Failures to a Quality Characteristic.
Procedure
1. Access the Characteristics page (see Creating Attributive Characteristics).
2. Select a Quality Characteristic and click .
3. Click the Potential Failures tab and click .
4. In the Potential Failure field, browse a Failure, previously created in the Defect App and click Select.
5. Click Save.

Process Apps
4.3.2.2.4 How to Create Inspection Definitions

Inspection Definitions define how Quality Characteristics must be acquired at runtime. One Quality Characteristic
can have one or more Inspection Definitions.
The Inspection Definition can be configured with different Frequency and will be executed at runtime accordingly.
The two frequency types are:
• 100 Percent, the Inspection will be executed on every produced item.
• Part Based, the Inspection will be executed at specified interval of produced items.
If the Electronic Signature Scenario is associated with the Inspection Definition, the relevant users must sign the
Inspection Definition to complete it.
Audit Trail is displayed in the Inspection Definition page to provide evidence of all the operations that have been
carried out on the Inspection Definition. The records can be viewed by selecting the particular Inspection Definition
and clicking the Audit Trail tab.
Workflow
1. Add a new Inspection Definition.
2. Create a New Revision of an Inspection Definition.
3. Set an Inspection Definition to Current.
Available Operations on Inspection Definitions

Edit To modify Inspection Definition attributes, apart from the Id, Revision and
Sample Size.
Copy Revision To create a copy of an existing Inspection Definition Revision with a new Id
and Revision.
Create new Revision To create a new revision of an Inspection Definition
Set Current To set or unset a specific Inspection Definition to current.
Unset Current
Lock To lock or unlock a specific Inspection Definition, for example to ensure

that the one in use is not modified.
Unlock
To delete an Inspection Definition.

Delete
 An additional option to navigate to the Scenario Configurations page is provided on the Inspection
Definitions page. Click Signature Scenario Configurations and navigate to the Scenario
Configurations page where you can create a new Scenario Configuration, edit or delete an existing
scenario.

Process Apps
4.3.2.2.4.1 Adding a New Inspection Definition

Inspection Definitions are used to configure Quality Characteristics to be carried out at runtime. They represent
how a certain measurement (that is, a Characteristic Representation) has to be collected at runtime in terms of
frequency and sample size.
Procedure
1. Do either of the following to open the Inspection Definitions page:
• Click the Inspection Definitions home tile.

• Click Quality Execution Engineering in the side menu bar and click Inspection Definitions.
2. In the Inspection Definitions page, click .
Id The identifier assigned to the Inspection Definition.

Once the Inspection Definition is created, the Id value cannot be
modified.
Name (Optional) The name assigned to the Inspection Definition.
Revision A mandatory field to identify the specific revision of the

Inspection Definition. Once defined, this value cannot be
modified.
Sample Size The number of measurements for each sample. The only
supported value is 1.
Can Be Skipped If set, the Quality Characteristics acquisition can be skipped.
Quality Characteristic Id The Quality Characteristic to be associated with the Inspection

Definition.
Frequency A mandatory field to identify the type of frequency of the

Inspection to be performed at runtime. It can be of two types:
• 100 Percent, the Inspection will be executed on every
produced item.
• Part Based, the Inspection will be executed at
specified interval, i.e. the inserted Frequency Value,
of produced items.
 Any Inspection Definition created in the Opcenter

Execution Foundation from any version lower than 4.2,
will adopt the value 100 Percent.

Process Apps
Frequency Value The interval at which the Inspection will be executed, when the
Frequency is selected as Part Based. In this case, the field is
mandatory and its lower limit is set to 0.001.
Signature Scenario The Electronic Signature Scenario to be associated with the

Inspection Definition to validate the detected failures and
digitally sign them at runtime. This option is available when the
Audit Trail app is installed in your Solution.
4. Click Save.
4.3.2.2.4.2 Creating a New Revision of an Inspection Definition

Revisions of Inspection Definitions can be created with differences in certain aspects from other forms of the same
Inspection Definition.
With revisions, entire Inspection Definitions are not required to be created from scratch when only few artifacts of
the original Inspection Definition need to be changed or upgraded.
Revisions can be created with not only new parameters but also by modifying or deleting those that have been
inherited.
Procedure
1. Do either of the following to open the Inspection Definitions page:

• Click Quality Execution Engineering in the side menu bar and click Inspection Definitions.
2. In the Inspection Definitions page, select the Inspection Definition for which you want to create a new revision.
3. Click .
4. Enter a new revision ID. Once defined, this value cannot be modified.
5. Click Save. The new Inspection Definition is displayed in the Inspection Definitions page. You can now add or
modify the Inspection Definition parameters.
4.3.2.2.4.3 Setting an Inspection Definition to Current

Any revision of an Inspection Definition can be set to current in order to define which revision should be used to
configure Quality Inspections at runtime.
Only one revision for each Inspection Definition (i.e. all the revisions with the same Inspection Definition Id) may be
set the current at any one time.
Procedure
1. Do either of the following to open the Instruction Definitions page:

• Click Quality Execution Engineering in the side menu bar and click Inspection Definitions
2. In the Inspections Definitions page, click on the tile of the Inspection Definition revision you want to set to
current.

Process Apps
3. Click .
4.3.2.2.5 Exporting and Importing Quality Execution Data

The Work Instruction App allows you to export and import its own master data entities. Unlike the Export operation,
the Import procedure depends on the exported entities and has to be performed carefully as described in the
following section.

The table below indicates the sequence to import the export package based on the entities: the first column lists
the entities to be imported and the rows indicate the order to import.
Example: If you want to import Characteristics and Inspection Definitions, and the Characteristics entities were
exported by setting Include Descendants to False, you must first import the Characteristics package and then the
Inspection Definitions one.
 • Characteristics are parent entities.

• Note that the entity name of Inspection Definitions is Characteristic Representation.
• Be aware that Failures are associated to Characteristics and they must be exported together with the
Characteristics. See Exporting and Importing Defect Data for information about the import sequence.
Failures Characteristics Inspection Notes

(Defect App) Definitions
Characteristics If Characteristics are

exported by
& Inspection
setting Include
Definitions
Descendants to True
(Characteristic
Representation)
Characteristics If Characteristics is
exported by
& Inspection
setting Include
Definitions
Descendants to False
(Characteristic
Representation)
Characteristics If you export any

Characteristic, the
related potential Failure
References are also
automatically exported.
4.3.2.2.6 How to Configure an Inspection Task

An Inspection Task is a Task based on the Inspection Task Definition. To create and configure an Inspection
Task, you need to access the Task App and create a Task, as follows:
1. In the Task Administration page, create a Task (Inspection Task) based on the Inspection Task Definition,
paying attention to specify the following:

Process Apps
Tab Data Description
Details Tab Equipment The Equipment to be associated with the

Task. For more information, see Equipment App.
Parameter Tab MTU The Material Tracking Unit required to move

Materials. For more information, see Material
App.
RTInspectionDefContainer Contains a list of information on the Inspection

Definitions previously created. You need to
create its value as described in Implementing an
Inspection Task Container.
Context Tab MaterialNId The Material to be associated with the Material

Tracking Unit.
MaterialRevision The Material revision.

Otherwise, if you want to use the Inspection Task Definition within a Business Process Flow, from the BPFlow
App, in the Process Definition Editor, configure a User Task, associating it with the Inspection Task Definition
and setting the above mentioned data in Manual Edit mode. The system creates automatically a Task.
2. Activate the inspection Task.
The system will populate your custom runtime environment with all required data, showing all Inspection
Definitions created in the Inspection Definitions page.
4.3.2.2.6.1 Implementing an Inspection Task Container

All information on the Inspection Definitions, previously created, are included in a container that needs to be
configured in the runtime Task (Inspection Task), based on the Inspection Task Definition.
To implement a Container for the Inspection Task, you need to create a Container ID via
the CreateRuntimeChrReprContainer command. The following is an example of API signature, where
CharacteristicRepresentationId is the ID of the Inspection Definition:
Name: 'somename', CharacteristicRepresentationsInfo:

[{CharacteristicRepresentationId: '8719dabf-cd34-4eeb-abdd-196d661a3bc0', Label:
'ParkingSensorCheck', RuntimeChrRepresentationNId: 'A Nid'},{.....}]
For more information on the CreateRuntimeChrReprContainer command, see the Commands section of
the CHR_OP Reference Guide.
4.3.2.3 How to Integrate and Use Quality Execution

At runtime, Quality Execution allows you to acquire samples during the life cycle of a product or process.
To integrate and use Quality Execution in a runtime environment, you can follow one of these approaches,
depending on your needs:
• Only read the values from the involved entities, implementing runtime queries via a Service Layer oData query
or an SDKLean ProjectionQuery. For information on the runtime data model, see Quality Execution Data Model
Entities.

Process Apps
• Also implement a user interface for Quality Execution in order to perform manual acquisitions. In this case, you
can:
• Integrate the provided UI component and widgets, as described in Implementing a User Interface for
Quality Execution. Your custom user interface will be populated with all required data by the system,
according to the configurations performed in the engineering phase. The operations that you can
perform if you implement the user interface following our guideline are described in What can I do in
Quality Execution Runtime Environment?.
• Implement custom UI Components and UI Modules, as described in Code-Based Development of UI
Components and UI Modules in the Opcenter Execution Foundation Development and Configuration Guide,
or custom Model-Driven UI Modules with the related UI Screens, as described in Model-Driven
Development of UI Modules and UI Screens in the Opcenter Execution Foundation Development and
4.3.2.3.1 Quality Execution Data Model Entities

At runtime, the Quality Execution data model is made up of the following entities, belonging to the CHR_OP
Functional Block:
• InspectionAcquisitionContext
• InspectionSample
• InspectionValue
• VisualDetectedFailure
• RuntimeCharacteristicRepresentationContainer
• RuntimeCharacteristicRepresentation
• PartBasedInspectionExecutionCriteria
• InspectionExecutionEngine
• PartBasedChrReprContainer
• CandidateSerial
For further information on CHR_OP Functional Block, refer to the Entities section of the CHR_OP Reference Guide.

Process Apps
InspectionAcquisitionContext entity
This entity contains information on the context of the inspection acquisition and it is defined by the following
properties:

Process Apps
MaterialNId NId of the involved Material, defined in the Inspection

Task.
MaterialRevision Revision of the involved Material, defined in the

Inspection Task.
EquipmentNId NId of the involved Equipment, defined in the Inspection

Task.
CharacteristciRepresentationNId NId of the Inspection Definition, created in the

engineering phase.
RuntimeCharacteristicRepresentationNId NId of the runtime Inspection Definition.
When acquiring the value, the system creates an InspectionSample entity for each Quality Characteristic.
InspectionSample entity
This entity contains information on the acquired sample of a runtime Inspection Definition and it is defined by the
following properties:
AnyViolation Indicates if any violation occurred during the sample acquisition, for
example a defect has been detected.
• 0: no violation occurred
• 1: a violation occurred.
Timestamp The timestamp of the last measured value.
User The user who performed the last inserted value update.
ScenarioInstanceId The identifier of the Electronic Signature Scenario instance.
IsSignaturePending Defines if the completed Inspection Definition requires to be reviewed

or not. If true, the Inspection Definition must be signed off.
Sketch The visual characteristic sketch at runtime.
MasterSketch The visual characteristic sketch from Visual Characteristic

Specification.
SketchRows The number of rows in which the sketch is divided for.
SketchColumns The number of columns in which the sketch is divided for.

Process Apps
SketchMimeType The sketch mime type.

When acquiring a sample of an Inspection Definition associated with Attributive Characteristics or Variable
Characteristics, the system creates an InspectionValue entity.
When acquiring a sample of an Inspection Definition associated with Visual Characteristics, the system creates a
VisualDetectedFailure entity.
InspectionValue entity
This entity contains information on the measured values of a runtime Inspection Definition and it is defined by the
MeasuredAttributeValue The measured value of an Attribute Characteristic.

• 0: the Attribute Characteristic is not available
• 1: the Attribute Characteristic is available
MeasuredVariableValue The measured value of a Variable Characteristic.

The value is the tolerance value set in the engineering phase.
MTUNId NId of the involved Material Tracking Unit.
CharacteristicType A navigation property to access the related entity.
FailureNId NId of the associated Failure.
FailureRevision Revision of the associated Failure.
VisualDetectedFailure entity
This entity contains information on the Failures detected in a runtime Inspection Definition and it is defined by the
Count The number of the detected Failures, set in case of Visual

Characteristics without images.

Process Apps
FailureNId NId of the associated Failure.
CharacteristicType A navigation property to access the related entity.
MTUNId NId of the involved Material Tracking Unit.
Coords The coordinates to pinpoint the area where Failures are

detected, set in case of Visual Characteristics with images.
RuntimeCharacteristicRepresentationContainer entity
This entity defines the container of the runtime Inspection Definitions and it is defined by the following property:
NId NId of the Runtime Inspection Definition container.
The characteristicRepr widget reads this entity and displays its content in the runtime page.
RuntimeCharacteristicRepresentation entity
This entity contains information on the runtime Inspection Definitions and it is defined by the following properties:
NId NId of the Runtime Inspection Definition.
ChrReprSampleSize The number of measurements to be acquired for each sample.
ChrReprNId NId of the engineering Inspection Definition.
ChrSpecNId NId of the Quality Characteristic, associated with the

ChrSpecRevision Revision of the Quality Characteristic, associated with the

CanBeSkipped Defines if the measurement can be skipped or not. If true, it

can be skipped.

Process Apps
RuntimeChrReprContainer A navigation property to access the related entity.
ChrSpecUId Unique identifier of the Quality Characteristic.
Label Label of the Runtime Inspection Definition, displayed in the

runtime page.
ChrReprRevision Revision of the Characteristic Representation.
ScenarioConfiguration The logical link of the Runtime Inspection Definition with an

Electronic Signature Scenario.
ChrReprFrequencyNId The NId of the Runtime Inspection Definition applicable for

Part Based only.
MandatoryExecutionsCompleted Indicates whether the mandatory Quality Executions are

completed.
ReferencedOperation The identifier of the Operation.

The characteristicRepr widget reads this entity and displays its content in the runtime page.
PartBasedInspectionExecutionCriteria entity
This entity contains information on the criteria for the Part Based Inspection Execution and it is defined by the
NId The NId of the Part Based Inspection Execution Criteria.
Name The Name of the Part Based Inspection Execution Criteria.
Description The Description of the Part Based Inspection Execution Criteria.

You can configure the Part Based Inspection Execution with two different Criteria's. The two Criteria's are:
• Default, the Inspection will be executed as soon as a part will be made available.
• Serial, the Inspection will be executed as soon as a specific serialized part will be made available.
InspectionExecutionEngine entity
This entity contains information on the Inspection Execution Counter and it is defined by the following properties:
MaterialNId The NId of the Material.

Process Apps
MaterialRevision The revision of the Material.
EquipmentNId The NId of the Equipment.
ReferencedOperation The identifier of the Operation.
CharacteristicRepresentationNId The NId of the Characteristic Representation.
CharacteristicRepresentationRevision The revision of the Characteristic Representation.
CharacteristicRepresentationFrequency The NId of the Characteristic Representation

Frequency.
CharacteristicRepresentationFrequencyValue The Value of the Characteristic Representation

Frequency.
CharacteristicRepresentationRuntimeNumber The Number of Characteristic Representation to be

executed.
ActualCounter The remaining number of quantity produced.
PartBasedChrReprContainer entity
This entity contains information on the Containers associated with the Inspection Execution Engine and it is defined
by the following property:
ContainerNId The NId of the Containers.
CandidateSerial entity
This entity contains information on the Candidate Serial associated with Containers of the Inspection Execution
Engine and it is defined by the following property:
Serial The NId of Serial.
4.3.2.3.2 What can I do in Quality Execution Runtime Environment?

If you will implement a user interface as described in Implementing a User Interface for Quality Execution, in the
runtime environment you can perform the following operations, depending on the quality characteristics you are
taking into account:

Process Apps
• In case of Inspection Definition associated with Attributive Characteristic, declare if the Quality Characteristic is
available or not. If not, you can associate the Inspection Definition with the detected Failures, previously
created in the Failure page.
• In case of Inspection Definition associated with Variable Characteristic, verify if the Quality Characteristic
respects the allowed tolerances. If tolerances have not been respected, you can associate the Inspection
Definition with the detected Failures, previously created in the Failure page.
• In case of Inspection Definition associated with Visual Characteristics, if defects have been detected, you need
to specify the number of defects. Then, you can associate the Inspection Definition with the involved Failures,
previously created in the Failure page. If an image have been assigned to the Visual Characteristic in the
engineering phase, you can pinpoint the area where Failures are detected and highlight the Failures with
colored dots. The color will be different, depending on the Failure you are taking into account. To avoid a
misalignment if a new image is loaded in the engineering phase, at runtime the visual image used to defect
acquisition is frozen, after the first defect is detected. In case of the Inspection Definition having frequency as
Part Based and no failures are detected, then you can click on to proceed with the Inspection.
For each Quality Characteristic type, you can see the Attachments associated with the involved Failures (if any).
Attachments help you to better identify the detected Failures.
If the Electronic Signature Scenario is associated with an Inspection Definition, the relevant users must sign off
using the Sign button as evidence that all the operations have been carried out. It logs the Electronic Signature
details along with the status and inserted comments in the Audit Trail Records.
Whenever you perform one operation, the system automatically acquires the related sample.
After a sample is acquired, you can read the values from the involved entities in the data model by implementing
runtime queries via a Service Layer oData query or an SDKLean ProjectionQuery. For information on the runtime
data model, see Quality Execution Data Model Entities.
In addition, you can manage the Inspection Task states.
Diagram
The following diagram shows an example of workflow.

Process Apps
4.3.2.3.3 Implementing a User Interface for Quality Execution

In order to implement a custom user interface where you can perform manual acquisitions at runtime, you need
to add a dedicated Mashup UI Module containing the required UI Component (Quality Execution) to your Solution.
The Quality Execution UI Component comes provided with the characteristicRepr widget, which is made available
by the Opcenter EX FN UI Framework.
In addition, the Opcenter EX FN UI Framework makes the sitTaskContainer widget available to visualize the created
Inspection Tasks containing all information on the Inspection Definitions.
By embedding both widgets, you will create a user interface like the one shown in Example of Runtime User
Interface.
Procedure
1. Integrate the sitTaskContainer widget in your code-based UI Module, as described in sitTaskContainer widget
overview.
2. From Solution Studio, add a Mashup UI Module for Quality Execution to your Solution to integrate the
characteristicRepr widget.
3. Reconfiguring your UI Application by associating the Mashup UI Module added in step 1, as described in
Configuring UI Applications in the Opcenter Execution Foundation Development and Configuration Guide.
4. Redeploy your Solution, as described in How to Deploy a Manufacturing Solution in the Opcenter Execution
sitTaskContainer widget overview

This widget provides you a list of Inspection Tasks which contain all information on the Inspection Definitions
created in the engineering phase (see How to Create Inspection Definitions) and associated with Quality
Characteristics.
Consider the user interface section highlighted in blue shown in Example of Runtime User Interface. The widget
displays a list of Inspection Task tiles and some UI common functionalities.
Each tile can be selected to visualize the contained Inspection Definitions.
The widget can be integrated in any code-based UI Module by means of the following HTML code snippet:
<sit-task-container sit-icv-data="viewDataArray"
sit-icv-options="viewOptionsObject">
</sit-task-container>
 For more information on the widget, see also the sitTaskContainer in the UI Framework Reference.
characteristicRepr widget overview

This widget provides you the list of Inspection Definitions created in the engineering phase and associated with
Quality Characteristics and allows you performing different operations, depending on the associated Quality
Characteristic.
Consider the user interface section highlighted in yellow shown in Example of Runtime User Interface. The widget
displays a list of Inspection Definition tiles and some UI common functionalities.
Each tile can be selected to perform the required operation, depending on the quality characteristics you are taking
into account:

Process Apps
• In case of Inspection Definition associated with Attributive Characteristic, you can declare if the Quality
Characteristic is available or not. For this purpose, the widget provides two radio buttons, one to be selected if
the Quality Characteristic is available and one to be selected if not. The labels of the radio buttons are the ones
defined in the engineering phase (see Creating Attributive Characteristics). If the Quality Characteristic is not
available, the widget provides a button in order to associate the Inspection Definition with Failures, defined in
the engineering phase (see Creating Failures). When clicking this button, the system displays a dialog box where
you can select the involved Failures.
• In case of Inspection Definition associated with Variable Characteristic, you can verify if the Quality
Characteristic respects the allowed tolerance, defined in the engineering phase (see Creating Variable
Characteristics). For this purpose, the widget provides a dedicated field where you insert the Quality
Characteristic quantity. If the tolerance is not respected, a button to associate the Inspection Definition with
Failures, defined in the engineering phase, is available. When clicking this button, the system displays a dialog
box where you can select the involved Failures.
• In case of Inspection Definition associated with Visual Characteristic without any image assigned, if defects have
been detected, you can specify the number of defects. For this purpose, the widget provides a dedicated field
where you insert the defect number and a button to associate the Inspection Definition with Failures, defined in
the engineering phase. When clicking this button, the system displays a dialog box where you can select the
involved Failures.
• In case of Inspection Definition associated with Visual Characteristic with an image assigned, if defects have
been detected, you can both assign Failures and pinpoint the area where Failures are detected, highlighting the
Failures with colored dots. For this purpose, the widget:
• Provides a button to associate the Inspection Definition with Failures. When clicking this button, the
system displays a dialog box where you can select the involved Failures.
• Provides a dedicated field where you can browse the associated Failures.
• Displays the image assigned to the Visual Characteristic where you can highlight the Failures with
colored dots. To insert a colored dot, you need to click on the image. The color will be different,
depending on the Failure you have browsed.
 • Displays the warning icon once the Quality Execution is completed in case of Inspection Definition
having frequency as Part Based. In this case you need not to carry out any further inspection.
• Displays the button to proceed with the inspection in case of the Inspection Definition having
frequency as Part Based and no failures are detected.
For each Quality Characteristic type, the widget also provides both the details of the Inspection Definition you are
taking into account and a button to see the Attachment associated with the involved Failures (if any). Attachments
help you to better identify the detected Failures.
The widget also provides the Sign button where the User Credentials along with the comment (optional) are
provided to approve that all the operations have been carried out (see Electronic Signature).
The widget is embedded by adding the dedicated Mashup UI Module containing the Quality Execution UI
Component to your Solution. The following is the related HTML code snippet:
<characteristic-repr cr-id="myid" container-id="000-0000-00000" context=""

mtu="mymtu"hide-single-element-list=" "></characteristic-repr>
 For more information on the widget, see also the characteristicRepr in the UI Framework Reference.
Example of Runtime User Interface

Process Apps
Inspection Definition associated with Attributive Characteristic
 Legend
• Blue: user interface section provided by the sitTaskContainer widget
• Yellow: user interface section provided by the characteristicRepr widget
Inspection Definition associated with Variable Characteristic
Inspection Definition associated with Visual Characteristic without Image

Process Apps
Inspection Definition associated with Visual Characteristic with Image
4.3.2.3.3.1 Adding a Mashup UI Module for Quality Execution to your

Solution
In order to implement a custom user interface where you can perform manual acquisitions at runtime, you need
to add a dedicated Mashup UI Module containing the required UI Component (Quality Execution) to your
Solution. The Quality Execution UI Component comes provided with the characteristicRepr widget.
For more information on Mashup UI Module, see Creating a Mashup UI Module in the Opcenter Execution

Process Apps
Procedure
1. Create a Mashup UI Module. For more information on this step, see Creating a Mashup UI Module in the
2. Click within the tile of the newly created Mashup UI Module.
3. In the UI Screen page, select the screen you want to configure and click the arrow icon .
4. Click on the UI Components tab in the toolbox on the right-hand side and click on
the Siemens.SimaticIT.WITask.
5. Drag and drop the Quality Execution onto the editor.
6. Click to save the Mashup UI Module.
7. Navigate to the Mashups page and select the Mashup UI Module which you configured in the above steps. For
more information on this step, see Designing Mashup UI Modules in the Opcenter Execution
8. Click to generate the Mashup UI Module.
4.3.2.3.4 Executing Inspection Definition with Frequency as Part Based

To execute the Inspection Definition with frequency as Part Based the following APIs are exposed:
• UpdatePartBasedInspectionExecutionCounter
• CreateCandidateSerial
• DeleteCandidateSerial
UpdatePartBasedInspectionExecutionCounter API
The UpdatePartBasedInspectionExecutionCounter API is exposed by Quality Execution to declare a Produced
Quantity. This API updates the InspectionExecutionEngine entity and calculates the
CharacteristicRepresentationRuntimeNumber and ActualCounter properties based on the declared Produced
Quantity. After calculation if the Quality Execution is needed, then the QualityInspectionExecutionNeeded event
is triggered. This API is defined by the following parameter:
ParameterName Type Description
MaterialNId string The NId of the Material.
MaterialRevision string The revision of the Material.
ReferencedOperation string The identifier of the Operation.
RuntimeCharacteristicReprese List< The information of Runtime Characteristic

ntationInfo RuntimeCharacteristicRepres Representation, Part Based Inspection
entationInfo> Execution Criteria and Equipment.
ProducedQuantity decimal The Quantity of Produced items.
RuntimeChrReprContainerNId string The NId of the Runtime Characteristic

Representation Container.
where, RuntimeCharacteristicRepresentationInfo is a parameter type with the properties:

Process Apps
Property Type Description
PartBasedExecutionCriteriaNId string The NId of the Part Based Execution Criteria.
CharacteristicRepresentationNId string The NId of the Characteristic Representation.
CharacteristicRepresentationRevision string The revision of the Characteristic

Representation.
EquipmentNId string The NId of the Equipment.

QualityInspectionExecutionNeeded with the properties:
CharacteristicRepresentationNId string The NId of the Characteristic Representation.
CharacteristicRepresentationRevision string The revision of the Characteristic

Representation.
With envelope:
Property Value
Category QualityInspectionExecutionNeeded
Module WorkInstruction
Tag QualityInspectionExecution
Topic WorkInstructionQE
UserField1 <Frequency>
CreateCandidateSerial API
This API creates the Candidate Serial on which the Inspection will be executed. The API is defined by the following
parameter:
CandidateSerialInfo List<CandidateSerialInfo> The list of Containers and their related

Serials.

Process Apps
CharacteristicRepresentationNId string The NId of the Characteristic

Representation.
CharacteristicRepresentationRevisio string The revision of the Characteristic

n Representation.

where, CandidateSerialInfo is a parameter type with the properties:
ContainerNId string The NId of the Container.
Serial List<string> The list of Serial NId.
DeleteCandidateSerial API
This API deletes the Candidate Serial on which the Inspection will be executed. The API is defined by the following
parameter:
CandidateSerialInfo List<CandidateSerialInfo> The list of Containers and their related

Serials.
CharacteristicRepresentationNId string The NId of the Characteristic

Representation.
CharacteristicRepresentationRevisio string The revision of the Characteristic

n Representation.

where, CandidateSerialInfo is a parameter type with the properties:
ContainerNId string The NId of the Container.

Process Apps
Serial List<string> The list of Serial NId.

How To Export and Import Data
Exporting Data from the Runtime Database
5 How To Export and Import Data

Opcenter Execution Foundation provides the Export Import capability in order to exchange data, previously
configured and set, from one system to another with a compatible data model structure.
These operations can either be performed via user interface as documented in the following sections, or
programmatically implemented in custom UI Screens as follows:
• for Model-Driven UI Modules, at Configuring the Model-Driven UI Screen Contentsin the Opcenter Execution
Foundation Development and Configuration Guide
• for Standard UI Modules, at ICVOptions in the Opcenter Execution Foundation UI Framework Reference Guide
Worflow
1. Export data from the runtime database.
2. (Optional) Modify the exported data.
3. Import data to the runtime database.
5.1 Exporting Data from the Runtime Database

The Export Import functionality allows you to export selected entities and instances of any Opcenter EX FN App in
an export package that can be downloaded locally and imported afterwards.
The export packages are managed in the Export Import Administration page and will be removed automatically in
case of inactivity.
How the Export operation will be performed depends of the involved App: each App exports the entity data, as well
as its properties in composition, and, if desired, any child relationships it may have. If data segregation has been
set, this also impacts whether the Export operation can be performed.
 Bear in mind that to correctly perform the download of logs and export packages of any App, you must
configure the Site Settings of Chrome in order to support multiple downloads.
For more information about the Apps that support the Export Import functionality and the import sequence of the
related entity data, see the links below:
App Import Sequence of Entity Data
Barcode App Exporting and Importing Barcode Rule Data
Defect App Exporting and Importing Defect Data
Label App Exporting and Importing Label Type and Printer Data
Equipment App Exporting and Importing Equipment Data
Material App Exporting and Importing Material Data
Personnel App Exporting and Importing Personnel Data
Exporting and Importing UoM Data

Reference App
Exporting and Importing Entity Life Cycle and State Machine Data

Exporting Data from the Runtime Database
App Import Sequence of Entity Data
Exporting and Importing Autonumbering Configuration Data
Business Process Flow App Exporting and Importing Process Definition Data
Task App Exporting and Importing Task Data
Work Instruction App Exporting and Importing Work Instruction Data
Golden rules
• The export package always contains the records of the base entity, including its facets and the entities in
composition. If you select the Include Descendants export option, the child entities (i.e. the entities defined as
Source in Project Studio) will be also exported.
• In case of promotion of scalar fields to navigation properties at App level, if the Export operation is performed
starting from the customized App, the Include Descendants export option will take into account these relations
when they are defined across the same domain. If these relations are defined across different domains, these
references will be just resolved in the target database during the Import operation (see Modifying the Exported
Data).
• For the overview of the export files see Modifying the Exported Data
Prerequisites
• If the runtime database is on SQL Server, the Export functionality requires the BCP Utility on each Foundation
host; see Prerequisites for Opcenter Execution Foundation Hosts in the Opcenter Execution
Foundation Installation Guide for details.
• The ExportImportAdmin UI Module must be associated to the UI Application whose data you want to export (see
Selecting UI Modules in the Opcenter Execution Foundation Development and Configuration Guide).
Procedure
1. In the desired App page, select the item to export and then click Export : the Export side panel opens.
If the Data Segregation is enabled, a warning message indicates that only the entities on which you have
visibility, based on your assigned data segregation tags, will be exported.
2. (Optional) select the Include Descendants check box to export the children relationships of the selected entity
and click Export.
3. Do either of the following to open the Export Import Administration page:
• click the Export Import Administration home tile.
• click Export Import Administration in the side menu bar and click Export Import Administration
4. Select the exported package, click Download and select Download Package: the zip file is downloaded
containing .DAT and .FMT files for each entity and a manifest file. For more information on the package content,
see Modifying the Exported Data.
Available operations on export packages

Modifying the Exported Data
On the existing export packages you can perform the following operations in the Export Import Administration
page, by selecting the operation type from the grid and clicking the proper icon.
The page displays the list of operations performed (Export or Import) and the related additional details such as
Operation Status, Application Name or Solution Name.
Refresh To update the list of import/export operations.
To import the selected export package.

Import package
Details To display the operation details such as Source, Operation type, App name and
Solution name. The Operation Status description informs that this operation
cannot be executed.
Download Log To download the log corresponding to the export package in status Error or
Completed.
Download Package To download the export package in status Completed in a zip file.
To set the operation to Error and freeze it, and create a new operation with the
Recovery operation
same data of the selected one.
To set the operation to Error in order to be automatically removed.

Abort operation
5.2 Modifying the Exported Data

After you have exported a data package, you can apply changes to the data values.
Data is contained in the <EntityName>.dat file. The corresponding <EntityName>.fmt file must be modified only in
case of schema misalignment, otherwise it must not be changed.
The mapping between entity types and the related <EntityName>.dat files is expressed in the Index.csv file.
After a package has been manually modified, the application does not perform any checks on data consistency. It is
your responsibility to maintain data consistency, ensuring that data types, data values and logical references are
properly maintained.
Golden Rules
Operation Golden Rule
Add records For a new record you must

• set the Added/Modified field to 1
• set the Id and the AId fields to the same GUID value, which
must be unique inside the export package

Modify records For a modified record you must

• set the Added/Modified field to 1
• not modify Id and AId fields
If you modify a field belonging to the entity logical key (e.g. the
NId property), the modified record will be added as a new record.
Add/Modify Entity References • All physical references (foreign keys) to other entities must
be expressed as AId values (and not as Id values). AId values
will be recalculated to Id values during the import operation.
The referenced entities (parent entities), along with their
logical keys (AId value), must be present on the database
before you import an entity (source entity).
• If entities have logical references to other entities (simple
string references to entity logical keys), there are no
constraints on the import sequence of the related entities,
but you must be aware that before using applications at
runtime, the imported data must be consistent with the
source data model.
Manage Value type of reference type All references to other entities must be expressed as AId values
(and not as Id values). AId values will be recalculated to Id values
during the import operation.
Manage Scalar fields promoted to In case of promotion of scalar fields to navigation properties at
navigation properties App level, if the Export operation was performed starting from
the customized App and the relations are defined across
different domains, all references to other entities must be
expressed as AId values (and not as Id values). AId values will be
recalculated to Id values during the import operation.
Remove records If you attempt to remove a record from a base entity .dat file, no
changes will be applied to the target database.
Add/Remove Facets • If you remove a record from a facet .dat file, the facet record
will be removed.
• If you import a base entity with facets, the imported facets
will overwrite the entity facets in the target database.

Manage System fields The values of the boolean

properties IsDeleted and ToBeCleaned cannot be modified in
the export package as they are always reset in the target
database. Consequently, once imported in the target database,
they must be reconfigured.
The values of the boolean properties IsCurrent,
IsFrozen and IsLocked can be modified in the export package. In
the Export Import Administration page, when importing data
you can decide to copy the values of the system fields, included
in the export package, to the target database. For more
information, see Importing Data to the Runtime Database.
Manage project-specific fields (e.g. The IsDefault property value of the source database is preserved
IsDefault) in the target database. Any configuration conflict must be
manually handled in the target environment. For example, if
there are two entities that are set as default, you must manually
modify one of the two.
Manage Segregation Tags The Segregation Tags that are associated to each entity are
contained in a separate file.
Manage Attachments You cannot add or modify attachments. You can only modify the
associations between entities and existing attachments.
Procedure
1. Extract files from the exported zip and open the .dat file corresponding to the entity model whose records you
want to modify (see description below).
2. Apply the required changes by adapting the examples below regarding the following use cases:
• Adding a new record
• Adding a new record with relations to other entities
• Modifying a record
3. Save the file.
4. Zip all extracted files to a new zip file, containing exactly the same folder structure as the exported one. The file
is ready to be imported.
Export package description

Each exported zip contains the following files:
File/Folder Description
Index.csv The file describing the mapping of the following elements:

• database table name (EntityTable column header)
• .dat file (DataFile column header)
• base entity full name (EntityType column header).
Manifest.json File for internal use containing information about the exported package.

File/Folder Description
<EntityName The data file that you must modify.

>.dat
The zip contains one file for each base entity. The total number of .dat files depends on the
export options (e.g. including descendants or not) and on how entities have been modeled.
The file name of the .dat file represents the short name of the exported base entity. The
short name is the name that you assign to a base entity during the modeling phase in
Project Studio.
If you have more entities with the same name in different Functional Blocks (in the same
domain) the zip file will contain more .dat files, one for each entity. Each file will be
distinguished by a progressive number (e.g. <EntityName>_1.dat, <EntityName>_2.dat,
<EntityName>_n.dat).
In case of an extended entity, there is only one .dat file containing the data of both the base
entity and the extended entity.
 The Segregation Tags of an entity are contained in a separate file.

Attachments are listed in the File.dat file and the related contents (payloads) are
contained in separate blob files. The relationship between entity and file is
specified as a physical reference (foreign key) to the Id/AId of the record in the
File.dat file (as documented for the one-to-many example below).
Format Folder containing internal files. These files are format files which must be modified only if
you need to align the exported schema to the current data model.
 For instance, to correctly import entities that refer to any obsolete/removed

properties, you have to remove the line which refers to the deleted property from
the <ROW> section of the .fmt file.
For more details on the obsolete properties, see Obsolete Functionalities in the
Opcenter Execution Foundation Release Notes.
 .dat and .csv files can be opened in Excel.
Example for a new record

The example refers to the EquipmentType entity.
To add a new record, add a line to the EquipmentType.dat file and take note of the following relevant fields within
the example:
• AddeOrModified = 1
• Id = AId = unique Guid
• NId = free field

EquipmentType.dat
__AddedOrModified Id AId IsFrozen IsLocked IsDeleted EntityType Discriminator

CreatedOn LastUpdatedOn ConcurrencyVersion ToBeCleaned NId Name Description IsDefault
LevelNId
1 bb0345c1-26f5-4f46-9d90-fa0536349a49 bb0345c1-26f5-4f46-9d90-fa0536349a49 0 0 0
Siemens.SimaticIT.MasterData.EQU_MS.MSModel.DataModel.EquipmentType
EquipmentType_Siemens_SimaticIT_MasterData_EQU_MS_MSModel 2020-02-13 10:14:44.2265273
+00:00 2020-02-13 10:17:49.1842456 +00:00 0 0 EquipmentNId3 EquipmentName3
EquipmentDescription3 0 Enterprise
Example for a new record with 1-n (one-to-many, in composition) relationship

with another entity
The example refers to a one-to-many relationship in composition between the EntityTypeProperty (source) entity
and the EquipmentType (target) entity.
The export package contains 2 data files which are relevant for this use case:
• the EquipmentTypeProperty.dat file, containing the records that have a reference (foreign key) to the
EquipmentType entity, and
• the EquipmentType.dat file, containing the EquipmentType records with the AId values that you will use in the
relationship.
To add a new EquipmentTypeProperty record, add a line to the EquipmentTypeProperty.dat file and take note
of the following relevant fields within the example:
• AddedOrModified = 1
• NId, Property Value = free fields
• EquipmentType_Id = EquipmentType AId value (read from the EquipmentType.dat package, e.g. 83453795-
b23e-40ea-acb1-eb31fe3fa783 in the example below)

EquipmentTypeProperty.dat
__AddedOrModified Id AId IsFrozen IsLocked IsDeleted EntityType

Discriminator CreatedOn LastUpdatedOn ConcurrencyVersion ToBeCleaned NId
PropertyValue Operational PropertyType EquipmentType_Id
0 1DD59F0B-4A4E-EA11-8458-005056013851 A8DD9B0D-EE1D-BED4-4FBE-9F9D5F2D6A12 0
0 0 Siemens.SimaticIT.MasterData.EQU_MS.MSModel.DataModel.EquipmentTypeProperty
EquipmentTypeProperty_Siemens_SimaticIT_MasterData_EQU_MS_MSModel 2020-02-13
10:17:32.9532113 +00:00 2020-02-13 10:17:32.9532113 +00:00 0 0
Equipment1Property1 1 1 5 C1468276-BD4D-2EF6-3444-8E7B8F9C3582
1 30df6eba-7369-44e6-9d92-7627edf01804 30df6eba-7369-44e6-9d92-7627edf01804 0
0 0 Siemens.SimaticIT.MasterData.EQU_MS.MSModel.DataModel.EquipmentTypeProperty
EquipmentTypeProperty_Siemens_SimaticIT_MasterData_EQU_MS_MSModel 2020-02-13
10:17:49.1842456 +00:00 2020-02-13 10:17:49.1842456 +00:00 0 0
Equipment1Property3 true 0 7 83453795-b23e-40ea-acb1-eb31fe3fa783
EquipmentType.dat

Discriminator CreatedOn LastUpdatedOn ConcurrencyVersion ToBeCleaned NId Name
Description IsDefault LevelNId
0e 83453795-b23e-40ea-acb1-eb31fe3fa783 83453795-b23e-40ea-acb1-eb31fe3fa783 0
0 0 Siemens.SimaticIT.MasterData.EQU_MS.MSModel.DataModel.EquipmentType
EquipmentType_Siemens_SimaticIT_MasterData_EQU_MS_MSModel 2020-02-14 11:42:
03.9266667 +00:00 2020-02-14 11:42:03.9266667 +00:00 0 0 Equipment3 Equipment3
Equipment3 0 Enterprise
Example for a new record with n-m (many-to-many) relationship with another
entity
The example refers to a many-to-many relationship between the EquipmentGroupConfiguration source (child)
entity and the EquipmentConfiguration target (parent) entity.

The export package of the EquipmentConfiguration entity (with descendants) contains 3 data files which are
relevant for this use case:
• EquipmentGroupConfiguration.dat file containing the EquipmentGroupConfiguration entity records with
the AId values that you will use in the relation
• EquipmentConfiguration.dat file containing the EquipmentConfiguration entity records with the AId values
that you will use in the relationship
• EquipmentGroupConfiguration-To-EquipmentConfiguration.dat file containing the references (foreign keys)
both to the EquipmentConfiguration and to the EquipmentGroupConfiguration entity
In this use case, the relationship is not stored in the source entity file (as for the one-to-many relationship) but it is
stored in the EquipmentGroupConfiguration-To-EquipmentConfiguration.dat separate file.
To add a new EquipmentConfiguration record with its relationship you must modify the following two files instead
of one:
• In the EquipmentConfiguration.dat file add a line and take note of the following relevant fields within the
example
• AddeOrModified = 1
• NId = free field
• In the EquipmentGroupConfiguration-To-EquipmentConfiguration.dat file, add a record with
• AddedOrModified = 1

• EquipmentGroupConf_[xxx] = EquipmentConfiguration AId value

• EquipmentConfiguration_Id = EquipmentGroupConfiguration AId value
EquipmentConfiguration.dat

Description LocationNId EquipmentTypeNId LevelNId
1 fbb16cb8-b384-4369-8639-d5caffd746a6 fbb16cb8-b384-4369-8639-d5caffd746a6 0
0 0 Siemens.SimaticIT.MasterData.EQU_MS.MSModel.DataModel.EquipmentConfiguration
EquipmentConfiguration_Siemens_SimaticIT_MasterData_EQU_MS_MSModel 2020-02-14
11:34:24.5133333 +00:00 2020-02-14 11:34:24.5133333 +00:00 0 0
EquipmentConfiguration3 EquipmentConfiguration3 EquipmentConfiguration3
Equipment1 Enterprise
EquipmentGroupConfiguration

Description Category
0 D202F62A-174F-EA11-8458-005056013851 89E2FF49-E4C8-2F85-656E-46A64EA2FBBC 0
0 0
Siemens.SimaticIT.MasterData.EQU_MS.MSModel.DataModel.EquipmentGroupConfiguration
EquipmentGroupConfiguration_Siemens_SimaticIT_MasterData_EQU_MS_MSModel 2020-02-14
10:45:52.1879207 +00:00 2020-02-14 11:34:24.5133333 +00:00 0 0
EquipmentGroupConfiguration1 EquipmentGroupConfiguration1
EquipmentGroupConfiguration EquipmentGroupConfiguration
1 044b7712-cc0b-42e1-9509-5753d89427ed 044b7712-cc0b-42e1-9509-5753d89427ed 0
0 0
10:45:52.1879207 +00:00 2020-02-14 11:34:24.5133333 +00:00 0 0
EquipmentGroupConfiguration-To-EquipmentConfiguration.dat
__AddedOrModified EquipmentGroupConf_1118171532 EquipmentConfiguration_Id

0 89E2FF49-E4C8-2F85-656E-46A64EA2FBBC 5B12AFB9-98ED-B500-0874-3037415B8016
0 89E2FF49-E4C8-2F85-656E-46A64EA2FBBC 50954A76-0E73-69CA-C431-391A27C76FA2
1 044b7712-cc0b-42e1-9509-5753d89427ed fbb16cb8-b384-4369-8639-d5caffd746a6
Example of modifying a record

Importing Data to the Runtime Database
EquipmentGroupConfiguration.dat original export file
_AddedOrModified Id AId IsFrozen IsLocked IsDeleted EntityType

Description Category
0 5ED42544-3085-44FE-B4F5-F9AB26A27943 2FB4E228-BA3B-7441-A81E-121C5213D6ED 0
0 0
13:28:37.8500000 +00:00 2020-02-14 13:28:37.8500000 +00:00 0 0
EquipmentGroupConfiguration.dat modified file
__AddedOrModified Id AId IsFrozen IsLocked IsDeleted EntityType Discriminator

CreatedOn LastUpdatedOn ConcurrencyVersion ToBeCleaned NId Name Description Category
1 5ED42544-3085-44FE-B4F5-F9AB26A27943 2FB4E228-BA3B-7441-A81E-121C5213D6ED 0
0 0
13:28:37.8500000 +00:00 2020-02-14 13:28:37.8500000 +00:00 0 0
EquipmentGroupConfiguration New Description EquipmentGroupConfiguration
Example of new/modified Facet

If you want to add/modify a Facet, you should follow the same indications that are provided for the one-to-many
relationship.
5.3 Importing Data to the Runtime Database

The Export Import functionality allows you to import entities and instances previously exported in order to manage
the configuration data.
Regarding Foundation Apps and entities, the way you import data depends on how you have previously exported
the related entities (i.e. with/without the Include descendants option). Consequently, the import sequence must be
carefully followed.
Golden rules

• In case of physical references (references via database foreign key), parent entities (i.e. the entities that have
been defined in Project Studio as the End side of the navigation) must be present on the database before you
import the required entity.
• The Import operation does not perform any checks on the custom logic and it is your responsibility to preserve
application data integrity. For example, in case of logical references towards other entities (for example, textual
references to logical keys which are managed at application level), there are no constraints on the import
sequence but in order to properly use applications at runtime you must be sure that the imported data is
consistent with the source data model.
• If you need to import packages that were exported in 3.x version and that contain entities which refer to
obsolete/removed entities, you must first apply manual changes to the package format files (fmt files) in order
to align the data model schema, before you can correctly perform the import operation.
Prerequisites
• Source database and target database must be aligned for both schema and collation.
• If the runtime database is on SQL Server, the Import functionality requires the BCP Utility on each Foundation
host; see Prerequisites for Opcenter Execution Foundation Hosts in the Opcenter Execution
Foundation Installation Guide for details.
• The user belongs to the SysAdmin role.
• You have associated the ExportImportAdmin UI Module to the UI Application containing the Apps whose data
you want to import. See Selecting UI Modules in the Opcenter Execution Foundation Development and
Configuration Guide
• You have previously exported the required data.
Procedure
1. Do either of the following to open the Export Import Administration page:
• click the Export Import Administration home tile.
• click Export Import Administration in the side menu bar and click Export Import Administration
2. From the Export Import Administration page, click Import package in the side menu bar: the
Import Package side panel opens.
3. In the Package box, click Browse , select the export package to be imported.
4. Set the following parameters or leave the check-boxes disabled (default), depending on your needs:
Keep Package Value for Locked Flag If selected, the value of the system field IsLocked,
included in the export package, will be copied to the
target database.
If left disabled (default):
• If you are importing new data, the system will
reset the value of the system field IsLocked in
the target database.
• If you are importing data already existing in the
target database, the system will maintain the
current value of the system field IsLocked in

Keep Package Value for Frozen Flag If selected, the value of the system field IsFrozen,
target database.
reset the value of the system field IsFrozen in
current value of the system field IsFrozen in
Keep Package Value for Current Flag If selected, the value of the system field IsCurrent,
target database.
reset the value of the system field IsCurrent in
current value of the system field IsCurrent in
5. Click Import.
6. If you want to remove a previously selected package, click .
7. (Optional) In order to maintain query performances, rebuild the indexes manually as described in Index
Management in Opcenter Execution Foundation of Opcenter Execution Foundation Development and
The Export Import Administration page displays a new row containing information about the just performed
import operation.
Available operations on imported packages

On the imported packages you can perform the following operations by selecting the operation in the Export
Import Administration page and then clicking the required icon:
Icon Description
To update the list of import/export operations.

Refresh
To display the operation details such as Source, Operation type, App name and Solution name.
Details

Deleting Export Import Operation Data from the System Database
Icon Description
To download the log corresponding to the import operation in status Error or Completed. The
download folder depends on the browser settings.
Download
Log The log file provides you with several information such as the entity domain, the target database
tables, the number of imported rows and so on.
If you have imported referenced entities and there are any missing referenced logical keys in the
database, an Invalid Object Navigation error is returned. To properly import referenced entities,
you should follow the import procedures documented for each Foundation Apps.
To set the operation to Error in order to be automatically removed.

Abort
operation
To set the operation to Error and freeze it, and create a new operation with the same data of the
selected one.
Recovery
operation
 • If the target environment has been configured with an auto numbering pattern that includes counters,
and the target entities are subject to auto numbering rules, bear in mind that the following manual
steps could be required:
a. Remove any counters from the auto numbering configuration.
b. Create a new counter starting from the number of the last used imported entity's seed.
• If you have imported entities associated with segregation tags, their segregation tags will be visible
after you log out and log in.
5.4 Deleting Export Import Operation Data from the System

Database
Data related to the Export Import operations remain on the system database as long as you manually remove
them.
Procedure
To clean data related to the export or import operations from the <prefix>_UA_sys database, you must manually
execute the following SQL Server/Oracle Stored Procedures directly on the <prefix>_UA_sys database:

Table Name Stored Procedure Input Description

Parameters
(SQL Server) FSP_DELEXPORTIMPORTOPERATION @hour To remove

ExportImport (integer) operations that
Operation have:
• the
LastUpdateOn
timestamp
which is older
than the
specified value
• the Status prop
erty set either to
Completed or
Error
(Oracle) FSP_DELEXPORTIMPORTOPERATION V_HOUR To remove

ExportImport (integer) operations that
Operation have:
• the
LastUpdateOn
timestamp
which is older
than the
specified value
• the Status prop
erty set either to
Completed or
Error
A job which executes the Stored Procedure can be alternatively scheduled.

How To Manage Time To Live for Client Cache
6 How To Manage Time To Live for Client Cache

Resources of an UI Application, files with an extension such as .svg, .js, .json, .css and .png are configured to be
cached in the client machines for reducing the load time. By default these cached files are configured to be replaced
with new files after a span of 30 days. This page will guide you, to modify the maximum time till which the cache can
live in the client machine.
Procedure
To change the maximum age for the cache to live for an UI application follow the steps as listed below:
1. Open the web.config file from Internet Information Services (IIS).
a. Expand the Default Web Site > sit-ui > runtime node.
b. Right-click<UI Application Name> and select the Manage Folder > Explore to open the UI Application
main page.
c. Edit the web.config file in a text editor.
2. Provide a value to the attribute cacheControlMaxAge available in the xml tag clientCache, the value must be in
the format [-][d.]hh:mm:ss. The validity stated here applies to all the cached file types (currently configured
for: .js, .json, .css, .svg, and .png) for the particular UI application whose web.config will be modified.
For Example,
• If you want to set 1 hour as the time to live for cache in the client machine, then you should provide the
value as 01:00:00
• For 90 days you should provide the value as 90.00:00:00
• For 6 hours you should provide the value as 06:00:00
• For 1 minute you should provide the value as 00:01:00

How To Manage Time To Live for Client Cache
• For 60 seconds you should provide the value as 00:00:60
3. If you want the changes on cacheControlMaxAge to be set immediately. Open Developer Tools in a web
browser and Empty Cache and Hard Reload the UI Application. Otherwise, the new validity will be in effect
once the previous validity has expired.
Nevertheless, the value for cacheControlMaxAge will be reset to the default value once a new version for the
solution is deployed.
 Provided the web.config file for an UI application was modified with a change in the
cacheControlMaxAge and the UI content was not accessed from any browser, if there was a solution
deployment meanwhile you access the UI, then the latest files from the server will be loaded with the
value reset for the cacheControlMaxAge.

OpcenterEXFN UserManual

Uploaded by

Copyright:

Available Formats

OpcenterEXFN UserManual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OpcenterEXFN UserManual

Uploaded by

Copyright:

Available Formats

Opcenter Execution Foundation 4.

Siemens AG PL20210506303162726 Copyright © Siemens AG 2021

Opcenter Execution Foundation 4.2 - User Manual iii

iv Opcenter Execution Foundation 4.2 - User Manual

Opcenter Execution Foundation 4.2 - User Manual v

vi Opcenter Execution Foundation 4.2 - User Manual

4 Process Apps ...................................................................................................304

Opcenter Execution Foundation 4.2 - User Manual vii

5 How To Export and Import Data.....................................................................465

viii Opcenter Execution Foundation 4.2 - User Manual

Opcenter Execution Foundation 4.2 - User Manual ix

Title User Manual

Product Title Opcenter Execution Foundation

Version Title 4.2

Product Version OpcenterEXFN_4.2.0.0

Summary Provides detailed information on how to use the Opcenter Execution

Audience Operator, Supervisor, Support Engineer

10 Opcenter Execution Foundation 4.2 - User Manual

1 Opcenter Execution Foundation App Overview

What are Opcenter EX FN Apps

App Name Topic Referenced Functional Blocks

Application Log Application Logs related to • Siemens.SimaticIT.ALG_MS

Audit Trail Audit Trail and Electronic • Siemens.SimaticIT.ES_SD

Opcenter Execution Foundation 4.2 - User Manual 11

App Name Topic Referenced Functional Blocks

Automation Automation Gateway • Siemens.SimaticIT.ATN_MS

Barcode Barcode Rules Management • Siemens.OpcenterEX.FN.BRC_MS

BPFlow • Business Process Flows • Siemens.SimaticIT.BPF_MS

Data Segregation Data Segregation • Siemens.SimaticIT.DSG_SD

Defect Failure and Quality Action • Siemens.OpcenterEX.FN.DEF_MS

Equipment Equipment • Siemens.SimaticIT.UDM_RF

Label Label Management • Siemens.SimaticIT.LBM_MS

Material • Material Templates • Siemens.SimaticIT.MAT_MS

OPCUAConnect Connection between • Siemens.SimaticIT.OPCUAConnect_MS

Personnel Personnel and users • Siemens.SimaticIT.PRM_MS

QEMigration Migration of existing Failures • Siemens.OpcenterEX.FN.QEMigration_MS

12 Opcenter Execution Foundation 4.2 - User Manual

App Name Topic Referenced Functional Blocks

Reference • Units of Measure • Siemens.SimaticIT.UDM_RF

Signals Signals • Siemens.SimaticIT.SGN_MS

System Manages base entities and • Siemens.SimaticIT.SITUASys

Task Tasks • Siemens.SimaticIT.UDM_RF

WITask Management of Task • Siemens.SimaticIT.EQU_MS

Work Instruction • Work Instructions • Siemens.SimaticIT.UDM_RF

1.1 UI Common Functionalities

Opcenter Execution Foundation 4.2 - User Manual 13

Function Icon Description

Filter To specify filtering criteria on the displayed fields.

Sort By To select a field you want to sort by, in ascending or descending

Group By To group the items by a desired field.

Search by Id To find a specific item.

Segregation The icon is displayed after selecting an entity instance. It allows

Back To move back to the previous screen.

14 Opcenter Execution Foundation 4.2 - User Manual

Home Cards and Navigation

Function Icon Description

 This is the default setting. To implement the behavior, you

Refresh To Refresh the UI application.

1.2 Home Cards and Navigation