Ignition MES Suite

MES User Manual

Inductive Automation
All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or
mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the
written permission of the publisher.
All Inductive Automation products are trademarks or registered trademarks of Inductive Automation. Other brand and
product names are trademarks or registered trademarks of their respective holders.
Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness
is implied. The information provided is on an "as is" basis. Inductive Automation shall have neither liability nor
responsibility to any person or entity with respect to any loss or damages arising from the information contained in
this book.
Printed: June 2014 in the U.S.A.

Table of Contents
Part I Introduction

18

1 Production
...................................................................................................................................
Model
19
2 Getting
...................................................................................................................................
Help
21
3 Licensing
...................................................................................................................................
and Activation
22

Part II Track and Trace

26

1 Introduction
................................................................................................................................... 26
What is Track ..........................................................................................................................................................
and Trace
26
ISA-95
.......................................................................................................................................................... 26
Resources .......................................................................................................................................................... 27
Equipment ......................................................................................................................................................... 28
Material ......................................................................................................................................................... 32
Personnel ......................................................................................................................................................... 33
Segm ents
.......................................................................................................................................................... 33
Operations .......................................................................................................................................................... 34

2 Installation
................................................................................................................................... 36
Existing Ignition
..........................................................................................................................................................
System
36
Installing Modules
......................................................................................................................................................... 36
New Ignition System
.......................................................................................................................................................... 37
Selecting Install
.........................................................................................................................................................
Options
37
Configure Database
.......................................................................................................................................................... 37
MES Module Settings
.......................................................................................................................................................... 38

3 Configuration
................................................................................................................................... 40
MES Module Configuration
.......................................................................................................................................................... 40
Datasource.........................................................................................................................................................
Settings
40
Production Model
..........................................................................................................................................................
Configuration
42
Production.........................................................................................................................................................
Model
42
Enterprise Configuration
......................................................................................................................................... 42
Site Configuration......................................................................................................................................... 44
Area Configuration
......................................................................................................................................... 45
Line Configuration
......................................................................................................................................... 46
Cell Configuration......................................................................................................................................... 47
Cell Group Configuration
......................................................................................................................................... 48
Storage Zone ......................................................................................................................................... 49
Storage Unit
......................................................................................................................................... 50

4 User Tutorial
................................................................................................................................... 53
Define Personnel
.......................................................................................................................................................... 53
Raw Material Unloading
.......................................................................................................................................................... 56
Unload Vinegar
......................................................................................................................................................... 57
Define Vinegar Unloading
......................................................................................................................................... 57
Define Vinegar Material
................................................................................................................................... 57
Define Unloading...................................................................................................................................
Equipment
61
Define Unload Vinegar
...................................................................................................................................
Tasks
68
Define Unload Vinegar
...................................................................................................................................
Segments
69
Define Unload Vinegar
...................................................................................................................................
Operations
78
Inductive Automation

Track Vinegar Unloading

......................................................................................................................................... 79
Unload Vinegar Trace
......................................................................................................................................... 82
Unload Oil ......................................................................................................................................................... 84
Define Oil Unloading
......................................................................................................................................... 84
Track Oil Unloading
......................................................................................................................................... 86
Mixing Dressing
.......................................................................................................................................................... 87
Defining Mixing
......................................................................................................................................................... 87
Tracking Mixing
......................................................................................................................................................... 90
Mix Dressing ..........................................................................................................................................................
Trace
91

5 PLC Driven
...................................................................................................................................
Tracking Tutorial
93
Define Process
.......................................................................................................................................................... 93
Define Material
......................................................................................................................................................... 93
Define Tasks
......................................................................................................................................................... 98
Define Tags .......................................................................................................................................................... 106
Add Tag Change
..........................................................................................................................................................
Event
107
Sim ulate Tracking
.......................................................................................................................................................... 109
PLC Driven Trace
.......................................................................................................................................................... 110

6 Component
...................................................................................................................................
Reference
112
MES Object Editor
.......................................................................................................................................................... 112
MES Object Selector
.......................................................................................................................................................... 120
MES Operation
..........................................................................................................................................................
Selector
125
MES Segm ent
..........................................................................................................................................................
Selector
128
MES Material..........................................................................................................................................................
Selector
134
MES Personnel
..........................................................................................................................................................
Selector
136
MES Sublot List
.......................................................................................................................................................... 138
MES Property
..........................................................................................................................................................
Value Editor
141
MES Operation
..........................................................................................................................................................
Info
143
MES Lot Selector
.......................................................................................................................................................... 146
MES Trace Graph
.......................................................................................................................................................... 152

7 Reports
...................................................................................................................................
and Analysis
160
Inventory .......................................................................................................................................................... 160
Lot Trace
.......................................................................................................................................................... 165
Sublot Trace.......................................................................................................................................................... 168
Lot Info
.......................................................................................................................................................... 170
Sublot Info .......................................................................................................................................................... 172

8 MES...................................................................................................................................
Objects
175
Overview
.......................................................................................................................................................... 175
Properties .......................................................................................................................................................... 177
Script Functions
.......................................................................................................................................................... 180
General Script
.........................................................................................................................................................
Function
181
Property Script
.........................................................................................................................................................
Functions
182
Parent/Child
.........................................................................................................................................................
Script Functions
194
Events
.......................................................................................................................................................... 197
MaterialClass
.......................................................................................................................................................... 197
MaterialDef .......................................................................................................................................................... 198
PersonnelClass
.......................................................................................................................................................... 198
Person
.......................................................................................................................................................... 198
MaterialLot .......................................................................................................................................................... 199
MaterialSublot
.......................................................................................................................................................... 200
Equipm entClass
.......................................................................................................................................................... 201
Equipm ent .......................................................................................................................................................... 201
ProcessSegm
..........................................................................................................................................................
ent
202
OperationsDefinition
.......................................................................................................................................................... 208
Inductive Automation

5
OperationsSegm
..........................................................................................................................................................
ent
210
OperationsResponse
.......................................................................................................................................................... 214
ResponseSegm
..........................................................................................................................................................
ent
215
MESEnterprise
.......................................................................................................................................................... 223
MESSite
.......................................................................................................................................................... 224
MESArea
.......................................................................................................................................................... 225
MESLine
.......................................................................................................................................................... 226
MESLineCell.......................................................................................................................................................... 227
MESLineCellGroup
.......................................................................................................................................................... 228
MESStorageZone
.......................................................................................................................................................... 229
MESStorageUnit
.......................................................................................................................................................... 230

9 Scripting
................................................................................................................................... 232
Basics
.......................................................................................................................................................... 232
MESObjectTypes
......................................................................................................................................................... 232
UUIDs ......................................................................................................................................................... 233
AbstractMESObject
......................................................................................................................................................... 233
Client / Gatew
..........................................................................................................................................................
ay Scripts
234
Operations
......................................................................................................................................................... 234
getAvailableOperations
......................................................................................................................................... 234
getAvailableReferenceOptions
......................................................................................................................................... 235
createOperation......................................................................................................................................... 235
beginOperation ......................................................................................................................................... 235
endOperation ......................................................................................................................................... 235
getCurrentOperation
......................................................................................................................................... 235
getAvailableSegments
......................................................................................................................................... 235
getOperationSegments
......................................................................................................................................... 236
Segments......................................................................................................................................................... 236
createSegment ......................................................................................................................................... 236
executeSegment
......................................................................................................................................... 236
beginSegment ......................................................................................................................................... 236
endSegment ......................................................................................................................................... 236
getCurrentSegments
......................................................................................................................................... 236
updateSegment......................................................................................................................................... 237
Lots
......................................................................................................................................................... 237
createSublots ......................................................................................................................................... 237
getLotList
......................................................................................................................................... 237
MES Object
.........................................................................................................................................................
Handling
237
invalidateCache......................................................................................................................................... 237
synchronizeMESPersonnel
......................................................................................................................................... 237
updateSegmentDependencies
......................................................................................................................................... 238
createMESObject
......................................................................................................................................... 238
deriveMESObject
......................................................................................................................................... 238
loadMESObject ......................................................................................................................................... 240
getMESObjectLink
......................................................................................................................................... 240
getMESObjectChildLinks
......................................................................................................................................... 240
searchMESObjects
......................................................................................................................................... 240
saveMESObject......................................................................................................................................... 240
hasDependencies
......................................................................................................................................... 240
Data and .........................................................................................................................................................
Analysis
241
executeMESEvent
......................................................................................................................................... 241
getInventory ......................................................................................................................................... 241
getLotTraceByLotName
......................................................................................................................................... 241
getLotTraceByLotUUID
......................................................................................................................................... 241
getLotTraceBySublotName
......................................................................................................................................... 241
Inductive Automation

getLotTraceBySublotUUID
......................................................................................................................................... 242
getLotInfoByName
......................................................................................................................................... 242
getLotInfoByUUID
......................................................................................................................................... 242
getSublotInfoByName
......................................................................................................................................... 242
getSublotInfoByUUID
......................................................................................................................................... 242
Miscellaneous
..........................................................................................................................................................
Object Reference
242
MESObjectLink
......................................................................................................................................................... 243
MESObjectFilter
......................................................................................................................................................... 248
MESPropertyValueFilter
......................................................................................................................................................... 254
ModifiedMESProperties
......................................................................................................................................................... 255
MESLotFilter
......................................................................................................................................................... 255
MESInventoryFilter
......................................................................................................................................................... 269
MESScriptEvent
......................................................................................................................................................... 281
MESObjectEventParameters
......................................................................................................................................................... 282
MESObjectCollection
......................................................................................................................................................... 282
AbstractMESComplexProperty
......................................................................................................................................................... 284

Part III OEE Downtime

288

1 Introduction
................................................................................................................................... 289
OEE
.......................................................................................................................................................... 289
TEEP
.......................................................................................................................................................... 291
Production Count
..........................................................................................................................................................
Tracking
291
Dow n Tim e Tracking
.......................................................................................................................................................... 291
Production Scheduling
.......................................................................................................................................................... 292

2 Getting
...................................................................................................................................
Started
293
Installation .......................................................................................................................................................... 293
Installing Modules
......................................................................................................................................................... 293
Configure.........................................................................................................................................................
Database
294
MES Module
.........................................................................................................................................................
Settings
294
User Interface
.......................................................................................................................................................... 295
Work Orders
......................................................................................................................................................... 297
Product Codes
......................................................................................................................................................... 298
Production
.........................................................................................................................................................
Schedule
298
Operator .........................................................................................................................................................
Screen
300
Line Charts
......................................................................................................................................................... 303
Analysis Screen
......................................................................................................................................................... 304
Report Screen
......................................................................................................................................................... 308
Dashboard .......................................................................................................................................................... 308
Area Summary
......................................................................................................................................................... 308
Enterprise.........................................................................................................................................................
Summary
310
Impromptu.........................................................................................................................................................
Analysis
311
Line Summary
......................................................................................................................................................... 311
Site Summary
......................................................................................................................................................... 312
TEEP
......................................................................................................................................................... 313
Production Model
.......................................................................................................................................................... 314
Production
.........................................................................................................................................................
Item Settings
314
Adding Production
.........................................................................................................................................................
Items
318
Configuration
.......................................................................................................................................................... 318
Components
......................................................................................................................................................... 319
Creating a.........................................................................................................................................................
Screen
319

3 Configuration
................................................................................................................................... 324
MES Module ..........................................................................................................................................................
Configuration
324
Datasource
.........................................................................................................................................................
Settings
324
Inductive Automation

7
Production Model
..........................................................................................................................................................
Configuration
325
Production
.........................................................................................................................................................
Model
326
Enterprise Configuration
......................................................................................................................................... 326
Site Configuration
......................................................................................................................................... 328
Area Configuration
......................................................................................................................................... 330
Line Configuration
......................................................................................................................................... 332
Cell Group Configuration
......................................................................................................................................... 341
Cell Configuration
......................................................................................................................................... 343
Workday Routines
.......................................................................................................................................................... 347
Dow ntim e Reasons
.......................................................................................................................................................... 349
Adding a .........................................................................................................................................................
Dow ntime Reasons
351
Editing a Dow
.........................................................................................................................................................
ntime Reasons
353
Deleting a.........................................................................................................................................................
Dow ntime Reasons
353
Import / Export
......................................................................................................................................................... 353
Product Infeed
.......................................................................................................................................................... 354
Adding a .........................................................................................................................................................
Product Infeed
354
Editing a Product
.........................................................................................................................................................
Infeed
355
Deleting a.........................................................................................................................................................
Product Infeed
355
Import / Export
......................................................................................................................................................... 355
Product Outfeed
.......................................................................................................................................................... 356
Adding a .........................................................................................................................................................
Product Outfeed
356
Editing a Product
.........................................................................................................................................................
Outfeed
357
Deleting a.........................................................................................................................................................
Product Outfeed
357
Import / Export
......................................................................................................................................................... 357
Product Waste
.......................................................................................................................................................... 358
Adding a .........................................................................................................................................................
Product Waste Counter
359
Editing a Product
.........................................................................................................................................................
Waste Counter
359
Deleting a.........................................................................................................................................................
Product Waste Counter
360
Import / Export
......................................................................................................................................................... 360

4 Component
...................................................................................................................................
Reference
361
Production Com
..........................................................................................................................................................
ponents
361
Production
.........................................................................................................................................................
Line Selector
361
Production
.........................................................................................................................................................
Cell Selector
362
Product Code
.........................................................................................................................................................
Selector
363
Product Code
.........................................................................................................................................................
Table
364
Product Code
.........................................................................................................................................................
Line Table
366
Product Code
.........................................................................................................................................................
Properties Table
367
Production
.........................................................................................................................................................
Comments Panel
368
Product Code
.........................................................................................................................................................
Controller
371
Analysis Controller
......................................................................................................................................................... 372
Production
.........................................................................................................................................................
Analysis Selector
378
Production
.........................................................................................................................................................
Stored Analysis Selector
382
Production
.........................................................................................................................................................
Bar Chart
383
Production
.........................................................................................................................................................
Pie Chart
384
Analysis Table
......................................................................................................................................................... 386
Dow n Tim e Com
..........................................................................................................................................................
ponents
388
Dow n Time
.........................................................................................................................................................
Table
388
Performance
.........................................................................................................................................................
Indicator
397
Line Run Selector
......................................................................................................................................................... 398
Analysis Time
.........................................................................................................................................................
Chart
400
Schedule Com
..........................................................................................................................................................
ponents
403
Work Order
.........................................................................................................................................................
Selector
403
Work Order
.........................................................................................................................................................
Table
404
Work Order
.........................................................................................................................................................
Controller
405
Inductive Automation

Line Schedule
.........................................................................................................................................................
Selector
407
Schedule.........................................................................................................................................................
Day View
409
Schedule.........................................................................................................................................................
Week View
411
Schedule.........................................................................................................................................................
Month View
413
Schedule.........................................................................................................................................................
Date Selector
415
Schedule.........................................................................................................................................................
Entry Controller
416
Schedule.........................................................................................................................................................
Controller
421
Time Selector
......................................................................................................................................................... 424
Line Schedule
.........................................................................................................................................................
View
425

5 Production
...................................................................................................................................
OPC Values
435
Using OPC Values
.......................................................................................................................................................... 435
OPC Value Reference
.......................................................................................................................................................... 436
Project ......................................................................................................................................................... 436
Enterprise......................................................................................................................................................... 437
Site
......................................................................................................................................................... 438
Area
......................................................................................................................................................... 439
Line
......................................................................................................................................................... 441
Cell
......................................................................................................................................................... 448
Additional.........................................................................................................................................................
Factors
452
Workday .........................................................................................................................................................
Routine
453
Dow ntime.........................................................................................................................................................
Reasons
454

6 Binding
...................................................................................................................................
Function Reference
456
Analysis
.......................................................................................................................................................... 457
Analysis Filter
......................................................................................................................................................... 457
History
.......................................................................................................................................................... 458
Dow ntime.........................................................................................................................................................
History
458
Production
.........................................................................................................................................................
History
459
Scheduled
.........................................................................................................................................................
vs. Actual
460

7 Scripting
................................................................................................................................... 462
Line Events .......................................................................................................................................................... 462
Custom OEE..........................................................................................................................................................
Calculations
463
OEE Factor Cap
.......................................................................................................................................................... 464
Gatew ay Scripts
.......................................................................................................................................................... 465
Client/Designer
..........................................................................................................................................................
Scripts
475

8 Analysis
...................................................................................................................................
Providers
484
Com m ent
Dow ntim e
OEE
Schedule
TEEP

.......................................................................................................................................................... 484
.......................................................................................................................................................... 485
.......................................................................................................................................................... 487
.......................................................................................................................................................... 490
.......................................................................................................................................................... 491

9 Miscellaneous
................................................................................................................................... 494
Additional Factors
.......................................................................................................................................................... 494
Production Rate
..........................................................................................................................................................
Calculation
494

Part IV SPC Quality

496

1 Introduction
................................................................................................................................... 497
SPC Charts .......................................................................................................................................................... 497
Scheduling Sam
..........................................................................................................................................................
ples
499
Evaluating Signals
.......................................................................................................................................................... 500

2 Getting
...................................................................................................................................
Started
501
Installation .......................................................................................................................................................... 501
Inductive Automation

9
Existing Ignition
.........................................................................................................................................................
System
501
Installing Modules
......................................................................................................................................... 501
New Ignition
.........................................................................................................................................................
System
503
Selecting Install .........................................................................................................................................
Options
503
Configure.........................................................................................................................................................
Database
503
MES Module
.........................................................................................................................................................
Settings
504
User Interface
.......................................................................................................................................................... 505
Quality User
.........................................................................................................................................................
Screens
506
Overview
......................................................................................................................................... 507
Sample Definitions
......................................................................................................................................... 508
Sample Entry ......................................................................................................................................... 514
SPC Control
.........................................................................................................................................................
Charts
516
Control Charts ......................................................................................................................................... 517
Analysis
......................................................................................................................................... 520

3 Configuration
................................................................................................................................... 524
MES Module ..........................................................................................................................................................
Configuration
524
Datasource
.........................................................................................................................................................
Settings
524
Production Model
..........................................................................................................................................................
Configuration
525
Production
.........................................................................................................................................................
Module
526
Enterprise Configuration
......................................................................................................................................... 526
Site Configuration
......................................................................................................................................... 529
Area Configuration
......................................................................................................................................... 531
Line Configuration
......................................................................................................................................... 532
Location Configuration
......................................................................................................................................... 533
Control Lim its
.......................................................................................................................................................... 536
Overview......................................................................................................................................................... 537
Default Control
.........................................................................................................................................................
Limits
537
Add Control
.........................................................................................................................................................
Limits
537
Edit Control
.........................................................................................................................................................
Limits
541
Delete Control
.........................................................................................................................................................
Limits
541
Import/Export
......................................................................................................................................................... 541
Out of Control
..........................................................................................................................................................
Signals
542
Overview......................................................................................................................................................... 542
Default Signals
......................................................................................................................................................... 543
Add Signals
......................................................................................................................................................... 543
Edit Signals
......................................................................................................................................................... 546
Delete Signals
......................................................................................................................................................... 546
Import/Export
......................................................................................................................................................... 546
Sam ple Intervals
.......................................................................................................................................................... 547
Overview......................................................................................................................................................... 547
Default Intervals
......................................................................................................................................................... 547
Add Intervals
......................................................................................................................................................... 547
Edit Intervals
......................................................................................................................................................... 549
Delete Intervals
......................................................................................................................................................... 549
Import/Export
......................................................................................................................................................... 549
SQLTag Sam..........................................................................................................................................................
ple Collectors
549
Overview......................................................................................................................................................... 549
Add Sample
.........................................................................................................................................................
Collectors
550
Edit Sample
.........................................................................................................................................................
Collectors
551
Delete Sample
.........................................................................................................................................................
Collectors
551
Import/Export
......................................................................................................................................................... 551

4 Component
...................................................................................................................................
Reference
552
Quality Com ponents
.......................................................................................................................................................... 552

Inductive Automation

Definition .........................................................................................................................................................
List
552
Definition .........................................................................................................................................................
Attribute List
556
Definition .........................................................................................................................................................
Location List
558
Definition .........................................................................................................................................................
Control Limit List
560
Definition .........................................................................................................................................................
Signals List
561
Location Selector
......................................................................................................................................................... 561
Interval Selector
......................................................................................................................................................... 563
Datatype .........................................................................................................................................................
Selector
564
Definition .........................................................................................................................................................
Selector
565
Location Sample
.........................................................................................................................................................
List
566
Sample Entry
......................................................................................................................................................... 572
SPC Com ponents
.......................................................................................................................................................... 575
SPC Selector
......................................................................................................................................................... 576
Stored SPC
.........................................................................................................................................................
Selector
581
SPC Controller
......................................................................................................................................................... 583
Histogram.........................................................................................................................................................
Chart
587
Pareto Chart
......................................................................................................................................................... 590
Xbar and .........................................................................................................................................................
R Chart
594
Xbar and .........................................................................................................................................................
S Chart
600
Median and
.........................................................................................................................................................
Range Chart
606
Individual .........................................................................................................................................................
and Range Chart
612
P-Chart ......................................................................................................................................................... 618
NP-Chart ......................................................................................................................................................... 624
U-Chart ......................................................................................................................................................... 629
C-Chart ......................................................................................................................................................... 635

5 Quality
...................................................................................................................................
OPC Values
642
Using OPC Values_2
.......................................................................................................................................................... 643
SPC OPC Value
..........................................................................................................................................................
Reference
643
Project ......................................................................................................................................................... 643
Enterprise......................................................................................................................................................... 645
Control Limits ......................................................................................................................................... 646
Signals
......................................................................................................................................... 646
Intervals
......................................................................................................................................... 647
Site
......................................................................................................................................................... 648
Area
......................................................................................................................................................... 649
Line
......................................................................................................................................................... 650
Location ......................................................................................................................................................... 653
Additional Factors
......................................................................................................................................... 656
Tag Collectors ......................................................................................................................................... 657

6 Scripting
................................................................................................................................... 659
Production Location
..........................................................................................................................................................
Events
659
Before Sample
.........................................................................................................................................................
Updated Event
659
After Sample
.........................................................................................................................................................
Updated Event
659
Sample Approval
.........................................................................................................................................................
Updated Event
660
Sample Coming
.........................................................................................................................................................
Due Event
660
Sample Due
.........................................................................................................................................................
Event
660
Sample Interval
.........................................................................................................................................................
Event
661
Sample Overdue
.........................................................................................................................................................
Event
663
Sample Waiting
.........................................................................................................................................................
Approval Event
663
Signals Evaluated
.........................................................................................................................................................
Event
663
Signal Evaluation
.........................................................................................................................................................
Results
664
Signal Out.........................................................................................................................................................
of Control Event
664
Signal in Control
.........................................................................................................................................................
Event
665

Inductive Automation

11
Sample Due
.........................................................................................................................................................
State Types
665
Object Reference
.......................................................................................................................................................... 665
Sample ......................................................................................................................................................... 665
Sample Data
......................................................................................................................................................... 669
Attribute Data
.........................................................................................................................................................
Type
670
Sample Additional
.........................................................................................................................................................
Factor
671
Sample Definition
......................................................................................................................................................... 672
Sample Definition
.........................................................................................................................................................
Attribute
677
Sample Definition
.........................................................................................................................................................
Location
680
Sample Definition
.........................................................................................................................................................
Control Limit
682
Sample Definition
.........................................................................................................................................................
Signal
683
Control Limit
.........................................................................................................................................................
Kind Type
684
SPC Category
.........................................................................................................................................................
Types
685
Signal Kind
.........................................................................................................................................................
Types
685
Control Limit
.........................................................................................................................................................
Calculated Value
686
Scripting Functions
.......................................................................................................................................................... 686
sample.production
......................................................................................................................................................... 686
sample.production.utils
......................................................................................................................................... 686
cancelLocationProductCode
................................................................................................................................... 687
setLocationProductCode
................................................................................................................................... 687
sample.quality
......................................................................................................................................................... 688
sample.quality.definition
......................................................................................................................................... 688
getNew
................................................................................................................................... 688
getSampleDefinition
................................................................................................................................... 688
addSampleDefinition
................................................................................................................................... 689
updateSampleDefinition
................................................................................................................................... 690
sample.quality.sample.data
......................................................................................................................................... 690
getNew ByDefUUID
................................................................................................................................... 690
getNew ByName
................................................................................................................................... 691
getCreateSampleByDefUUID
................................................................................................................................... 691
getCreateSampleByName
................................................................................................................................... 692
getSample
................................................................................................................................... 693
updateSample ................................................................................................................................... 693
approveSample................................................................................................................................... 694
unapproveSample
................................................................................................................................... 694
removeSample ................................................................................................................................... 695
sample.quality.spc.controllimit
......................................................................................................................................... 695
setControlLimitValue
................................................................................................................................... 695
calcControlLimitValue
................................................................................................................................... 696

7 Analysis
...................................................................................................................................
Providers
699
Quality

.......................................................................................................................................................... 699

Part V Instrument Interface

704

1 Instrument
...................................................................................................................................
Interface Module
704
Introduction .......................................................................................................................................................... 704
File Monitor Settings
.......................................................................................................................................................... 705
Serial Settings
.......................................................................................................................................................... 707
Parse Tem plate
.......................................................................................................................................................... 709
Com ponent Reference
.......................................................................................................................................................... 715
File Monitor
......................................................................................................................................................... 715
Serial Controller
......................................................................................................................................................... 720
Scripting
.......................................................................................................................................................... 729
Object Reference
......................................................................................................................................................... 729
Inductive Automation

Parse Results ......................................................................................................................................... 729

Parse Value ......................................................................................................................................... 730
Parse Row Collection
......................................................................................................................................... 731
Parse Row
......................................................................................................................................... 732
Gatew ay .........................................................................................................................................................
Scripts
733
Client/Designer
.........................................................................................................................................................
Scripts
733

Part VI Recipe / Changeover

736

1 Introduction
................................................................................................................................... 737
Recipe Types.......................................................................................................................................................... 737
Production Model
.......................................................................................................................................................... 739
Default Values
.......................................................................................................................................................... 742
Master Recipes
.......................................................................................................................................................... 744
Sub Recipes .......................................................................................................................................................... 745
Editing Recipes
.......................................................................................................................................................... 747
Recipe Change
..........................................................................................................................................................
Log
750
Recipe Security
.......................................................................................................................................................... 752
Recipe Scaling
.......................................................................................................................................................... 753
Variance Monitoring
.......................................................................................................................................................... 753
Selecting Recipes
.......................................................................................................................................................... 757
Production OPC
..........................................................................................................................................................
Server
760

2 Installation
................................................................................................................................... 764
Existing Ignition
..........................................................................................................................................................
System
764
Installing Modules
......................................................................................................................................................... 764
New Ignition..........................................................................................................................................................
System
765
Selecting .........................................................................................................................................................
Install Options
765
Configure Database
.......................................................................................................................................................... 765
MES Module ..........................................................................................................................................................
Settings
766

3 Configuration
................................................................................................................................... 768
MES Module ..........................................................................................................................................................
Configuration
768
Datasource
.........................................................................................................................................................
Settings
768
Production Model
..........................................................................................................................................................
Configuration
769
Production
.........................................................................................................................................................
Model
770
Enterprise Configuration
......................................................................................................................................... 770
Site Configuration
......................................................................................................................................... 772
Area Configuration
......................................................................................................................................... 773
Line Configuration
......................................................................................................................................... 774
Cell Configuration
......................................................................................................................................... 776
Cell Group Configuration
......................................................................................................................................... 777
Location Configuration
......................................................................................................................................... 779
Sub Recipe Mask
.......................................................................................................................................................... 780
Sub Recipe
.........................................................................................................................................................
Mask Setting
780
Recipe Values
.......................................................................................................................................................... 780
Adding a .........................................................................................................................................................
Recipe Value
781
Editing a Recipe
.........................................................................................................................................................
Value
785
Deleting a.........................................................................................................................................................
Recipe Value
785
Import / Export
......................................................................................................................................................... 785

4 Component
...................................................................................................................................
Reference
787
Recipe
Recipe
Recipe
Recipe

Editor.......................................................................................................................................................... 787
Editor..........................................................................................................................................................
Table
797
Changelog
..........................................................................................................................................................
View er
800
Variance
..........................................................................................................................................................
View er
802

Inductive Automation

13
Recipe Selector
..........................................................................................................................................................
Com bo
804
Recipe Selector
..........................................................................................................................................................
List
805

5 Analysis
...................................................................................................................................
Providers
808
Recipe Analysis
..........................................................................................................................................................
Provider
808
Recipe Variance
..........................................................................................................................................................
Analysis Provider
811
Sub Product ..........................................................................................................................................................
Code Variance Analysis Provider
813
Recipe Change
..........................................................................................................................................................
Log Analysis Provider
815

6 Production
...................................................................................................................................
OPC Values
818
Enterprise
Site
Area
Line
Cell
Cell Group
Location

.......................................................................................................................................................... 818
.......................................................................................................................................................... 819
.......................................................................................................................................................... 820
.......................................................................................................................................................... 821
.......................................................................................................................................................... 823
.......................................................................................................................................................... 825
.......................................................................................................................................................... 827

7 Scripting
................................................................................................................................... 830
Client / Gatew
..........................................................................................................................................................
ay Scripts
830
getDefaultValues
......................................................................................................................................................... 830
setPathDefaultValue
......................................................................................................................................................... 831
revertPathDefaultValue
......................................................................................................................................................... 832
createSubProductCode
......................................................................................................................................................... 833
renameSubProductCode
......................................................................................................................................................... 834
deleteSubProductCode
......................................................................................................................................................... 835
setPathRecipeValue
......................................................................................................................................................... 836
revertPathRecipeValues
......................................................................................................................................................... 837
createRecipe
......................................................................................................................................................... 838
renameRecipe
......................................................................................................................................................... 839
deleteRecipe
......................................................................................................................................................... 840
addItemToRecipe
......................................................................................................................................................... 841
removeItemFromRecipe
......................................................................................................................................................... 842
getChangelogHistory
......................................................................................................................................................... 843
getRecipeVariances
......................................................................................................................................................... 844
getItemRecipeList
......................................................................................................................................................... 845
getCurrentItemRecipe
......................................................................................................................................................... 846
getRecipeValues
......................................................................................................................................................... 847
isItemRecipeMonitoringEnabled
......................................................................................................................................................... 848
setItemRecipe
......................................................................................................................................................... 849
cancelItemRecipe
......................................................................................................................................................... 850
readItemCurrentValues
......................................................................................................................................................... 851
exportRecipe
......................................................................................................................................................... 852
importRecipe
......................................................................................................................................................... 853
getRecipeValueSecurity
......................................................................................................................................................... 854
getItemLiveRecipeValues
......................................................................................................................................................... 855
Recipe Value..........................................................................................................................................................
Scripts
856
Evaluate Variance
.........................................................................................................................................................
Script
856
Request Value
.........................................................................................................................................................
Script
857
Object Reference
.......................................................................................................................................................... 857
ChangelogFilters
......................................................................................................................................................... 858
VarianceFilters
......................................................................................................................................................... 859
ItemRecipeValue
......................................................................................................................................................... 861
RecipeTag
......................................................................................................................................................... 862
RecipeValueSecurityInfo
......................................................................................................................................................... 864
RecipeValueSecurityRole
......................................................................................................................................................... 864
Inductive Automation

Part VII Web Services

868

1 Introduction
................................................................................................................................... 868
What Are Web
..........................................................................................................................................................
Services
868
Netw ork Com
..........................................................................................................................................................
m unications
868
XML
.......................................................................................................................................................... 868
WSDL
.......................................................................................................................................................... 869
SOAP
.......................................................................................................................................................... 870

2 Installation
................................................................................................................................... 871
Existing Ignition
..........................................................................................................................................................
System
871
Installing Modules
......................................................................................................................................................... 871
New Ignition..........................................................................................................................................................
System
872
Selecting .........................................................................................................................................................
Install Options
872

3 Configuration
................................................................................................................................... 873
Web Service ..........................................................................................................................................................
Configuration
873
WSDL Settings
......................................................................................................................................................... 873
Operation.........................................................................................................................................................
Settings
874
Parameters
......................................................................................................................................................... 874
Listener Configuration
.......................................................................................................................................................... 875
Listener Configuration
.........................................................................................................................................................
Settings
875
Listener Interval
.........................................................................................................................................................
Settings
876
Listener Event
.........................................................................................................................................................
Scripts
876
Listener Parameters
......................................................................................................................................................... 877

4 User...................................................................................................................................
Tutorial
878
Web Service ..........................................................................................................................................................
Configuration
878
Setup Listener
.......................................................................................................................................................... 885

5 Scripting
................................................................................................................................... 888
Client / Gatew
..........................................................................................................................................................
ay Scripts
888
runWebService
......................................................................................................................................................... 888
activateListener
......................................................................................................................................................... 890
deactivateListener
......................................................................................................................................................... 890
deactivateAllListeners
......................................................................................................................................................... 890
toDict
......................................................................................................................................................... 891
toDataset......................................................................................................................................................... 891
Miscellaneous
..........................................................................................................................................................
Object Reference
891
BeforeRunEvent
......................................................................................................................................................... 891
AfterRunEvent
......................................................................................................................................................... 891
ServiceErrorEvent
......................................................................................................................................................... 892
ParseErrorEvent
......................................................................................................................................................... 892
WSVariable
......................................................................................................................................................... 892
WSOperation
......................................................................................................................................................... 893
WSElement
......................................................................................................................................................... 894

Part VIII Barcode Scanner

896

1 Introduction
................................................................................................................................... 896
2 Installation
................................................................................................................................... 898
Existing Ignition
..........................................................................................................................................................
System
898
Installing Modules
......................................................................................................................................................... 898
New Ignition..........................................................................................................................................................
System
899
Selecting .........................................................................................................................................................
Install Options
899

3 Component
...................................................................................................................................
Reference
900
Inductive Automation

15
Barcode Controller
.......................................................................................................................................................... 900

4 Scripting
................................................................................................................................... 906
Client / Gatew
..........................................................................................................................................................
ay Scripts
906
getPatternList
......................................................................................................................................................... 910
getNew BarcodePattern
......................................................................................................................................................... 911
decode ......................................................................................................................................................... 911
Miscellaneous
..........................................................................................................................................................
Object Reference
912
Barcode Event
......................................................................................................................................................... 913

Index

Inductive Automation

917

Introduction
Part I

Introduction

18

Introduction

Inductive Automation

Introduction

1.1

19

Production Model

To start out, it is important to define what the production model is, which is heavily referred to when
dealing with OEE and downtime.
A production model defines your manufacturing or process in tree view form. It provides an organized way
to easily configure, control and analyze your facility.

Production Model Tree

Inductive Automation

Introduction

20

Enterprise
The enterprise is the highest level of the production model and typically represents a manufacturing
company. A company may have one or more production facilities.
Site
A site is a geographical production location and is part of an enterprise. Separating your enterprise into
multiple production sites allows for comparing OEE, downtime and production information between
them.
Area
An area is a physical or logical grouping of production lines.
Line
A line is a collection of one or more cells and/or cell groups that run a single product at any given time.
Typically, the product flows from one cell or cell group to the next in sequence until the product, or sub
assembly, being produced is complete.

Cell Group Tree

Location
A location is the space where a sample is collected. This can be placed under an area or a line and is
used only in the SPC Quality Module
Cell Group
A cell group contains two or more cells. Typically, these cells occur at the same time in the sequence of
the line instead of one after another, causing the cell group to act as a single sub process or step within
the production.
Cell
The cell is a single machine, sub process or step required in the manufacture a product. The product
may be a hard product such as used in packaging, adding liquid or powder, etc. Packaging machines are
a common example, but a cell applies to processes also.

Inductive Automation

Introduction

1.2

21

Getting Help

There are multiple methods of getting help with both Ignition and the MES modules:
Online Forum
From www.inductiveautomation.com website, the online support forum can be accessed to search for
solutions and post questions. It is actively patrolled by Inductive Automation staff and many
knowledgeable users.
Email Support
E-mail support is available at [email protected]
Phone Support
You can reach us during business hours 8am-5pm Pacific time at 1-800-266-7798. Support charges may
apply. 24-hour support is also available for an addition fee.
Design Services
Inductive Automation has design support staff skilled in working with IT, maintenance, production
departments and integrating the OEE Downtime and Scheduling module to the plant floor and ERP
systems. For more information, contact sales.

Inductive Automation

Introduction

1.3

22

Licensing and Activation

Trial Mode
The MES modules follow the same trial operation as Ignition. Any MES module can be used for 2-hours at
a time, with no other restrictions. At the end of the trial period, the system will stop logging data to the
database, display expired trial overlays on live values and clients will see a demo screen. By logging into
the gateway, you may re-start the demo period, and enable another 2 hours of execution. The demo
period may be restarted any number of times.
You may install an unlicensed MES module into a licensed Ignition server. The Ignition server licensing will
not be affected and the MES module will operate in Demo mode.
Licensing
The MES license can be purchased along with, or separately from, the Ignition license. Despite the
modular licensing, each Ignition server only has a single CD-Key and license file. That is, there is a single
license file that dictates which modules are current activated.
When module(s) are purchased, you will receive a CD-Key - a six digit code that identifies your purchase.
You then use this CD-Key to activate the software through the Ignition Gateway. Activation is a process by
which the CD-Key and its associated parameters get locked to the machine that you are activating. If you
adding an additional module, your account will be updated, and you can re-use your existing CD-Key to
activate the new features. For this reason, if you purchased the MES module separately from the Ignition
server, the MES license will have to be added to your existing CD-Key.
It is possible to inactivate your CD-Key, freeing it for activation on a different machine.
Not all production facilities have the large number of lines and cells while others do. For this reason there
are two basic editions to choose from to meet your situation:
Standard License
The Standard edition provides OEE, downtime and scheduling functionality for unlimited production areas,
lines and cells. Includes the OEE, downtime and schedule engine; configuration software; user interface
screens; enhanced analysis tools; and reports. There are no restrictions on the number of tags, logged
data items, screens or clients (users).
Line License
The Standard edition provides OEE, downtime and scheduling functionality for a single production lines.
Multiple Line Licenses can be installed on a single server. There is no limit on the number of cells that a
line can be configured for. Includes the OEE, downtime and schedule engine; configuration software; user
interface screens; enhanced analysis tools; and reports. There are no restrictions on the number of tags,
logged data items, screens or clients (users).
Enterprise Extension
In addition to the above editions, the Enterprise Extension allows analysis and reporting across multiple
physical production sites from anywhere on your network. Compare efficiency and downtime by
production line, operator, user defined values and more. Requirements: Standard or Line License for the
OEE Downtime Module, and the Reporting module.
Activation
Activation, as mentioned above, is the method by which a cd-key is locked down to the install machine,
and the modules are notified of their license state. It is a two step process that can be performed
Inductive Automation

Introduction

23

automatically over the internet, or manually through email or the Inductive Automation website.
Step 1 - Enter CD-Key
When the software is purchased, you are provided with a six digit CD-key. After logging into the
gateway configuration, go to Licensing > Purchase or Activate, and select "Activate".
Enter your CD-key.
Step 2a - Activate over Internet
If your computer has internet access, activating over the internet is the easiest option. A secure file
will be created with your cd-key, and sent to our servers. The response file will then be downloaded
and installed, completing the entire process in seconds.
OR
Step 2b - Activate Manually
If you do not have internet access on the installation machine, you must activate manually. In this
process, an activation request file is generated (activation_request.txt). You must then take
this file to a machine with internet access, and email it to [email protected], or visit
our website to activate there. Either way will result in a license file (license.ipl) being generated,
which you then must take back to the Gateway machine and enter into the License and Activation
page.

Inductive Automation

Track and Trace

Part II

Track and Trace

Track and Trace

2.1

Introduction

26

The Track and Trace module extends Ignition to manage and track production and then providing trace
results. It is ideal for quickly implement track and trace systems without the need to design database
schemas because it is handled by the module. New Ignition components are also included that eliminate
the need build custom screens with entry boxes for each values accepted by the user or barcode
scanner. Also included, is a powerful visual management component to define material, personnel,
equipment, production tasks, routes, etc. Then trace results are visually analyzed using the trace graph
component.

2.1.1

What is Track and Trace

Overview
Knowing where product is and has been in a production facility can be very valuable. In the typical
production environment, time series data is collected by the SCADA or HMI systems. To give that data
context to the specific product being produced, or other criteria, can provide the picture into your process
that is very valuable when diagnosing quality or other issues. It is also very valuable for narrowing down
recalls and regulatory compliance.

Tracking Product
In the real-world production environment, tracking product is not as easy as it sounds. It impacts
production staff and can hinder their efficiency. In some cases tracking information maybe provided by
another system and in other cases it might require user input. It is preferable that the user input is done
realtime as opposed to the operator writing on paper and a data entry person entering it into the system.
In general, an effective system will have a minimal impact the operations staff.

Tracing Product
This is the analysis and reporting of the details that went into making or processing a product. In the
Ignition MES system, it includes linking other data such as data from the historian, OEE, SPC, recipe or
even data from external systems.

2.1.2

ISA-95

Overview
Originally ISA stood for Instrument Society of America. ISA have evolved into more than just instruments
and beyond America, and as a results changed to International Society of Automation. ISA has set many
standards used for automation, but the Track and Trace Module is specifically build around the ISA-95
standard that was developed to automate the interface between enterprise financial systems and control
systems on the plant floor.
Information that the top level system or ERP (Enterprise Resource Planning) has about upcoming
production requirements is needed on the plant floor. Likewise, some of the production details from the
plant floor is valuable at the ERP level.
Plant floor control systems are designed to control processes and machines and are not well suited to
Inductive Automation

Track and Trace

27

handle much production data. They can make control decisions in the 5mS to 200mS range, but have
limited historical storage and database capabilities.
ERP systems are well suited to processed financial, inventory, receivables, etc. They do a great job of
accepting orders, checking if additional raw material should be ordered, paying vendors, reporting and
etc. that can be updated anytime during a day, week, month, quarter or even year.
Both the speed of the plant floor control systems and the planning and tracking ability of an ERP system
is needed in the middle ground. This middle ground is commonly referred to as MES (Manufacturing
Management System) and MOM (Manufacturing Operations Management).

Functional Hierarchy Model

The objectives of the ISA-95 standard are to provide a consistent operational model and terminology that
is a foundation for the different levels to communicate. In addition, systems on the same level can
communicate in a consistent manor. It was developed to be applied in all industries and all sorts of batch
processes, continuous processes and discrete manufacturing.
In this era of manufacturing, data stored in proprietary systems or in systems where it requires hours in
custom programming to share data between systems, will not provide what is needed. In this era,
manufacturing information systems must be data centric solution. Operations has their wish list and the
cost, schedule and risk to create such a system is monumental and as a results typically doesn't happen.
In other cases, funding is approved and the project is started, but it falls short of expectations. There has
to be an easier way!
The Ignition Track and Trace Module is aligned with the ISA-95 model. If we started from scratch and
developed our own, which was tempting because modeling after the ISA-95 standard is not a easy task,
we would be yet another company with a different model that other have to learn and adapt to. If we did,
we would be doing our customers and the industry a disservice.

2.1.3

Resources

Any task that is done during manufacturing, requires resources. Resources can be material, equipment
and personnel. The image below shows a basic task of Bottling Wine and has three resources of Wine
(material), Bottling Line 1 (equipment) and Bottling Operator (personnel). It also shows the resource
Bottled Wine (material) that was created from the task.

Inductive Automation

Track and Trace

28

Basic Segm ent and Associated Resources

If more detail is desired, then more resources can be added to the Bottle Wine task. Below we see
Bottles, Corks and Labels, all of which are material, have been added. Also, another Inspector has been
added as personnel. There is no limit to the number of resources that can be added. However, keep in
mind that details about the resources have to be entered during production impacting the production staff.

More Detailed Segm ent and Associated Resources

2.1.3.1

Equipment

Equipment
Any automated production or processing that is done requires equipment. Manual production or
processing is done at a location such as unloading at a dock. The dock is the location where the
production or processing is taking place. It can also be manually adding a antenna at a work cell.
In the Ignition MES system, there are two types of equipment, processing equipment and tooling or rolling
equipment.

Processing Equipment
The processing equipment is defined in the production model and is defined using in the Ignition designer.
Inductive Automation

Track and Trace

29

The reason equipment is defined in the Ignition designer is because tags are used to collect production
data, downtime, SPC sample data, etc. for it. Tags can only be assigned in the designer and also involves
configuration in the control system, through the OPC server and tags to the equipment defined in the
production model.

Tooling or Rolling Equipment

Tooling and rolling equipment can be defined either in the Ignition Designer or in the Ignition client. By
allowing tooling or rolling equipment to be defined in the Ignition client, provides dynamic changes by a
user that otherwise has not need to access the Ignition Designer. This is handy for tooling such as dies,
jigs, etc. but can also include rolling equipment such as forklifts.

Equipment Hierarchy
The processing equipment is organized into a hierarchy that starts at the top and works down to the
equipment. The Ignition MES suite, uses this model to define equipment that is relatively permanent. This
means equipment that tags are used to read information from and send control information down to
during production. Because tags are involved, this type of equipment is defined in the Ignition Designer.
Other rolling or tooling equipment that do not use tags can either be configured in the Ignition Designer,
MES object editor or from the built-in scripting language.

Equipm ent Hierarchy

Inductive Automation

Track and Trace

30

The equipment defined in the production model is where production tasks can be done. The rolling or
tooling equipment can be added as additional equipment resources use during the production tasks. For
example, a press (Production Line defined in the production model) will have associated dies used for
making various products. If tracking of which die was used for a production task, then the die can be
defined as a rolling or tooling equipment item separate from the the press.

Production Model
In the Ignition MES system, the equipment hierarchy is defined in the production model. It is important to
define what the production model is, because everything done in the Ignition MES system revolves around
it.
A production model defines your manufacturing or process in tree view form. It provides an organized way
to easily configure, control and analyze your facility. It does not control the possible routes that product
flows within a facility, but simply is a organized manor in which to manage machinery.

Production Model Tree

Inductive Automation

Track and Trace

31

MES Enterprise
The enterprise is the highest level of the production model and typically represents a manufacturing
company. The Ignition MES system only supports one enterprise per Ignition server but can have
one or more production facilities (sites).
MES Site
A site is a geographical production location and is part of an enterprise.
MES Area
An area is a physical or logical grouping of production types within a production facility.
MES Line
A line is a collection of one or more cells (machines) and/or cell groups (groups of machines) where
product can be produced. It may have one or more machines or sub processes.
MES Line Cell
The cell is a single machine, sub process or step required in the manufacturing of a product.
MES Line Cell Group
A cell group contains two or more cells. Typically, these cells occur at the same time in the sequence
of the line instead of one after another, causing the cell group to act as a single sub process or step
within the production.

Cell Group Tree

MES Storage Zone

The storage zone is a space that material is stored. There can be multiple storage zones within an
area. Each storage zone can have storage units where actual product is stored.
MES Storage Unit
The storage unit resides in a storage zone and provide greater granularity of where material is stored.

Equipment Path
In the Ignition MES system, specific equipment is normally referred to by the equipment path. It is
simply the route starting with the enterprise and following down the items in the production model tree
to the specific equipment item.
Referring to the production model in the image below, the equipment path to Line 1 is Your
Enterprise/Your Site/Your Area/Line 1.

Inductive Automation

Track and Trace

32

Equipm ent Path

Although it is not recommended, it is possible to have more than one line named Line 1. An
equipment path will specify only one of the lines named Line 1, which is required for all Ignition MES
functionality.

Equipment Classes
Defining production tasks for each specific piece of equipment, is very tedious. A better method would
be to organize the equipment into categories, or class using ISA-95 terms. An example will make this
clearer with fewer words. Consider five packaging lines in a packaging area and three of them can
package mixed nuts and the remaining two cannot. Creating a mixed nuts equipment class with the
three line within it, allows a single task to be defined specifying that a mixed nuts equipment resource
is required.

2.1.3.2

Material

Material
Any Production or processing that is done involves material. The material maybe raw material that goes
into finished goods, or it can be consumable or by-product that is not directly related to the finished goods.

Material Definition
Material definitions are used to define raw materials, material that are partially processed but not in
finished goods state and finished goods. Consider the following case: If we are assembling an electronic
product, then we will have electronic components, including a circuit board, that will each have material
definitions. The components will be soldered to the circuit board and will have a material definition for the
sub assembly. Next, the circuit board will be added to the housing which will have a material definition that
represents it. This will continue until the finished goods are complete. It may even include accessories
that are sold with the finished product. Each will have a material definition. Think of this way, in order to
know which lots of components were used to make a batch of circuit boards, then material definitions are
needed.

Material Classes
Defining production tasks for each specific material, is very tedious. A better method would be to organize
the material into categories, or class using ISA-95 terms. An example will make this clearer with fewer
words. Consider unloading electronic components at a receiving dock. Defining a task to receive each
type of component would be a management nightmare. Instead all of the components can be added to a
Electronic Component class and when the operator does the receive components task at the dock, it
prompts them for the specific component that belongs to the Electronic Components class. Only one
Inductive Automation

Track and Trace

33

receive components task has to be defined, which is much easier to manage.

2.1.3.3

Personnel

Personnel
Any Production or processing that is done involves people. In the Ignition MES system, this is optional. If
trace information about the personnel involved in the production or processing is desired, then it is
supported. The person can be automatically selected based on their Ignition login or it can be selected by
another means.

Person
The MES Person objects are automatically generated from the Ignition users that have first and last
names defined. This prevent the default "admin" user from being created in the MES system and showing
up in selection lists. When the Ignition MES modules first start, the MES Person objects are synchronized
and then will be synchronized on a hourly basis thereafter. They can also synchronized on demand using
a script function.

Person Classes
Defining production tasks for each specific person, is very tedious. A better method would be to organize
the people into categories, or class using ISA-95 terms. An example will make this clearer with fewer
words. Consider unloading vinegar at a unloading pump station. If there are ten operator who are qualified
to unload vinegar, then creating a Vinegar Unload Operator class containing the ten qualified operators,
only will require one unload vinegar task definition. Adding an eleventh operator is as simple as adding that
person to the Vinegar Unload Operator class.

2.1.4

Segments

Segments
Any task that is done during manufacturing, requires resources. Resources can be material, equipment
and personnel. The image below shows a basic segment of Bottling Wine and has three input resources
of Wine (material), Bottling Line 1 (equipment) and Bottling Operator (personnel). Then there is one output
material resource of Bottled Wine. Most often there is only one output material resource, but in some
situations there can be multiple output resources. If not much trace detail is needed, then this is the
minimum that is needed to run production. Actually, for the Track and Trace Module, material and
equipment are required but the personnel is optional.

Basic Segm ent and Associated Resources

Inductive Automation

Track and Trace

34

If more detail is desired, then more resources can be added to the Bottle Wine segment. Below we see
Bottles, Corks and Labels, all of which are material, have been added to the segment. Also, another
Inspector has been added as personnel. There is no limit to the number of resources that can be added
to a segment. However, keep in mind that details about the resources have to be entered during
production.

More Detailed Segm ent and Associated Resources

2.1.5

Operations

Production is not always as simple as run production, and might involve more that just one step. This is
accomplished by including multiple segments into a operation. Remember that segments are the basic
tasks. Now we can link multiple segments (tasks) together into a operation to perform more complicated
tasks as shown in the image below.

Inductive Automation

Track and Trace

35

Operation and Associated Segm ents and Resources

The image below shows how Process Segments are used by Operations Segments and how Operation
Definitions refer to Operations Segments. Collectively, these are in the definition side. They are only
created or modified when users are defining their production process.
On the production side, Operations Response and Response Segments are created when the operator
begins production. As a result, there will be a set of Operation Response and Response Segments for
each production run.

Definition and Production

Inductive Automation

Track and Trace

2.2

36

Installation

To install the Track and Trace Module into an existing Ignition system, follow the instructions in the
Existing Ignition System. If you are installing Ignition at the same time, use the instructions in the New
Ignition System.

2.2.1

Existing Ignition System

2.2.1.1

Installing Modules

To install the Track and Trace Module onto an existing Ignition server, follow the steps below:
Before installing the Track and Trace Module, it is recommended to first set up the database connection
that will be used to store track and trace data.
PLEASE NOTE:
It is also highly recommended that you do a backup of the Ignition system and database(s) before
upgrading or installing any new modules.
1. Download the Trace-Installer-module.modl module
from the Inductive Automation download website. It will be under the MES modules heading.
2. Install the Trace-Installer-module.modl module
Navigate to the Modules page of the Ignition gateway. At the bottom of the list of already installed modules,
click the
link located at the bottom of the page. Next, browse to the TraceInstaller-module.modl file and click the install button as shown below.

Install Ignition Module

Inductive Automation

Track and Trace

37

The Trace Installer module will install all required MES modules. These are the Production and Trace
modules. It is important to keep in mind not to install or update these modules individually. Instead, it
should be done by updating the Trace Installer module.

2.2.2

New Ignition System

2.2.2.1

Selecting Install Options

To install the Track and Trace Module at the same time as Ignition, add the following steps to the normal
Ignition installation:
1. Select "Custom Configuration" on the setup step during the Ignition installation.
The following screen will appear. Scroll down to Track and Trace Module and select it. This will cause the
modules required for track and trace functionality to be installed at the same time as Ignition.

.
Ignition Installer

2.2.3

Configure Database

Track and trace data is stored in a database(s) external to Ignition. These database(s) are setup in the
gateway configuration section by selecting the Databases> Connections section from the left-hand
configuration menu. See the Ignition documentation for more information on setting up a database
connection. Below shows a typical database connection that is required for the Track and Trace Module.

Inductive Automation

Track and Trace

38

Sam ple Database Connection

2.2.4

MES Module Settings

The Track and Trace Module derives MES Person object from the built-in users Ignition is configured for
that have first and last names assigned. Because Ignition can have multiple User Source Profiles, the
MES system must be configured to which one to use. In the Authentication section, select the user
source profile to have the MES system use.
The Track and Trace, OEE Downtime, Scheduling, SPC and Recipe modules store data in an SQL
database. Because Ignition can be configured for multiple databases, the MES Module Settings
configuration page is used to select which databases to store track and trace, OEE, downtime,
scheduling, SPC and Recipe data. If only one database has been configured in Ignition, then it will be
selected by default.
To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules. If more than one database connection exists,
then the desired database connection can be selected to be used by the MES modules as shown below.
All MES database tables and indexes will be created automatically in the selected database.
PLEASE NOTE:
The recommended procedure to change the database on an existing system, is to stop current
production in the MES system, disable the production model in the designer, change the data setting, re
enable the production model and restart production.

Inductive Automation

Track and Trace

MES Module Settings Page

Inductive Automation

39

Track and Trace

2.3

40

Configuration

There are two areas to configure the Track and Trace Module. The first area is in the Ignition Gateway and
affects all MES Modules.
The second is in the Ignition Designer and is used to configure production models, user screens and the
like. These settings are saved in an Ignition project and can be backed up and restored using the built-in
project backup and restore features of Ignition.

2.3.1

MES Module Configuration

The Track and Trace Module is just one of the MES (Manufacturing Execution System) modules that has
settings which can be set.
2.3.1.1

Datasource Settings

Track and trace data is stored in databases external to Ignition. These database(s) are setup in the
gateway configuration section by selecting the Databases> Connections section from the left-hand
configuration menu. See the Ignition documentation for more information on setting up a database
connection. Below shows a typical database connection that is required for the Track and Trace Module.
Currently, the MES Suite supports MySQL, SQL Server, Oracle and PostgreSQL.

Sam ple Database Connection

To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules. If more than one database connection exists,
then the desired database connection can be selected to be used by the MES modules as shown below.

Inductive Automation

Track and Trace

41

MES Module Settings Page

Authentication
The Track and Trace Module derives MES Person object from the built-in users Ignition is configured for
that have first and last names assigned. Because Ignition can have multiple User Source Profiles, the
MES system must be configured to which one to use. In the Authentication section, select the user
source profile to have the MES system use.
Runtime Database
The runtime database is not used for the Track and Trace Module.
Data Retention Duration
Because the Runtime database is not used specifically for the Track and Trace Module, this setting does
not apply.
Analysis Database
The analysis database is where all track and trace data is stored.
Analysis Database (Auxiliary)
The MES Modules will mirror the track and trace information that is written to the local analysis database
to this database. For single site implementations, set this to "-none-". This can be set to share track and
trace information to remote enterprise database.
Inductive Automation

Track and Trace

42

Analysis Query Cache Duration

This setting represents the number of seconds to cache analysis results. Analysis is used to compare
retrieve trace information for the trace graph, reporting and etc.

2.3.2

Production Model Configuration

A production model defines your manufacturing or process in tree view form. It provides an organized way
to easily configure, control and analyze your facility. It starts with your enterprise, which represents your
company, and continues down to the site (physical location), area, line and cells.
As described in the Resources in the Introduction chapter, equipment is used during track and trace
operations. They are also used for OEE, SPC and Recipe Modules.
2.3.2.1

Production Model

The production model is configured within the Ignition designer and is accessed by selecting the
"Production" folder under the Global node in the project browser. From here your enterprise, site, area(s),
line(s) and line cell(s), line cell group(s), storage zone(s) and storage unit(s) can be added, renamed and
deleted.

Production Model Tree

2.3.2.1.1 Enterprise Configuration

The Enterprise item is added automatically and only one can exist per Ignition server. For this reason the
Add and Delete menu items will not appear for the Enterprise item.
Renaming an Enterprise
To rename it to the name of your enterprise, right-click on it and select Rename, then enter the new
name.
Important Note
It is extremely important to understand that production OPC values have an OPC item path that
Inductive Automation

Track and Trace

43

matches the layout of the production model and that renaming production items can cause Ignition
tags associated with a production item to stop being updated. See Production OPC Server for more
information.

Enterprise Nam e

Inductive Automation

Track and Trace

44

General Enterprise Settings

For the enterprise, there are only general settings. These settings are accessed by selecting the
enterprise item contained in the"Production" folder in the project browser and then selecting the
"General" tab as shown below.

Enterprise General Settings

Enabled

By default, the enterprise item is enabled. It can be disabled by un-checking the

Enabled setting and saving the project. This will stop the track and trace, OEE,
downtime, SPC, recipe and scheduling modules from executing the enterprise and all
other production items that are underneath it.

Description

This is an optional description and is just for your reference.

MES Events

This is where events are defined for the different types of MES objects. See MES
Events in the MES Object chapter for more inofrmation.
There are two types of events. System events are predefined and cannot be added,
deleted or renamed, but do allow entering script to execute when the event is
triggered. The second type are custom events that can be added, deleted or renamed
and are executed from script.

2.3.2.1.2 Site Configuration

Adding a Site
To add your site, right-click on your enterprise folder in the project browser and select the New
Production Item > New Production Site menu item. A site named "New Site" will be added to the
enterprise folder.

Inductive Automation

Track and Trace

45

Renaming a Site
To rename it to the name representing the site's physical location, right-click on it and select Rename,
then enter the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Site
To remove an existing site, right-click on the site item and select the Delete menu item. A window will
appear confirming that you permanently want to delete the production site. Please note that the area(s),
line(s), cell(s), cell group(s) and location(s) underneath the site will also be permanently removed.

New Site

General Site Settings

These settings are accessed by selecting the site item contained in the enterprise folder in the project
browser, and then selecting the "General" tab.
Enabled

By default, the site item is enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the track and trace, OEE, downtime,
SPC, recipe and scheduling modules from executing the site and all other production
items that are underneath it.

Description

This is an optional description and is just for your reference.

2.3.2.1.3 Area Configuration

Adding an Area
To add a production area, right-click on your site folder in the project browser and select the New
Production Item > New Production Area menu item. An area named "New Area" will be added to the
site folder. Multiple production areas can be added to your production site. Each area can represent a
physical or logical production area within your production site. Some examples of production areas are:
packaging, cracking, filtration, fabrication, etc.
Renaming an Area
To rename it to the name representing the production area, right-click on it and select Rename, then
enter the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
Inductive Automation

Track and Trace

46

information.
Deleting an Area
To remove an existing production area, right-click on the area item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production area. Please note that
the line(s), cell(s), cell group(s) and location(s) underneath the area will also be permanently removed.

New Area

Area General Settings

These settings are accessed by selecting the desired area item contained in the site folder in the project
browser and then selecting the "General" tab.
Enabled

By default, the area item is enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the track and trace, OEE, downtime,
SPC, recipe and scheduling modules from executing the area and all other production
items that are underneath it.

Description

This is an optional description and is just for your reference.

2.3.2.1.4 Line Configuration

Adding a Line
To add a production line, right-click on an area folder in the project browser and select the New
Production Item > New Production Line menu item. A line named "New Line" will be added to the area
folder. Multiple production lines can be added to a production area.
Renaming a Line
To rename it to the name representing the production line, right-click on it and select Rename, then enter
the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Line
To remove an existing production line, right-click on the line item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production line. Please note that
the cell(s), cell group(s) and location(s) underneath the line will also be permanently removed.

Inductive Automation

Track and Trace

47

New Line

Line General Settings

These settings are accessed by selecting the desired line item contained in the area folder in the project
browser and then selecting the "General" tab.
Enabled

By default, the line item is enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the track and trace, OEE, downtime,
SPC, recipe and scheduling modules from executing the line and all other production
items that are underneath it.

Description

This is an optional description and is just for your reference.

2.3.2.1.5 Cell Configuration

Adding a Cell
To add a production cell, right-click on a line folder in the project browser and select the New Production
Item > New Production Cell menu item. A cell named "New Cell" will be added to the line folder. Multiple
production cells can be added to a production line.
Renaming a Cell
To rename it to the name representing the production cell, right-click on it and select Rename, then enter
the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Cell
To remove an existing production cell, right-click on the cell item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production cell.

Inductive Automation

Track and Trace

48

Deleting a Cell

Cell General Settings

These settings are accessed by selecting the desired cell item contained in the line folder in the project
browser and then selecting the "General" tab.
Enabled

By default, the cell item is enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the track and trace, OEE, downtime,
SPC, recipe and scheduling modules from executing the line cell.

Description

This is an optional description and is just for your reference.

2.3.2.1.6 Cell Group Configuration

Adding a Cell Group

To add a production cell group, right-click on a line folder in the project browser and select the New
Production Item > New Production Cell Group menu item. A cell group named "New Cell Group" will
be added to the line folder. Multiple production cell groups can be added to a production line.
Renaming a Cell Group
To rename it to the name representing the production cell group, right-click on it and select Rename,
then enter the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Cell Group
Inductive Automation

Track and Trace

49

To remove an existing production cell group, right-click on the cell group item and select the Delete menu
item. A window will appear confirming that you permanently want to delete the production cell group.
Please note that the cell(s) underneath the cell group will also be permanently removed.

Adding a Cell Group

Cell Group General Settings

These settings are accessed by selecting the desired cell group item contained in the line folder in the
project browser and then selecting the "General" tab.
Enabled

By default, the cell group item is enabled. It can be disabled by un-checking the
Enabled setting and saving the project. This will stop the track and trace, OEE,
downtime, SPC, recipe and scheduling modules from executing the line cell group
and all other production items that are underneath it.

Description

This is an optional description and is just for your reference.

2.3.2.1.7 Storage Zone

Adding a Storage Zone

To add a storage zone, right-click on an area folder in the project browser and select the New
Production Item > New Storage Zone menu item. A storage zone named "New Storage Zone" will be
added to the area folder. Multiple storage zones can be added to a production area.
Renaming a Storage Zone
To rename it to the name representing the production storage zone, right-click on it and select Rename,
then enter the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
Inductive Automation

Track and Trace

50

information.
Deleting a Storage Zone
To remove an existing production storage zone, right-click on the storage zone item and select the
Delete menu item. A window will appear confirming that you permanently want to delete the production
storage zone.

Deleting a Storage Zone

Storage Zone General Settings

These settings are accessed by selecting the desired cell item contained in the line folder in the project
browser and then selecting the "General" tab.
Enabled

By default, the storage zone item is enabled. It can be disabled by un-checking the
Enabled setting and saving the project. This will stop the track and trace, OEE,
downtime, SPC, recipe and scheduling modules from executing the storage zone and
all other production items that are underneath it.

Description

This is an optional description and is just for your reference.

2.3.2.1.8 Storage Unit

Adding a Storage Unit

To add a production cell, right-click on a line folder in the project browser and select the New Production
Item > New Storage Unit menu item. A storage unit named "New Storage Unit" will be added to the
Inductive Automation

Track and Trace

51

storage zone folder. Multiple production storage units can be added to a production storage zone.
Renaming a Storage Unit
To rename it to the name representing the production cell, right-click on it and select Rename, then enter
the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Storage Unit
To remove an existing production storage unit, right-click on the storage unit item and select the Delete
menu item. A window will appear confirming that you permanently want to delete the production storage
unit.

Deleting a Storage Unit

Storage Unit General Settings

These settings are accessed by selecting the desired cell item contained in the line folder in the project
browser and then selecting the "General" tab.
Enabled

Inductive Automation

By default, the storage unit item is enabled. It can be disabled by un-checking the
Enabled setting and saving the project. This will stop the track and trace, OEE,
downtime, SPC, recipe and scheduling modules from executing the storage unit.

Track and Trace

Description

52

This is an optional description and is just for your reference.

Inductive Automation

Track and Trace

2.4

53

User Tutorial

The following tutorial steps through defining production, tracking production and analyzing and reporting
on the trace results. Defining production is the important step that should not be rushed and if not fully
thought throw, will cause unexpected trace results and cause production staff difficulty when handling
unusual or unexpected production situations.
This tutorial requires the Track and Trace demo project. Please follow the demo installation instructions
before continuing.

2.4.1

Define Personnel

Although not required, it is beneficial to track who handled material at the various stages as it flows
through a production facility.
The same users that are configured in Ignition are used here. This eliminates the need for double entry.
But, organizing the users into smaller groups is beneficial during analysis and reporting and is something
covered later in this tutorial.
If this is a fresh installation of Ignition, add some users to the Ignition system and assign first and last
names for them before continuing with this section. Otherwise, the only user is admin that will not appear
in the MES system because there is no first or last name set for it.

Personnel Step 1
To get started, open a client for the Track and Trace demo project. Using the MES Manager screen,
select the Personnel tab and right click on the open workspace. This will display a menu with the New
Object menu option.

Inductive Automation

Track and Trace

54

MES Editor Personnel Menu

Personnel Step 2
After selecting the New Object menu option, the Add New MES Object panel will appear. Select
"Personnel Class" for the type of MES object to add and enter "Unload Operator" for the name. Next, click
the Save button twice.

MES Editor Add New Object

Personnel Step 3
The Unload Operator class node will show in the MES Object Editor. Next, right click the node and select
the Add->Existing Child menu item. As mentioned in the opening paragraph of the Personnel section of
the tutorial, users originate from Ignition users and new personnel are not added here. For this reason we
are adding an existing child.

Inductive Automation

Track and Trace

55

MES Editor Add Existing Child Object

Personnel Step 4
After selecting the Add->Existing Child menu option, the Add Existing MES Object panel will appear.
Select "Person" for the type of MES object to add and select one of the available users and click Save.
Note: if do not see any users, add new Ignition users and assign first and last names.

Inductive Automation

Track and Trace

56

MES Editor Add Person

Add as many users to the Unload Operator class as you wish.

Personnel Step 5
Just like the Unload Operator personnel class added in steps 1 and 2 above, add a new Mix Operator
personnel class.

Personnel Step 6
Using the procedure in steps 3 and 4 above, add the existing users to the Mix Operator personnel class.

2.4.2

Raw Material Unloading

When performing tasks within a production facility, it requires personnel, equipment and material. These
are called resources and have to be defined in the Track and Trace Module. The definition of these
resources can be done using the MES Manager screen, but can come from other sources such as from
a ERP system. This tutorial will step you through defining them using the MES Manager.
To perform our first task of unloading raw materials, we first have to define the equipment used to unload
and store the various raw materials. In addition, the materials also have to be defined.
To get started with defining the unloading, the tutorial will step you through the following:
Inductive Automation

Track and Trace

57

Define Raw Material

Define Unloading Equipment
Define Unloading Tasks
2.4.2.1

Unload Vinegar

This section of the tutorial will step you through defining and tracking vinegar.
2.4.2.1.1 Define Vinegar Unloading

This scenario involves unloading vinegar that will be used for the production of salad dressings.
2.4.2.1.1.1 Define Vinegar Material

To track material as it flows through a production facility, it first has to be defined.

In most manufacturing facilities, there are many products that are produced and when the raw materials
and sub-assemblies are added to the list, there are so many that there is a need to organize them into
small groups. This is done by creating categories of material. A material definition can belong to more
than one category. For example, a definition for salt used in a bakery as a raw material, can be added to
raw materials, salt and dry goods categories.
Putting material definitions into multiple categories is beneficial during analysis and reporting and is
something covered later in this tutorial.

Define Vinegar Step 1

On the MES Manager screen, select the Material tab and right click on the open workspace. This will
display a menu with the New Object menu option.

MES Editor Material Menu

Inductive Automation

Track and Trace

58

Define Vinegar Step 2

After selecting the New Object menu option, the Add New MES Object panel will appear. Select "Material
Class" for the type of MES object to add and enter "Vinegar" for the name. Next, click the Save button
twice.
.

MES Editor Add New Object

Define Vinegar Step 3

The Vinegar class node will show in the MES Object Editor. Next, right click the node and select the Add>New Child menu item.

Inductive Automation

Track and Trace

59

MES Editor Add New Child Object

Define Vinegar Step 4

After selecting the Add->New Child menu option, the Add New MES Object panel will appear. Select
"Material Definition" for the type of MES object to add and enter "Balsamic Vinegar" for the name and click
Save twice.

Inductive Automation

Track and Trace

60

MES Editor New Material

Define Vinegar Step 5

In the same fashion, add a new Red Wine Vinegar material definition as a child to the Vinegar material
class. Now, the MES Object Editor should appear like the image below.

Inductive Automation

Track and Trace

61

MES Editor Vinegar Class

Continue with the next section to organize equipment.

2.4.2.1.1.2 Define Unloading Equipment

To track material as it flows through a production facility, it is important to know the equipment that it is
processed on.
Major equipment that is connected to plant floor control systems, are defined in the designer. This is
because setting up communications to the plant floor control systems, defining tags and much more is
not appropriate for the Ignition client. Also, this type of equipment doesn't change that often and when it
does, requires a control system engineer to design and configure the control system and make any HMI
and SCADA changes. The equipment referenced in this section of the tutorial, falls into the same
category of needing a control system engineer to design and configure, and as a results is configure in
the Ignition designer.
There is general equipment that is not tied to a control system and can represent what is known as rolling
equipment, such as a fork lift, or tooling, such as a die that is used in a press. It can be configured in the
Inductive Automation

Track and Trace

62

MES Manager screen using the Ignition client. This type of equipment is not tied plant floor control
systems and usually will not require a control system engineer to design or configure.
Just like material, organizing equipment into categories into smaller groups is beneficial during analysis
and reporting and is something covered later in this tutorial.

Define Equipment Step 1

Using the same MES Manager screen that was used to define material, select the Equipment tab and
right click on the open workspace. This will display a menu with the New Object menu option.

MES Editor Equipm ent Menu

Define Equipment Step 2

After selecting the New Object menu option, the Add New MES Object panel will appear. Select
"Equipment Class" for the type of MES object to add and enter "Unload Station" for the name. Next, click
the Save button twice.
.

Inductive Automation

Track and Trace

63

MES Editor Add New Object

Define Equipment Step 3

The Unload Station class node will show in the MES Object Editor. Next, right click the node and select
the Add->Existing Child menu item. As mentioned in the opening paragraph of the Equipment section of
the tutorial, major equipment that is connected to plant floor control systems, are defined in the designer.
For this reason we are adding an existing child.

Inductive Automation

Track and Trace

64

MES Editor Add Existing Child Object

Define Equipment Step 4

After selecting the Add->Existing Child menu option, the Add Existing MES Object panel will appear.
Select "Line" for the type of MES object to add and select "Unload Station 1" and click Save.

Inductive Automation

Track and Trace

65

MES Editor Add Equipm ent

Define Equipment Step 5

In the same fashion, add the existing Unload Station 2 line as a child to the Unload Station equipment
class. Now, the MES Object Editor should appear like the image below.

Inductive Automation

Track and Trace

66

MES Editor Unload Station Class

Define Equipment Step 6

Just like the Unload Station equipment class added in steps 1 and 2 above, add a new Vinegar Tanks
equipment class.

Define Equipment Step 7

Using the procedure in steps 3, 4 and 5 above, add the existing Vinegar Tank 1, Vinegar Tank 2 and
Vinegar Tank 3 equipment items to the Vinegar Tanks equipment class. Please note, in order for the
vinegar tanks to appear as an option, the Storage Unit type must be selected.

Inductive Automation

Track and Trace

MES Editor Add Vinegar Tanks

When complete, it should appear as shown in the image below.

Inductive Automation

67

Track and Trace

68

MES Editor Vinegar Tank Class

2.4.2.1.1.3 Define Unload Vinegar Tasks

Now that resources have been defined in the previous tutorial sections, production tasks can be defined.
The resources have to defined first because the production tasks refer to the resources that are required
for them.
In production, tasks can be very complex, but can be broken down into small tasks. These small tasks
are defined in Segments, or more specifically, Process Segments. In the MES Manager, they just appear
as Segments.
Consider what it might take to run production on some processing equipment. The first task might be to
clean the equipment from the prior production run. Then, maybe the lab may need to inspect the line and
sign off before production can start. Next, the equipment might need to heat up and finally production can
start. Each industry, type of equipment, product, company, etc. will have different tasks associated with
Inductive Automation

Track and Trace

69

running production. This is why ISA-95 came up with, and the Ignition MES modules are aligned with, the
concept of segments and made them configurable. It requires a little up front work, but you can have
exactly what is required for your company.
If all you want is a single task to run production, the Ignition Track and Trace Module has a feature that will
simplify the configuration. We will explored this later in this tutorial section.
Defining segments and adding the resources that are required for them will be explored in this tutorial
section.

Segment Step 1
On the MES Manager screen, select the Segments tab and right click on the open workspace. This will
display a menu with the New Object menu option.

MES Editor Segm ent Menu

Segment Step 2
After selecting the New Object menu option, the Add New MES Object panel will appear. The "Process
Segment" option will be the only type of MES object that can be selected. Next, type in Unload Vinegar for
the name and click the Save button only once.

Inductive Automation

Track and Trace

70

The Process Segment, Unload Vinegar configuration panel should be showing as in the image below.

MES Editor Process Segm ent Configuration

Segment Step 3
Next, click on the

icon to add a resource to the process segment and select Material.

Inductive Automation

Track and Trace

71

MES Editor Add Material Resource

Segment Step 4
Continue by entering a name to refer to this material resource by. Set the type of material to the Vinegar
material class. This will cause the operator to be prompted for the specific material being unloaded. If a
specific material definition is selected for the material reference, then the option will be automatically
selected for the operator.
The Use setting is very important. In this case Out is selected because there is not a lot of material in the
system. Instead, this process segment will output a new lot of material that is being received from a
vendor.

Inductive Automation

Track and Trace

72

MES Editor Process Segm ent Material Resource

Scroll down to see all of the settings for the material resource and set to the values list below. When all
setting are entered, click on Save.

Setting Name
Material Name

Value

Description

Vinegar
Type

This is the name to refer to this material resource by. Many process segments
have multiple material resources and this is a unique name displayed to the
operator, shown in analysis and reports, and internally used to reference this
material resource.

Material
Class

This can be set to a Material Class or a Material Definition. By setting this to

Material Class will cause the operator to be prompted for the specific material for
this material resource. If set to a Material Definition, then the selection will be

Material
Reference
Type

Inductive Automation

Track and Trace

73

automatically selected.
MES Object
Name

Vinegar

Depending on the setting of the type, Material Class or Material Definition options
will show. When Process Segments or Operations Segments are inherited from a
Process Segment, then the options that show for the Material Reference setting
will by limited by the parent settings.
For example: If Vinegar Material class is selected for a Process Segment and a
new child Process Segment is created from it, then the options will be limited to
the Vinegar Material Class and any child of it.

Units

Gallons

This appears to the operator, analysis and reports.

Use

Out

This is a very important setting and complete understanding of the possible

options is critical.
Options
In - is used for material feeding into a segment that will be part of the finished
goods.
Out - is used for material feeding out of a segment that is, or will be part of the
finished goods.
Consumable - is used for material feeding into a segment that is not part of the
finished goods.
By-product - is used for material feeding out of a segment that is not part of the
finished goods.

Lot Number
Source

Manual

This determines the source of the lot number.

Options
Manual - prompt the operator for the lot number. This is typically used when
receiving raw materials or entering a lot number generated by an outside system.
Auto - automatically generated lot number. The internal lot number generator will
generate a lot number and assign it automatically for the operator. This option can
also be used if a different lot number format is used or, lot numbers are provided
by another system that is integrated with this system.
In Link - In cases where the lot number of output of a segment will be the same
as the lot number of one of the inputs of the same segment, this setting will tie
the two together. Segments can be configured with multiple material inputs and
outputs and different lot number links can be configured.

Lot Number
Source Link

leave blank

If the Lot Number Source setting is set to In Link, then this is the name of the
material resource to get the lot number from.

Auto Generate
Lot

True

If true, a new lot will be generated for the material output of a segment. This is
typically only done when receiving material that a lot doesn't already exists.

Equipment
Class

This is the type of equipment associated with this material resource. It can be set
to a Equipment Class or a specific piece of equipment.

Lot Equipment
Reference
Type

Inductive Automation

Track and Trace

74

In the case where this material resource is an input to the segment, this will be
the equipment where the material is coming from. This helps establish routes that
exist due to physical machinery. For example if tanks 1 and 2 can only supply
line 1 and tanks 3 and 4 can only supply line 2.
In the case where this material resource is an output from the segment, this will
be the equipment where the material is going to. And just like the case of the
input, routes that exist due to physical machinery can be accommodated.
MES Object
Name

Vinegar
Tanks

Depending on the setting of the type, Equipment Class, Equipment, Line, Line
Cell, Line Cell Group or Storage Unit options will show. When Process Segments
or Operations Segments are inherited from a Process Segment, then the options
that show for the Lot Equipment Reference setting will by limited by the parent
settings.
For example: If Vinegar Tanks class is selected for a Process Segment and a
new child Process Segment is created from it, then the only options will be
limited to the Vinegar Tanks class and any child of it.

Quantity

leave blank

Typically this is left blank, but it can be set to a fixed value that will be constant
every time the segment is used for production.

Quantity Source

Manual

This setting determines the source of the quantity for this material resource.
Options
Auto - Obtain the quantity from the automatic production counters defined for the
associated equipment. The associated equipment may change if the Lot
Equipment Reference setting is set to a Material Class and the specific
equipment is not known until the segment is started for production.
Link - This option allows the quantity to come from an input or output material
resource of this segment. This eliminates the need to type in the quantity multiple
times if they will always be the same as another material resource.
Manual - The operator will be prompted for the quantity. The quantity must be
entered before the segment is ended.
Split - For segments that are splitting a lot into two or more streams, as is the
case of separating good from bad product, this option can be used. It is used by
having two or more material resources, that are segment outputs, linked to the
same material resource. When the segment is ended, the system will ensure that
the sum of the quantities of the linking material resources equal that of the linked
material resources.
Sublots - The quantity will be automatically set based on the number of Material
Sublot items belonging to the Material Lot. If sublots are used, then serial
numbers, or other unique identification number, can be assigned to each sublot
item.
For example, a Material Lot of batteries maybe have 25 individual batteries each
with a serial number and each with their own test results. The quantity of the
Material Lot will match the number of Material Sublot items of the Material Lot.
Or, the number of batteries in the lot.

Inductive Automation

Track and Trace

75

Combine - For segments that are combining two or more lots into one stream, as
is the case of joining goods after tests are done to only a portion of a lot, this
option can be used. It is used by having two or more material resources, that are
segment inputs, linked to the same material resource output. When the segment
is ended, the system will sum of the quantities of the linked material resources to
that of the linking material resources.
Quantity Source
Link

leave blank

This is used when the Quantity Source setting is set to Link, Split or Combine. It
is the name of the material resource of this segment to link to.

Final Lot Status

leave blank

When a segment is started, the status of the Material Lots will be set to Active.
When the segment is ended or a new lot is used for the material resource, the
status will be set to Complete. Optionally, the value of this setting can used
instead of the default Complete. Please note, the Active status while the lot is
active cannot be changed.
This is useful for setting a lot to Hold, In Process or anything that can be used to
filter lots or sublots.

Enable Sublots

False

If this setting is selected, than sublot support will be enabled for the material
resource. If sublots are used, then serial numbers, or other unique identification
number, can be assigned to each sublot item.
For example, a Material Lot of batteries maybe have 25 individual batteries each
with a serial number and each with their own test results.

Segment Step 5
Next, click on the
icon to add a resource to the process segment and select Equipment. This will be
the equipment that the segment can be run at.

Segment Step 6
Continue by entering a name to refer to this equipment resource by. Set the Equipment Reference to the
Unload Station equipment class. This will cause this segment to show as a option when available
segments are shown for Unload Station 1 or Unload Station 2. The other settings can be left blank. When
all setting are entered, click on Save

Inductive Automation

Track and Trace

76

MES Editor Process Segm ent Equipm ent Resource

Segment Step 7
Next, click on the
icon to add a resource to the process segment and select Personnel. This will be
the personnel that can run the segment.

Segment Step 8
Continue by entering a name to refer to this personnel resource by. Set the Personnel Reference to the
Unload Operator personnel class. This will cause users that belong to the Unload Operator class to be
available as options when this segment is run. The other settings can be left blank. When all setting are
entered, click on Save

Inductive Automation

Track and Trace

77

MES Editor Process Segm ent Personnel Resource

Segment Step 9
Click on Save for the final time and a prompt asking if you want to create an operation for this new
process segment. Select Yes and a new Operations Definition and Operations Segment object will be
created automatically. If no other segments need to added to the Operations Definition, then no other
configuration is need to start using the segment.

Inductive Automation

Track and Trace

78

MES Manager Create Operation from Segm ent

The Unload Vinegar operation was automatically created for us in the last step. This will handle our basic
operation of unloading vinegar at the unload station without any further changes.
However, you may want to take a look at in the Operations section in the MES Manager as shown below.
By right clicking on the Unload Vinegar node and selecting Show References, the segment and
associated material and equipment references are shown in the MES Object Manager.

Inductive Automation

Track and Trace

79

Unload Vinegar Operation

2.4.2.1.2 Track Vinegar Unloading

Now that vinegar unloading has been defined, the actual task of unloading vinegar can be done.

Unload Vinegar Step 1

On the Vinegar Unload Station screen, select the Unload Vinegar operation. This operation was created
when we finished defining the process segment to unload vinegar in the previous section of this tutorial.

Inductive Automation

Track and Trace

80

Select Unload Vinegar Operation

When the Unload Vinegar operation is selected, the Operation and Raw Material components are shown.
These components are based on the configuration that was done in the MES Manager and may have
different entry field depending on the configuration of the operation segment.

Unload Vinegar Step 2

Select the person that is unloading the vinegar.

Unload Vinegar Step 3

Select the material that is being unloaded. For this tutorial, select balsamic vinegar. Remember that we
used the Vinegar material class when defining the Unload Vinegar operation. We also added Balsamic
Vinegar and Red Wine Vinegar material definitions to the Vinegar material class. As a result, those are the
two options that are available.

Unload Vinegar Step 4

Select the location where the material will be stored. Remember that we used the Vinegar Tanks material
class when defining the Unload Vinegar operation. We also added Vinegar Tank 1, 2 and 3 storage units
to the Vinegar Tanks equipment class. As a result, those are the three options that are available.
Inductive Automation

Track and Trace

81

Unload Vinegar Step 5

Enter a lot number for the raw material. This component is shown because the Lot Number Source
setting was set to Manual for the Raw Material material resource of the Unload Vinegar operation.

Unload Vinegar Step 6

Now that the required information has been entered to begin the operation, click the Start button.
Note, the Quantity is not required to start because it might not be known until the truck is fully unloaded or
the tank the product is being stored in had to be changed.
Also, because the Track and Trace Module installs into the Ignition platform, all of the HMI and SCADA
functionality that comes with Ignition can be used. In this case, the actual process started at the same
time as the tracking information was records. This is optional, but is a big benefit to reduce reduce errors
in tracking production.
At this time, you can click on the Show Inventory button for the selected Vinegar Tank, it will show the lot
currently being processed.

Active Lot Inventory

Unload Vinegar Step 7

To end the Unload Vinegar operation, first enter a Quantity and then click the Stop button.
Inductive Automation

Track and Trace

82

Note, the operation cannot be ended until the Quantity is entered. This helps reduce errors in tracking
production.
2.4.2.1.3 Unload Vinegar Trace

Now that some vinegar has been unloaded, it can be viewed on the Trace Graph.

Unload Vinegar Trace Step 1

On the Trace Graph screen, begin typing the lot number used in the Unload Vinegar section of this
tutorial.

Select Vinegar Raw Material Lot Num ber

Unload Vinegar Trace Step 2

Although short, the flow of unloading vinegar is shown in visual form. More interesting information will
appear in the Trace Graph as we continue the tutorial.

Inductive Automation

Track and Trace

83

Unload Vinegar Trace

To see the table form, which is typical for a track and trace system, click on the Table tab.

Unload Vinegar Trace Step 3

Right click on the Unload Station 1 and select the Show Details menu item. This shows all the trace
details for this occurrence of Unloading Vinegar. Notice the exact timing and other details of the operation.
This can be used to query additional types of information that resides in the Ignition system or outside.

Inductive Automation

Track and Trace

84

Unload Vinegar Trace Details

2.4.2.2

Unload Oil

This section of the tutorial will step you through defining and tracking oil.
2.4.2.2.1 Define Oil Unloading

Using the same steps as defined for Unload Vinegar section, we will unload oil. This time we will
abbreviate it and you may have to refer back to the Unload Vinegar section of this tutorial for reference.

Define Unload Oil Step 1

Define the oil material definitions by creating a Oil material class then adding two new children to it called
Olive Oil and Vegetable Oil.

Define Unload Oil Step 2

Add a new Oil Tanks equipment class and add the existing oil tank storage units Oil Tank 1, 2 and 3.
When complete, it should appear as shown in the image below.

Inductive Automation

Track and Trace

MES Editor Oil Tank Class

Define Unload Oil Step 3

Add a new Unload Oil segment and add a material resource with the following settings:

Setting Name

Value

Material Name

Raw Material

Material Reference

Material Class
Oil

Units
Inductive Automation

Gallons

85

Track and Trace

Use

Out

Lot Number Source

Manual

Auto Generate Lot

True

Lot Equipment
Reference

Equipment Class

86

Oil Tanks
Quantity Source

Manual

Add a equipment resource with the following settings:

Setting Name
Equipment Name

Value
Unload Station

Equipment Reference Line

Unload Station 2

Add a personnel resource with the following settings:

Setting Name

Value

Personnel Name

Unload Operator

Personnel Reference

Personnel Class
Unload Operator

Save and when prompted "Create operation for this process segment?", select Yes.
2.4.2.2.2 Track Oil Unloading

Now that oil unloading has been defined, the actual task of unloading oil can be done.

Unload Oil Step 1

On the Oil Unload Station screen, select the Unload Oil operation.

Unload Oil Step 2

Select the person that is unloading the oil.

Unload Oil Step 3

Select the material that is being unload. For this tutorial, select olive oil.
Inductive Automation

Track and Trace

87

Unload Oil Step 4

Select the location where the material will be stored.

Unload Oil Step 5

Enter a lot number for the raw material.

Unload Oil Step 6

Now that the required information has been entered to begin the operation, click the Start button.
Note, the Quantity is not required to start because it might not be known until the truck is fully unloaded or
the tank the product is being stored in had to be changed.

Unload Oil Step 7

To end the Unload Oil operation, first enter a Quantity and then click the Stop button.
Note, the operation cannot be ended until the Quantity is entered.

2.4.3

Mixing Dressing

Now that we have some raw material to make dressing with, this section will step through defining and
making Balsamic dressing.
2.4.3.1

Defining Mixing

We currently do not have a material definition for Balsamic Dressing, the mix tanks or tanks to store the
dressing in after it has been mixed.
The Unload Vinegar section of the tutorial is very detailed, but this section will use the abbreviated version.
Refer to the Unload Vinegar section if a reference is needed.

Define Mixing Step 1

Define the balsamic dressing material definition by creating a Dressing material class then adding a new
child to it called Balsamic Dressing.

Define Mixing Step 2

Add a new Mix Station equipment class and add the existing lines Mix Station 1 and 2.

Define Mixing Step 3

Add a new Holding Tanks equipment class and add the existing storage units Holding Tank 1 and 2.

Define Mixing Step 4

Add a new Mix Balsamic Dressing segment and add a material resources for the ingredients used to
make balsamic dressing with the following settings:
Inductive Automation

Track and Trace

Setting
Name

88

Value

Material Name

Vinegar

Material
Reference

Material Definition
Balsamic Vinegar

Units

Gallons

Use

In

Lot Number
Source

Auto

Auto Generate
Lot

False

Lot Equipment
Reference

Equipment Class
Vinegar Tanks

Quantity
Source

Manual

Quantity
Source Link

Dressing

Setting
Name

Value

Material Name

Oil

Material
Reference

Material Definition
Olive Oil

Units

Gallons

Use

In

Lot Number
Source

Auto

Auto Generate
Lot

False

Lot Equipment
Reference

Equipment Class
Oil Tanks

Quantity
Source

Manual

Quantity

Dressing
Inductive Automation

Track and Trace

89

Source Link

Now add a material resources for the mixed balsamic dressing being made with the following settings:

Setting
Name

Value

Material Name

Dressing

Material
Reference

Material Definition
Balsamic Dressing

Units

Gallons

Use

Out

Lot Number
Source

Auto

Auto Generate
Lot

True

Lot Equipment
Reference

Equipment Class
Holding Tanks

Quantity
Source

Combine

Quantity
Source Link

Dressing

Notice that the Quantity Source property is set to Combine and the Quantity Source Link is set to Dressing. Also, the
a Quantity Source Link properties in the Vinegar and Oil material resource definitions above as also set to Dressing.
This causes the quantity for the balsamic dressing to be the sum of the vinegar and oil quantities.

Add a equipment resource with the following settings:

Setting
Name

Value

Equipment
Name

Mix Station

Equipment
Reference

Equipment Class
Mix Station

Notice that a Equipment class is defined instead of a specific equipment item as done previously. This allows this
Inductive Automation

Track and Trace

90

operation to be done at either Mix Station 1 or 2 because the both are included in the Mix Station equipment class.

Add a personnel resource with the following settings:

Setting
Name

Value

Personnel
Name

Mix Operator

Personnel
Reference

Personnel Class
Mix Operator

Save and when prompted "Create operation for this process segment?", select Yes.
2.4.3.2

Tracking Mixing

Now that Mix Balsamic Dressing has been defined, the actual task of mixing balsamic dressing can be
done.

Mix Balsamic Dressing Step 1

On the Mixing Station 1 or Mixing Station 2 screen, select the Mix Balsamic Dressing operation.

Mix Balsamic Dressing Step 2

Select the person that is mixing the dressing.

Mix Balsamic Dressing Step 3

Select the balsamic vinegar lot that is being used. Use one that was previously unloaded in this tutorial.

Mix Balsamic Dressing Step 4

Select the olive oil lot that is being used. Use one that was previously unloaded in this tutorial.

Mix Balsamic Dressing Step 5

Select the destination where the balsamic dressing will be stored.

Mix Balsamic Dressing Step 6

Now that the required information has been entered to begin the operation, click the Begin button.
Note, the Quantities are not required to start because it might not be known until the mixing is complete.

Mix Balsamic Dressing Step 7

Inductive Automation

Track and Trace

91

To end the Mix Balsamic Dressing operation, first enter a Quantities and then click the End button.
Note, the operation cannot be ended until the Quantities are entered.

2.4.4

Mix Dressing Trace

Now that some balsamic dressing has been mixed, it can be viewed on the Trace Graph.

PLC Driven Trace Step 1

On the Trace Graph screen, begin typing in "000" which is the beginning of the lot number that was
automatically generated during the mixing operation. Select the full lot number.

Select Balsam ic Dressing Material Lot Num ber

PLC Driven Trace Step 2

The flow from unloading through mixing is shown.

Mix Dressing Trace

Inductive Automation

Track and Trace

92

To see the table form, which is typical for a track and trace system, click on the Table tab.

Next Steps
If you wish, continue by adding resources and operations definition to bottle the dressing or add more
ingredients to the dressing.

Inductive Automation

Track and Trace

2.5

93

PLC Driven Tracking Tutorial

The following tutorial steps through configuring PLC driven tracking of production. Defining production is
the important step that should not be rushed and if not fully thought throw, will cause unexpected trace
results and cause production staff difficulty when handling unusual or unexpected production situations.
This tutorial requires the Track and Trace demo project. Please follow the demo installation instructions
before continuing.

2.5.1

Define Process

This scenario involves testing power supplies and only involves one task (segment). More segments can
be link together but to keep this tutorial from being a book of it's own, it demonstrates only one task.
2.5.1.1

Define Material

To track power supplies as it flows through the testing phase, it first has to be defined as material.
In most manufacturing facilities, there are many products that are produced and when the raw materials
and sub-assemblies are added to the list, there are so many that there is a need to organize them into
small groups. This is done by creating categories of material. A material definition can belong to more
than one category. For example, a definition for salt used in a bakery as a raw material, can be added to
raw materials, salt and dry goods categories.
Putting material definitions into multiple categories is beneficial during analysis and reporting and is
something covered later in this tutorial.

Define Material Step 1

On the MES Manager screen, select the Material tab and right click on the open workspace. This will
display a menu with the New Object menu option.

Inductive Automation

Track and Trace

94

MES Editor Material Menu

Define Material Step 2

After selecting the New Object menu option, the Add New MES Object panel will appear. Select "Material
Class" for the type of MES object to add and enter "Power Supply Assemblies" for the name. Next, click
the Save button twice.
.

Inductive Automation

Track and Trace

95

MES Editor Add New Object

Define Material Step 3

The Power Supply Assemblies class node will show in the MES Object Editor. Next, right click the node
and select the Add->New Child menu item.

Inductive Automation

Track and Trace

96

MES Editor Add New Child Object

Define Material Step 4

After selecting the Add->New Child menu option, the Add New MES Object panel will appear. Select
"Material Definition" for the type of MES object to add and enter "Untested Power Supply" for the name
and click Save twice.

Inductive Automation

Track and Trace

97

MES Editor New Material

Define Material Step 5

In the same fashion, add a new "Tested Power Supply" material definition as a child to the Power Supply
Assemblies material class. Now, the MES Object Editor should appear like the image below.

Inductive Automation

Track and Trace

98

MES Editor Pow er Supply Assem blies Class

Continue with the next section to define the required task.

2.5.1.2

Define Tasks

Defining segments and adding the resources that are required for them will be explored in this tutorial
section. To keep this tutorial short and focus only on the steps needed to demonstrate tracking based on
values in a PLC, it only contains one task of testing power supplies. It can be expanded to include
receiving power supply units and multiple assembly or testing manufacturing steps.

Test Power Supply Segment Step 1

On the MES Manager screen, select the Segments tab and right click on the open workspace. This will
display a menu with the New Object menu option.

Inductive Automation

Track and Trace

99

MES Editor Segm ent Menu

Test Power Supply Segment Step 2

After selecting the New Object menu option, the Add New MES Object panel will appear. The "Process
Segment" option will be the only type of MES object that can be selected. Next, type in Test PS for the
name and click the Save button only once.
The Process Segment, Test PS configuration panel should be showing as in the image below.

Inductive Automation

Track and Trace

100

MES Editor Process Segm ent Configuration

Test Power Supply Segment Step 3

Next, click on the

icon to add a resource to the process segment and select Material.

Inductive Automation

Track and Trace

101

MES Editor Add Material Resource

Test Power Supply Segment Step 4

Continue by entering a name to refer to this material resource by. Set the type of material to the Tested
Power Supply material definition. This will automatically be selected for the material when power supplies
are automatically tested.
The Use setting is very important. In this case, Out is selected because there is not a lot for this material
in the system. Instead, this process segment will output a new lot of material for the power supplies being
tested.

Inductive Automation

Track and Trace

102

MES Editor Process Segm ent Material Resource

Scroll down to see all of the settings for the material resource and set to the values list below. When all
setting are entered, click on Save.

Setting Name
Material Name

Value

Description

Tested

This is the name to refer to this material resource by. Many process segments
have multiple material resources and this is a unique name displayed to the
operator, shown in analysis and reports, and internally used to reference this
material resource.

Type

Material
Definition

This can be set to a Material Class or a Material Definition. By setting to a

Material Definition, then the selection will be automatically selected.

MES Object
Name

Tested
Power
Supply

Depending on the setting of the type, Material Class or Material Definition options
will show. When Process Segments or Operations Segments are inherited from a
Process Segment, then the options that show for the Material Reference setting
will by limited by the parent settings.

Material
Reference

Inductive Automation

Track and Trace

103

Units

Each

This appears to the operator, analysis and reports.

Use

Out

This is a very important setting and complete understanding of the possible

options is critical.
Options
In - is used for material feeding into a segment that will be part of the finished
goods.
Out - is used for material feeding out of a segment that is, or will be part of the
finished goods.
Consumable - is used for material feeding into a segment that is not part of the
finished goods.
By-product - is used for material feeding out of a segment that is not part of the
finished goods.

Lot Number
Source

Manual

This determines the source of the lot number. In this tutorial, our script that is run
when the values in the PLC change, will set the lot number.
Options
Manual - prompt the operator for the lot number. This is typically used when
receiving raw materials or entering a lot number generated by an outside system.
Auto - automatically generated lot number. The internal lot number generator will
generate a lot number and assign it automatically for the operator. This option can
also be used if a different lot number format is used or, lot numbers are provided
by another system that is integrated with this system.
In Link - In cases where the lot number of output of a segment will be the same
as the lot number of one of the inputs of the same segment, this setting will tie
the two together. Segments can be configured with multiple material inputs and
outputs and different lot number links can be configured.

Lot Number
Source Link

leave blank

If the Lot Number Source setting is set to In Link, then this is the name of the
material resource to get the lot number from.

Auto Generate
Lot

True

If true, a new lot will be generated for the material output of a segment. This is
typically only done when receiving material that a lot doesn't already exists.

Lot Equipment
Reference
Type

Storage Unit This is the type of equipment associated with this material resource. It can be set
to a Equipment Class or a specific piece of equipment.
In the case where this material resource is an output to the segment and this is
where the power supplies will be placed after testing.

MES Object
Name
Quantity

Inductive Automation

RM Bay 2
leave blank

Typically this is left blank, but it can be set to a fixed value that will be constant
every time the segment is used for production.

Track and Trace

Quantity Source

Sublots

104

This setting determines the source of the quantity for this material resource.
Options
Auto - Obtain the quantity from the automatic production counters defined for the
associated equipment. The associated equipment may change if the Lot
Equipment Reference setting is set to a Material Class and the specific
equipment is not known until the segment is started for production.
Link - This option allows the quantity to come from an input or output material
resource of this segment. This eliminates the need to type in the quantity multiple
times if they will always be the same as another material resource.
Manual - The operator will be prompted for the quantity. The quantity must be
entered before the segment is ended.
Split - For segments that are splitting a lot into two or more streams, as is the
case of separating good from bad product, this option can be used. It is used by
having two or more material resources, that are segment outputs, linked to the
same material resource. When the segment is ended, the system will ensure that
the sum of the quantities of the linking material resources equal that of the linked
material resources.
Sublots - The quantity will be automatically set based on the number of Material
Sublot items belonging to the Material Lot. If sublots are used, then serial
numbers, or other unique identification number, can be assigned to each sublot
item.
For example, a Material Lot of batteries maybe have 25 individual batteries each
with a serial number and each with their own test results. The quantity of the
Material Lot will match the number of Material Sublot items of the Material Lot.
Or, the number of batteries in the lot.
Combine - For segments that are combining two or more lots into one stream, as
is the case of joining goods after tests are done to only a portion of a lot, this
option can be used. It is used by having two or more material resources, that are
segment inputs, linked to the same material resource output. When the segment
is ended, the system will sum of the quantities of the linked material resources to
that of the linking material resources.

Quantity Source
Link

leave blank

This is used when the Quantity Source setting is set to Link, Split or Combine. It
is the name of the material resource of this segment to link to.

Final Lot Status

leave blank

When a segment is started, the status of the Material Lots will be set to Active.
When the segment is ended or a new lot is used for the material resource, the
status will be set to Complete. Optionally, the value of this setting can used
instead of the default Complete. Please note, the Active status while the lot is
active cannot be changed.
This is useful for setting a lot to Hold, In Process or anything that can be used to
filter lots or sublots.

Enable Sublots

True

If this setting is selected, than sublot support will be enabled for the material
resource. If sublots are used, then serial numbers, or other unique identification
number, can be assigned to each sublot item.

Inductive Automation

Track and Trace

105

In this tutorial, a Material Lot of power supplies has 4 units being tested. Each
with a serial number and each with their own test results.

Test Power Supply Segment Step 5

Next, click on the
icon to add a resource to the process segment and select Equipment. This will be
the equipment that the segment can be run at.

Test Power Supply Segment Step 6

Continue by entering a name to refer to this equipment resource by. Set the Equipment Reference to the
PS Assembly line. This will cause this segment run at the PS Assembly equipment location. The other
settings can be left blank. When all setting are entered, click on Save

MES Editor Process Segm ent Equipm ent Resource

Inductive Automation

Track and Trace

106

Test Power Supply Segment Step 7

Click on Save for the final time and a prompt asking if you want to create an operation for this new
process segment. Select Yes and a new Operations Definition and Operations Segment object will be
created automatically. If no other segments need to added to the Operations Definition, then no other
configuration is need to start using the segment.

MES Manager Create Operation from Segm ent

2.5.2

Define Tags

Define Tags Step 1

Create memory or OPC tags as shown below. If you don't have a PLC to read them from, use memory
tags. Then, testing can be done by changing the tag values in the designer.

Inductive Automation

Track and Trace

107

PLC Driven Tag Layout

The intended functionality is when the tag named Active is set to true, it will start tracking 4 items (material
sublots) with the serial numbers defined by the SN1, SN2, SN3 and SN4 tag values. When the Active tag
is set to false, the tracking will stop.
If these tags are OPC tags that are driven by a PLC, then no human intervention on the Ignition system
will have to be done and it will follow the state of the station via the PLC.

2.5.3

Add Tag Change Event

Tag Change Event Step 1

Create a Tag Change event by selecting the Project->Event Scripts (Gateway) from the main menu.
Next, select the Tag Change tab and add a new event and rename it to PLCDrivenTracking.
Select the "AutoTrack/Station 1/Active" tag to the Tag Path(s) list.

Inductive Automation

Track and Trace

108

Tag Change Event

Tag Change Event Step 2

Enter script to run when the Active tag value changes by clicking on the Script tab and copy and paste the
following script:
from org.apache.log4j import Logger
log = Logger.getLogger('AutoTrack')
#Don't do anything if Ignition just started
if initialChange == False:
#The equipment path is to identify the equipment to track production at.
equipPath = 'Dressings Inc\California\Assembly\PS Assembly'
#The operation to use
operationName = 'Test PS'
#Read the active tag which can come from a PLC.
activeTag = system.tag.read('AutoTrack/Station 1/Active')
#Don't make any changes if the quality is bad
if activeTag.quality.isGood():
log.info("Tag change detected")
if activeTag.value == True:
log.info("Tag is True")
#Active is true, so begin tracking
lotNumber = system.tag.read('AutoTrack/Station 1/LotNumber')
#Read the sublot (item) serial numbers from tags
sn1Tag = system.tag.read('AutoTrack/Station 1/SN 1')
sn2Tag = system.tag.read('AutoTrack/Station 1/SN 2')
sn3Tag = system.tag.read('AutoTrack/Station 1/SN 3')
sn4Tag = system.tag.read('AutoTrack/Station 1/SN 4')

Inductive Automation

Track and Trace

109

#First a Operation must be started

#load the Operations Definition MES object to base the tracking on.
operDef = system.mes.loadMESObject(operationName, 'OperationsDefinition')
#Create a new Operations Response based on the loaded Operations Definition
operResp = system.mes.createOperation(operDef)
#Begin the operation
system.mes.beginOperation(equipPath, operResp)

#Create a new response segment.

#This method will just use the segment that has the same name as the operations r
#or if there is only one operations segment for the associated operations definit
respSeg = system.mes.createSegment(operResp, '', equipPath, True)

#This shows how to get lot property information by name and update values for it.
#In this case, the manual lot number is being set.
outLotProp = respSeg.getComplexProperty('Lot', 'Tested')
outLotProp.setValue('LotManualLotNo', lotNumber.value)
log.info("Beginning Segment")
#Begin the response segment
system.mes.beginSegment(respSeg)
log.info("Adding sublots")

#Now that the operation and segment have began, add the sublots.
respSeg.addSublots('Tested', sn1Tag.value, sn2Tag.value, sn3Tag.value, sn4Tag.val
else:
log.info("Tag is False")
#Active is false, so end tracking
#Get the currently running operations response running at the equipment
#specified by the equipment path.
operResp = system.mes.getCurrentOperation(equipPath)
#Do a quick check to make sure it was not stopped somewhere else.
if operResp != None:

#End the operations reponse which will cause the response segment to be en
system.mes.endOperation(equipPath, operResp)

Make sure the tab indents match what is shown above. The code is documented and will describe the
steps needed to begin and end tracking from script.
Note: Future versions of Ignition will support Sequential Function Charts (SFC) that will allow functionality
without all the script.

2.5.4

Simulate Tracking

Simulate Tracking Step 1

You you have a PLC available and want to set it up to test with, map the tags to the OPC item paths. If
not, a simulation can be done by simply changing tag values in the Ignition SQL Tag Browser.
Set the SN 1, SN 2, SN 3, SN 4, LotNumber tags to serial numbers and a lot number to use. Next, check
the Active tag which will cause tracking to begin. After a few seconds you can uncheck the Active tag
which will cause the tracking to end.

Inductive Automation

Track and Trace

110

PLC Driven Tag Layout

2.5.5

PLC Driven Trace

Now that some production information that automatically tracked it can be viewed on the Trace Graph.

PLC Driven Trace Step 1

On the Trace Graph screen, and set the Mode selection to Sublot. Also make sure the To Date Time
setting is past today. This will cause the serial numbers that were tracked to appear in the selector as
shown below.

Select Sublot (Serial) Num ber

PLC Driven Trace Step 2

Although short, the flow of testing power supplies is shown in visual form.

Inductive Automation

Track and Trace

111

Test Pow er Supplies Trace

The Sublot Match text that appears on the right hand node indicates that the serial number that is selected
is part of the lot.
To see the table form, which is typical for a track and trace system, click on the Table tab.
A lot more data can be shown that was collected during the testing of the power supplies, but it is beyond
the scope of this tutorial. It can be accomplished by querying data stored in Ignition or other systems
using the trace data. It can be by serial number, date range, equipment, personnel, and more.

Inductive Automation

Track and Trace

2.6

112

Component Reference

This section is a reference for all the components that come with the Track and Trace Module.

2.6.1

MES Object Editor

Description
A component that is added to Ignition windows to manage MES objects. In addition to using this
component to manager MES objects, script can also be used. See MES Object Handling scripts for more
information.
The MES Object Editor component is used to edit resources, segments and operations. See ISA-95 for
more information about the various MES objects. Equipment can be put into categories by first adding a
new equipment category and then adding equipment to it. The same can be done for material and
personnel. See the User Tutorial for more details of how to interact with this component.
Below is the node view showing the selected primary node and any child nodes.

MES Object Editor Node View Node

Below is the property table view used to add, remove and edit values of core, custom, resource
references or segment references.

Inductive Automation

Track and Trace

113

MES Object Editor Property Table View

Additionally, the MES Object Editor component is used to define segments and operations. In much the
same manor as equipment, material and personnel are defined and categorized, segments and
operations are managed.
The MES Object Editor must be used in conjunction with the MES Object Selector component. There are
many if not thousands of material, equipment, personnel, segment and operations that can be managed
in this component and in order to know which one to show and focus on, it uses the MES Object Selector
component. No binding is required for the two to work together. Behind the scenes, the MES Object Editor
finds the MES Object Selector and the two will communicate.
Important
For the MES Object Editor component to find the MES Object Selector, it must be in the same container
on the window. It is okay to be in a container, they just both have to be in the same container or root
container.
When a new class, segment or operation is added, the MES Object Selector selection will change to
reflect the newly added MES object. This doesn't happening when adding a new child in order to keep the
primary MES object shown.
Properties
This component has standard Ignition properties with the addition of the following properties:
Enable Show Deleted Properties

Set to true to show deleted properties in the property table.

Scripting name
Data Type

Inductive Automation

enableShowDeletedPropert
ies
Boolean

Track and Trace

Enable Auto Sizing

Set to True to enable resizing in node view mode when the right
mouse button is clicked. When a menu is shown when the right
mouse button is clicked, it is better to set this property to False.
See the autoFit() function of this component that can be called
from a button.
Scripting name
Data Type

Show Deleted Objects

buttonFont
Font

Set to the font to use for the category headers of the property editor
table
Scripting name
Data Type

Close Button Font

readOnly
Boolean

Set to the font to use in buttons of the MES object configuration

panels of the MES Object Editor.
Scripting name
Data Type

Category Font

edgeColor
Color

Set to True to disable editing of everything.

Scripting name
Data Type

Button Font

showDeletedObjects
Boolean

The color to use when displaying edges. Edge in graphing terms

is the line between the nodes.
Scripting name
Data Type

Read Only

enableAutoSizing
Boolean

Set to true to show deleted objects. In the Ignition MES system,

MES object are not deleted but instead are disabled. This is done
to maintain historical integrity. Once a MES object had been
disabled, they can be shown in this component by setting this
property to True. From there, MES objects can be changed from
disabled to enabled state to restore their use.
Scripting name
Data Type

Edge Color

114

categoryFont
Font

Set to the font to use for the close button. The close button is used to
back out of the MES object configuration panels and return to the
node display.
Scripting name
Data Type

closeButtonFont
Font

Inductive Automation

Track and Trace

Description Area Font

Set to the font to use when displaying property descriptions.

Scripting name
Data Type

Miscellaneous Font

menuAddNewIconPath
String

Set to the Ignition image path of the icon to use for the edit menu
items. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Inductive Automation

editorTitleFont
Font

Set to the Ignition image path of the icon to use for the add new menu
item. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Menu Edit Icon Path

tabFont
Font

Set to the font to use for the editor title. The editor title is shown when
configuration panels are displayed and include information about
what is being edited.
Scripting name
Data Type

Menu Add New Icon Path

propertyFont
Font

Set to the font to use for tab page options.

Scripting name
Data Type

Editor Title Font

popupMessageFont
Font

Set to the font to for properties displayed in the property table.

Scripting name
Data Type

Tab Font

popupOptionsFont
Font

Set to the font to use when displaying popup messages.

Scripting name
Data Type

Property Font

miscellaneousFont
Font

Set to the font to use for popup options. The popup options are
displayed when adding new custom, material, equipment, personnel
or segments from the property table.
Scripting name
Data Type

Popup Message Font

descriptionAreaFont
Font

Set to the font to use for miscellaneous text.

Scripting name
Data Type

Popup Options Font

115

menuEditIconPath
String

Track and Trace

Menu Delete Icon Path

Set to the Ignition image path of the icon to use for delete menu items.
If this property is left blank, the default icon will be used.
Scripting name
Data Type

Menu Show References Icon

Path

Data Type

titleTextColor
Color

Set the color to use for the close button text. The close button is used
to back out of the MES object configuration panels and return to the
node display.
Scripting name
Data Type

Category Background Color

menuStopShowReferencesIcon
Path
String

Set the color to use for the title text. The editor title is shown when
configuration panels are displayed and include information about what
is being edited.
Scripting name
Data Type

Close Button Color

menuShowReferencesIconPath
String

Set to the Ignition image path of the icon to use for the stop showing
references menu item. If this property is left blank, the default icon will
be used.
Scripting name

Title Text Color

menuDeleteIconPath
String

Set to the Ignition image path of the icon to use for the show
references menu item. If this property is left blank, the default icon will
be used.
Scripting name
Data Type

Menu Stop Show References

Icon Path

116

closeButtonColor
Color

Set the background color to use for displaying categories in the

property table.
Scripting name
Data Type

categoryBackgroundColor
Color

Inductive Automation

Track and Trace

Node

117

A dataset containing node configuration used when displaying nodes in the MES Object
C component. The colors of the different parts of a node can be changed using this
Editors
o
property.
This provides a visual deference of the different types of MES objects.
n
This fproperty is a dataset allowing any number of node configurations keyed by first the
namei of the node and if a match is not found, then it will look for match by node type. If no
g
matches
are found, the entry named Default will be used.
u
r
a
t
i
o
n
Node Parts

Scripting name
Data Type

nodeConfiguration
Dataset

The Dataset must have the following columns that are reference by column name when
building node definitions:
Name

Stri Name which can be the node name or node type. It can contain wildcard
ng
characters including * or ?. The * character can be any characters and
the ? character represents any single character.
The valid node types match the type of the MES object and include:
MaterialClass
MaterialDef
EquipmentClass
Equipment
PersonnelClass
Person
ProcessSegment
OperationsDefinition
OperationsSegment

Examples:
Unloading*
MaterialClass

HeaderBackgro Colo The color to use for the header background.

undColor
r
HeaderFontColo Colo The color to use for the header text.
r
r
BodyBackgroun Colo The color to use for the background of the body.
dColor
r
BodyFontColor Colo The color to use for the body text.

r
Inductive Automation
BorderColor

Colo The color to use for the border.

r

Track and Trace

User Menu

118

A dataset containing user menu item to show in popup menus for the different nodes
ofI the MES Object Editor component.
t
e
m
s

Scripting name
Data Type

userMenuItems
Dataset

The Dataset must have the following columns that are reference by column number when
building the user menus:
0

String

Node type that determines which popup menu the user

menu item will appear in. Valid options are:
The valid node types match the type of the MES object and
include:
MaterialClass
MaterialDef
EquipmentClass
Equipment
PersonnelClass
Person
ProcessSegment
OperationsDefinition
OperationsSegment

String

Text to appear for the user menu item. This is also used to
identify the user menu item that was clicked in the
userMenuItemClicked event.

String

Ignition image path of the icon to display in the user menu

item.

Events
meunu - userMenuItemClicked
Event Properties
event.getMenuItemName()

Is fired whenever a user menu item is selected.

Returns the name of the user menu item that triggered the event.
Data Type
String

event.getNodeName()

Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

Inductive Automation

Track and Trace

selectNode - nodeClicked
Event Properties
event.getNodeName()

119

Is fired whenever a user clicks the mouse button on a node.

Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

selectNode - nodeEntered
Event Properties
event.getNodeName()

Is fired whenever the mouse is moved over a node.

Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

selectNode - nodeExited
Event Properties
event.getNodeName()

Is fired whenever the mouse is moved off of a node.

Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

Methods
autoFix()

Automatically zoom and pan the node display to show the current nodes shown in the MES Object Editor.
parameters
none

Inductive Automation

Track and Trace

returns

120

nothing

Sample script to zoom and pan to fit the currently displayed node to fit in the editor.
Script from a button action event on the window
event.source.parent.getComponent('MES Object Editor').autoFit()

2.6.2

MES Object Selector

Description
A component that is added to Ignition windows to allow auto complete selection of MES objects. It
contains many properties to filter the type and name of the MES object to include in the list. The auto
complete feature will include only appropriate MES object names that start with what the user has typed.
This is very useful so scrolling of large lists does not have to be done and the full object name does not
have to be typed in.

Closed MES Object Selector

Open MES Object Selector

Properties
This component has standard Ignition properties with the addition of the following properties:
Include Equipment
Class Objects

If true, MES Equipment Class objects will be included in the options.

Scripting name
Data Type

Include Equipment
Objects

includeEquipmentClassObjects

Boolean

If true, MES Equipment objects will be included in the options. This does not
include the equipment items from the production model which are separate
properties of this component.
includeEquipmentObjects
Scripting name
Data Type
Boolean

Inductive Automation

Track and Trace

121

Include Material Class If true, MES Material Class objects will be included in the options.
Objects

Scripting name
Data Type

includeMaterialClassObjects

Boolean

Include Material Def If true, MES Material Def objects will be included in the options.
Objects

Scripting name
Data Type

includeMaterialDefObjects

Boolean

Include MES Area

Objects

If true, MES Area objects will be included in the options. MES Areas are defined
in the production model.
includeMESAreaObjects
Scripting name
Data Type
Boolean

Include MES
Enterprise Objects

If true, MES Enterprise objects will be included in the options. The MES
Enterprise object is defined in the production model.
includeMESEnterpriseObjects
Scripting name
Data Type
Boolean

Include MES Line

Objects

If true, MES Line objects will be included in the options. MES Lines are defined in
the production model.
includeMESLineObjects
Scripting name
Data Type
Boolean

Include MES Line

Cell Objects

If true, MES Line Cell objects will be included in the options. MES Line Cells are
defined in the production model.
includeMESLineCellObjects
Scripting name
Data Type
Boolean

Include MES Line

Cell Group Objects

If true, MES Line Cell Group objects will be included in the options. MES Line
Cell Groups are defined in the production model.
includeMESLineCellGroupObjects
Scripting name
Data Type
Boolean

Include MES Site

Objects

If true, MES Sites objects will be included in the options. MES Sites are defined
in the production model.
includeMESSiteObjects
Scripting name
Data Type
Boolean

Inductive Automation

Track and Trace

122

Include MES Storage If true, MES Storage Unit objects will be included in the options. MES Storage
Unit Objects
Units are defined in the production model.

Scripting name
Data Type

includeMESStorageUnitObjects

Boolean

Include MES Storage If true, MES Storage Zone objects will be included in the options. MES Storage
Zone Objects
Zones are defined in the production model.

Scripting name
Data Type
Include Operations
Definition Objects

Boolean

includeOperationsRequestObjects

Boolean

If true, MES Operations Response objects will be included in the options.

Scripting name
Data Type

Include Operations
Segment Objects

includeOperationsDefinitionObjects

If true, MES Operations Request objects will be included in the options.

Scripting name
Data Type

Include Operations
Response Objects

Boolean

If true, MES Operations Definition objects will be included in the options.

Scripting name
Data Type

Include Operations
Request Objects

includeMESStorageZoneObjects

includeOperationsResponseObjects

Boolean

If true, MES Operations Segment objects will be included in the options.

Scripting name
Data Type

includeOperationsSegmentObjects

Boolean

Include Person
Objects

If true, MES Person objects will be included in the options. MES Person objects
are based on the Ignition users that have first and last names set.
includePersonObjects
Scripting name
Data Type
Boolean

Include Personnel
Objects

If true, MES Personnel Class objects will be included in the options.

Scripting name
Data Type

includePersonnelObjects

Boolean

Inductive Automation

Track and Trace

Include Process
Segment Objects

If true, MES Process Segment objects will be included in the options.

Scripting name
Data Type

Include Request
Segment Objects

includeProcessSegmentObjects

Boolean

If true, MES Request Segment objects will be included in the options.

Scripting name
Data Type

Include Response
Segment Objects

123

includeRequestSegmentObjects

Boolean

If true, MES Response Segment objects will be included in the options.

Scripting name
Data Type

includeResponseSegmentObjects

Boolean

Custom Property
The options can be limited to only include MES object that contain a custom
Nam property by name. It can contain wildcard characters including * or ?. The *
e
character can be any characters and the ? character represents any single
Filte character.
r

Example
Dimension*

Scripting name
Data Type

customPropertyNameFilter
String

Custom Property
The options can be limited to only include MES object that have a custom
Valu property expressions defined by this property that evaluates to true.
e
Filte Example
r
Kind > 3

Scripting name
Data Type

customPropertyValueFilter
String

Enabled State Filter The options can be limited to only include MES object that have the specified

enabled state.
Valid Options:
0 = Disabled
1 = Enabled
2 = Both

Scripting name
Data Type

Inductive Automation

enabledStateFilter
Integer

Track and Trace

Name Filter

124

The options can be limited to only include MES objects that their names match
this filter. It can contain wildcard characters including * or ?. The * character can
be any characters and the ? character represents any single character.
Example
*Vine*

Scripting name
Data Type

nameFilter
String

Parent MES Object The options can be limited to only include children of a parent MES object. A
Filte MES Object Selector component can be a slave of another MES Object
r
Selector.

For example, MES Object Selector 1 can be set to show material class objects.
Then, the Parent MES Object property of the MES Object Selector 2 can be
bound to the selected MES Object property of MES Object Selector 1 and set to
show material definitions. Now, the options shown for MES Object Selector 2
will only include children that are in the material class selected in MES Object
Selector 1.
Scripting name
Data Type

parentMESObjectFilter
MESObjectLink
See
MESObjectLink for more information.

SelectedUUID

The UUID of the selected MES object. See UUID for a description of UUIDs.
Scripting name
Data Type

SelectedName

selectedUUID
String

The name of the selected MES object.

Scripting name
Data Type

selectedName
String

Selected MES Object The MES object link for the currently selected MES object. Note that this is a

MESObjectLink and not the full MES object. This is done to reduce the overhead
of loading full objects appearing as options in the selector when they might not
even be selected. The get the full MES object calling getMESObject() function on
the MESObjectLink object can be done.
Scripting name
Data Type

selectedMESObject
MESObjectLink

See
MESObjectLink for more information.

Inductive Automation

Track and Trace

Equipment Path

125

After an equipment item has been selected, this will have the associated
equipment path. It is useful to bind to this property when using this component
as a equipment selector. Note, the equipment path cannot be set using this
property.
Scripting name
Data Type

equipmentPath
String

Extension Functions
objectSelected

The objectSelected extension function is called when the selected MES object changes. It can be
used to perform other operations based on the new selection. It can also prevent the new
selection by returning False.
def objectSelected(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the selected MES

object. Use mesObjectLink.getMESObject() to get the full MES object. See
MESObjectLink for more information.

Events
none

Methods
none

2.6.3

MES Operation Selector

Description
A component that is added to Ignition windows to display and select operations definitions. The operations
definitions that are shown, are limited by those appropriate for the equipment specified in the equipment
path property. The auto complete feature will include only appropriate operations definitions that start with
what the user has typed. This is very useful so scrolling of large lists does not have to be done and the full
name of the operations definition does not have to be typed in.

MES Operations Selector

Properties
This component has standard Ignition properties with the addition of the following properties:
Inductive Automation

Track and Trace

Equipment Path

126

The operations that are shown in the selector are limited to the specific
equipment specified with this property.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type
SelectedUUID

The UUID of the selected operations definition MES object. See UUID for a
description of UUIDs.
Scripting name
Data Type

SelectedName

selectedUUID
String

The name of the selected operations definition MES object.

Scripting name
Data Type

Active

equipmentPath
String

selectedName
String

If true, then there is an active operation for the specified equipment. This can be
bound to control the enabled state of buttons other active operation indications.
Scripting name
Data Type

active
Boolean

Can Begin Operation If true, then the specified equipment is not currently running an operation and a

valid operation has be selected by this component. This can be bound to control
the enabled state of buttons other can begin operation indications.
Scripting name
Data Type
Can End Operation

canBeginOperation
Boolean

If true, then the specified equipment is currently running an operation and can be
ended. This can be bound to control the enabled state of buttons other can end
operation indications.
Scripting name
Data Type

canEndOperation
Boolean

Inductive Automation

Track and Trace

127

To limit which operations definitions to show in the selector, enter a name filter.
It can contain wildcard characters including * or ?. The * character can be any
characters and the ? character represents any single character.

Name Filter

Example
Unload*

Scripting name
Data Type

nameFilter
String

Extension Functions
beginOperation

The beginOperation extension function is called just before the selected operation begins. It can
be used to set additional information in the operations response before it begins. It can also be
prevented by returning False.
def beginOperation(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the operations definition that
will begin. Use mesObjectLink.getMESObject() to get the full MES object. See
MESObjectLink for more information.

endOperation

The endOperation extension function is called just before the active operation is ended. It can be
used to set additional information in the operations response before it ends. It can also prevented
by returning False.
def endOperation(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the operations definition that
will end. Use mesObjectLink.getMESObject() to get the full MES object. See
MESObjectLink for more information.

Inductive Automation

Track and Trace

128

operationSelected

The operationSelected extension function is called when the selected operation definition
changes. It can be used to perform other operations based on the new selection. It can also
prevent the new selection by returning False.
def operationSelected(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the selected operations

definition. Use mesObjectLink.getMESObject() to get the full MES object. See
MESObjectLink for more information.

Events
none

Methods
beginOperation()

Begin the currently selected operations definition. This will cause a new MES Operations Response
object will be created based on the selected operation definition and then start it.
parameters
none
returns

nothing

endOperation()

End the currently active MES Operations Response.

parameters
none
returns

2.6.4

nothing

MES Segment Selector

Description
A component that is added to Ignition windows to display and select operations segments. The operations
segments that are shown, are limited by those appropriate for the equipment specified in the equipment
path property. The auto complete feature will include only appropriate operations definitions that start with
what the user has typed. This is very useful so scrolling of large lists does not have to be done and the full
name of the operations segment does not have to be typed in.
Inductive Automation

Track and Trace

129

MES Segm ent Selector

The MES Segment Selector component has two different modes. The Segment mode is used to select a
Operations Segment to run based on an active Operations Response for the specified equipment. This is
needed when there are multiple segments being used for an operation.
But this is overkill for many situations. If all that is needed is run a single segment like Unload Vinegar
then, the segment can automatically be selected when the operation is selected. The Definition mode
enables this functionality and the MES Operations Selector can be left off the screen. In order for the MES
Segment Selector to know which segment to select, one of two situations must exist. Either, there must
only be one Operations Segment in the Operation Definition or the Operations Segment name must
match the Operations Definition name.
Properties
This component has standard Ignition properties with the addition of the following properties:
Mode

The mode to be used for showing the segments. In segment mode, a operation
must be running for the specified equipment before segment options are shown.
In definition mode, Operations Segments that name matches the associated
Operations Definitions or Operations Definitions that only have one Operations
Segment will be shown.
Valid Options:
0 = Definition
1 = Segm ent

Scripting name
Data Type
Equipment Path

mode
Integer

The segments that are shown in the selector are limited to the specific
equipment specified with this property.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type
SelectedUUID

The UUID of the selected operations definition MES object. See UUID for a
description of UUIDs.
Scripting name
Data Type

SelectedName

selectedUUID
String

The name of the selected operations definition MES object.

Scripting name
Data Type

Inductive Automation

equipmentPath
String

selectedName
String

Track and Trace

130

Auto End Operation If true, then the associated Operations Definition will be ended when the

segment is ended.
Scripting name
Data Type
Active

autoEndOperation
Boolean

If true, then the selected segment is active. This can be bound to control the
enabled state of buttons other active segment indications.
Scripting name
Data Type

active
Boolean

Can Begin Segment If true, then the specified equipment is not currently running the selected

segment. This can be bound to control the enabled state of buttons other can
begin segment indications.
Scripting name
Data Type
Can End Segment

canBeginSegment
Boolean

If true, then the specified equipment is currently running the selected segment
and it can be ended. This can be bound to control the enabled state of buttons
other can end segment indications.
Scripting name
Data Type

canEndSegment
Boolean

Can Update Segment If true, then the specified equipment is currently running the selected segment

and it has been modified and can be updated. This can be bound to control the
enabled state of buttons other can update segment indications. When a lot,
person or other information has been changed for an active segment, it can be
updated to record the changes.
Scripting name
Data Type

canUpdateSegment
Boolean

Can Undo Segment If true, changes have been made to the currently selected segment that is

active. This can be bound to control the enabled state of buttons other can undo
segment indications. When a lot, person or other information has been changed
for an active segment, it can either be update or the changes canceled.
Scripting name
Data Type

canUndoSegment
Boolean

Inductive Automation

Track and Trace

131

To limit which operations segments to show in the selector, enter a name filter.
It can contain wildcard characters including * or ?. The * character can be any
characters and the ? character represents any single character.

Name Filter

Example
Unload*

Scripting name
Data Type

nameFilter
String

Extension Functions
beginOperation

The beginOperation extension function is called just before the associated operation begins. This
is only invoked in Definition mode. It can be used to set additional information in the operations
response before it begins. It can also be prevented by returning False.
def beginOperation(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the selected operations

definition. Use mesObjectLink.getMESObject() to get the full MES object. See
MESObjectLink for more information.

endOperation

The endOperation extension function is called just before the active operation is ended. This is
only invoked is the Auto End Operation is set to true. It can be used to set additional information
in the operations response before it ends. It can also prevented by returning False.
def endOperation(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the operations definition that
will end. Use mesObjectLink.getMESObject() to get the full MES object. See
MESObjectLink for more information.

Inductive Automation

Track and Trace

132

beginSegment

The beginSegment extension function is called just before the selected segment begins. It can
be used to set additional information in the response segment before it begins. It can also be
prevented by returning False.
def beginSegment(self, mesResponseSegment):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesResponseSegmen The MESResponseSegment object that will begin.

t

updateSegment

The updateSegment extension function is called just before the active segment is updated. It can
be used to set additional information in the response segment before it is updated. It can also
prevented by returning False.
def updateOperation(self, mesResponseSegment):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesResponseSegment The MESResponseSegment object that will be updated

endSegment

The endSegment extension function is called just before the active segment is ended. It can be
used to set additional information in the response segment before it ends. It can also prevented
by returning False.
def endOperation(self, mesResponseSegment):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesResponseSegmen The MESResponseSegment object that will end.

t

Inductive Automation

Track and Trace

133

segmentSelected

The segmentSelected extension function is called when the selected segment changes. It can be
used to perform other operations based on the new selection. It can also prevent the new
selection by returning False.
def segmentSelected(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the selected

operations segment. Use mesObjectLink.getMESObject() to get the full
MES object. See MESObjectLink for more information.

Events
none

Methods
beginSegment()

Begin the currently selected operations segment. Depending on the Mode property setting, this will cause
a new MES Operations Response object to be created and started. It will also create a new MES
Response Segment based on the selected operation segment and then start it.
parameters
none
returns

nothing

updateSegment()

If changes exist for the currently active MES Response Segment, they will be recorded.
parameters
none
returns

nothing

endSegment()

End the currently active MES Response Segment. Depending on the Auto End Operation property setting,
it will also end the active MES Operations Response.
parameters
none
returns

Inductive Automation

nothing

Track and Trace

134

endAllSegments()

End all active MES Response Segment objects. Depending on the Auto End Operation property setting, it
will also end the active MES Operations Response.
parameters
none
returns

nothing

updoChanges()

If changes exist for the currently active MES Response Segment, restore them to their values before the
where modified.
parameters
none
returns

2.6.5

nothing

MES Material Selector

Description
A component that is added to Ignition windows to display material selection components for the active
MES Response Segment. The material selection components that are shown depend on the
configuration of the MES Operations Segment.
In the image below, a MES Operations Segment with a material resource named Raw Material caused
the Raw Material header. The material resource has a material class defined causing the component to
select the specific material to be added.
The location for the material is not known, so a component to select the location is added and will contain
options based on the Equipment Class to store the material at.
The material resource is also configured for manual lot number source, causing a component to accept
the lot number is added.
And last, the material source is configured for manual entry of the quantity causing a component to
accept quantity is added.
All this is performed automatically and there is no need to create custom Ignition windows for each
combination of how MES Operations Segment objects are configured.

Inductive Automation

Track and Trace

135

MES Material Selector

If more than one material resource has been defined for a MES Operations Segment, then the MES
Material Selector component will automatically populate components for each material resource.
The MES Material Selector must be used in conjunction with the MES Segment Selector component. The
active MES Response Segment is retrieved from the MES Segment Selector component. MES
Operations Response objects are derived from MES Operations Segment objects and drive the entry
components created in the MES Material Selector component. No binding is required for the two to work
together. Behind the scenes, the MES Material Selector finds the MES Segment Selector and the two will
communicate.
Important
For the MES Material Selector component to find the MES Segment Selector, it must be in the same
container on the window. It is okay to be in a container, they just both have to be in the same container or
root container. Multiple containers can exist on the same window containing separate MES Segment
Selector and MES Material Selector components in each. The components residing in the same container
will work together allowing multiple segments to be controlled from the same window.
Properties
This component has standard Ignition properties with the addition of the following properties:
Modified Icon Path

Set to the Ignition image path of the icon to use for the modified
indication. If this property is left blank, the default icon will be used.
When a entry is changed, the modified icon will appear to the right of
the entry component.
Scripting name
Data Type

Name Filter

modifiedIconPath
String

To limit what is included in the lot or material options, set this filter. It can contain
wildcard characters including * or ?. The * character can be any characters and
the ? character represents any single character.
Example
Lot 150*

Scripting name
Data Type
Extension Functions
Inductive Automation

nameFilter
String

Track and Trace

136

itemSelected

The itemSelected extension function is called when the associated segment changes. It can be
used to perform other operations based on the new selection. Preventing this component from
changing the components for the new segment selection can be done by returning False.
def itemSelected(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the selected response

segment. Use mesObjectLink.getMESObject() to get the full MES object.

See MESObjectLink for more information.
Events
none

Methods
none

2.6.6

MES Personnel Selector

Description
A component that is added to Ignition windows to display personnel selection components for the active
MES Response Segment. The personnel selection components that are shown depend on the
configuration of the MES Operations Segment.
In the image below, a MES Operations Segment with a personnel resource named Operator caused the
Operator header. The personnel resource has a personnel class defined causing the component to
select the specific person to be added.
All this is performed automatically and there is no need to create custom Ignition windows for each
combination of how MES Operations Segment objects are configured.

MES Personnel Selector

If more than one personnel resource has been defined for a MES Operations Segment, then the MES
Personnel Selector component will automatically populate components for each personnel resource.
The MES Personnel Selector must be used in conjunction with the MES Segment Selector component.
The active MES Response Segment is retrieved from the MES Segment Selector component. MES
Operations Response objects are derived from MES Operations Segment objects and drive the entry
Inductive Automation

Track and Trace

137

components created in the MES Personnel Selector component. No binding is required for the two to
work together. Behind the scenes, the MES Personnel Selector finds the MES Segment Selector and the
two will communicate.
Important
For the MES Personnel Selector component to find the MES Segment Selector, it must be in the same
container on the window. It is okay to be in a container, they just both have to be in the same container or
root container. Multiple containers can exist on the same window containing separate MES Segment
Selector and MES Personnel Selector components in each. The components residing in the same
container will work together allowing multiple segments to be controlled from the same window.
Properties
This component has standard Ignition properties with the addition of the following properties:
Modified Icon Path

Set to the Ignition image path of the icon to use for the modified
indication. If this property is left blank, the default icon will be used.
When a entry is changed, the modified icon will appear to the right of
the entry component.
Scripting name
Data Type

modifiedIconPath
String

To limit what is included in the lot or person options, set this filter. It can contain
wildcard characters including * or ?. The * character can be any characters and
the ? character represents any single character.

Name Filter

Example
Lot 150*

Scripting name
Data Type

nameFilter
String

Extension Functions
itemSelected

The itemSelected extension function is called when the associated segment changes. It can be
used to perform other operations based on the new selection. Preventing this component from
changing the components for the new segment selection can be done by returning False.
def itemSelected(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the selected response

segment. Use mesObjectLink.getMESObject() to get the full MES object.

See MESObjectLink for more information.

Events
Inductive Automation

Track and Trace

138

none

Methods
none

2.6.7

MES Sublot List

Description
A component that is added to Ignition windows to manage material sublots. The user can view, add, edit
or delete sublot items. MES Material Sublots are used to track individual items that belong to a MES
Material Lot. For example, if each item that is part of a lot has a serial number, then this component can
be used to allow the operator to manage them. It can also be done in script.

MES Sublot List

The MES Sublot List must be used in conjunction with the MES Segment Selector component. The active
MES Response Segment is retrieved from the MES Segment Selector component. MES Operations
Response objects are derived from MES Operations Segment objects and drive the MES Material Sublot
objects to show. If the MES Operations Segment object has multiple material resources that have the
Enable Sublots setting set to True, then a selection component will appear in this component allowing the
operation to select the lot first. If only one material resource has the Enable Sublots setting set to True,
then the component will not be added and just the sublot list will appear.
No binding is required for the two to work together. Behind the scenes, the MES Material Selector finds
the MES Segment Selector and the two will communicate.
Important
For the MES Sublot List component to find the MES Segment Selector, it must be in the same container
on the window. It is okay to be in a container, they just both have to be in the same container or root
container. Multiple containers can exist on the same window containing separate MES Segment Selector
and MES Sublot List components in each. The components residing in the same container will work
together allowing multiple segments to be controlled from the same window.
Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

Track and Trace

Modified Icon Path

Set to the Ignition image path of the icon to use for the modified
indication. If this property is left blank, the default icon will be used.
When a entry is changed, the modified icon will appear to the right of
the entry component.
Scripting name
Data Type

Show Item
Numbers

Row Height

139

modifiedIconPath
String

If true, sequential item numbers are show to the left of the serial or other
identification number in the list.
showItemNumbers
Scripting name
Data Type
Boolean
The height in pixel to make each row in the list
Scripting name
Data Type

rowHeight
Integer

Extension Functions
none

Events
none

Methods
addSublot()

Create and add a single MES Material Sublot object to the currently selected MES Material Lot object. The
serial number will automatically be generated by the Ignition MES system. However, this can be
overridden with the CreateSerialNumber event of the MES Material Sublot object.
parameters

none

returns

nothing

addSublots(addCount)

Create and add multiple MES Material Sublot objects to the currently selected MES Material Lot object.
The serial numbers will automatically be generated by the Ignition MES system. However, this can be
overridden with the CreateSerialNumber event of the MES Material Sublot object.
parameters

addCount

The number of MES Material Sublot objects to create and add the the current
MES Material Lot.
Inductive Automation

Track and Trace

Data Type
returns

140

Integer

nothing

Sample script to add 10 sublots.

Script from a button action event on the window
event.source.parent.getComponent('MES Sublot List').addSublots(10)

appendSublot(serialNo)

Create and append a single MES Material Sublot object to the end of the sublot list.
parameters

serialNo

The serial number or other identifying number of the sublot to create and add.
Data Type
returns

String

nothing

Sample script to add a single sublot.

Script from a button action event on the window that gets the serial number from a text field component
and appends a new sublot.
serialNo = event.source.parent.getComponent('SN Text Field').text
event.source.parent.getComponent('MES Sublot List').appendSublot(serialNo)

insertSublot(serialNo)

Create and insert a single MES Material Sublot object above the current position in the sublot list.
parameters

serialNo

The serial number or other identifying number of the sublot to create and add.
Data Type
returns

String

nothing

renameSublot(newSerialNo)

Rename the currently selected sublot in the sublot list.

parameters

newSerialNo

The new serial number or other identifying number to rename the sublot to.
Data Type

String
Inductive Automation

Track and Trace

returns

141

nothing

Sample script to rename a sublot.

Script from a button action event on the window that gets the new serial number from a text field
component and rename the current selection.
newSerialNo = event.source.parent.getComponent('SN Text Field').text
event.source.parent.getComponent('MES Sublot List').renameSubLot(newSerialNo)

removeSublot()

Remove the currently selected sublot from the sublot list.

2.6.8

parameters

none

returns

nothing

MES Property Value Editor

Description
A component that is added to Ignition windows to display MES property value components for the active
MES Response Segment. The MES property value entry components that are shown depend on the
configuration of the MES associated objects.
In the image below, a MES Operations Segment with a material resource that references a MES Material
Definition that has a Viscosity custom property. This is causing the entry component to accept a viscosity
value be added. In order for the custom property to be shown, the Production Visible option for the custom
property must be set to True. Likewise, the required indication will be shown when the Required option for
the custom property is set to True.
All this is performed automatically and there is no need to create custom Ignition windows for each
combination of how associated MES objects are configured.

MES Property Value Editor

Inductive Automation

Track and Trace

142

If more than one property has been defined for the associated MES objects, then the MES Property Value
Editor component will automatically populate components for each one.
The MES Property Value Editor must be used in conjunction with the MES Segment Selector or MES
Sublot List components. Which one it works with is determined by the Mode property of this component.
If the Mode is set to Segment, then the active MES Response Segment is retrieved from the MES
Segment Selector component. MES Response Segment objects are derived from MES Operations
Segment objects and drive the entry components created in the MES Property Value Editor component.
No binding is required for the two to work together. Behind the scenes, the MES Property Value Editor
finds the MES Segment Selector and the two will communicate.
If the Mode is set to Lot, then the active MES Response Segment is retrieved from the MES Segment
Selector component. All lot references will be scanned for MES properties and drive the entry
components created in the MES Property Value Editor component. No binding is required for the two to
work together. Behind the scenes, the MES Property Value Editor finds the MES Segment Selector and
the two will communicate.
If the Mode property is set to Sublot, then the selected MES Material Sublot is retrieved from the MES
Sublot List component. The MES Material Sublot object drive the entry components created in the MES
Property Value Editor component. No binding is required for the two to work together. Behind the scenes,
the MES Property Value Editor finds the MES Sublot List and the two will communicate.
Important
For the MES Property Value Editor component to find the MES Segment Selector or MES Sublot List, it
must be in the same container on the window. It is okay to be in a container, they just both have to be in
the same container or root container. Multiple containers can exist on the same window containing
separate MES Segment Selector and/or MES Sublot List and MES Property Value Editor components in
each. The components residing in the same container will work together allowing multiple segments to be
controlled from the same window.
If two MES Property Value Editor components exist on the same container and one is set to Segment
mode and the other is set the Sublot mode, the two will connect to the correct parent. This allows MES
property values to be entered for both the segment or lot and for the selected sublot on the same screen.
Properties
This component has standard Ignition properties with the addition of the following properties:
Mode

The mode to be used select the source of the MES properties to provide value
editors for. Read the general description of this component for more information.
Valid Options:
0 = Segm ent
1 = Lot
2 = Sublot

Scripting name
Data Type

mode
Integer

Inductive Automation

Track and Trace

Modified Icon Path

Set to the Ignition image path of the icon to use for the modified
indication. If this property is left blank, the default icon will be used.
When a entry is changed, the modified icon will appear to the right of
the entry component.
Scripting name
Data Type

Required Icon Path

modifiedIconPath
String

Set to the Ignition image path of the icon to use for the required
indication. If this property is left blank, the default icon will be used.
When the Required option for a MES property is set to True, the
required icon will appear to the left of the entry component.
Scripting name
Data Type

Name Filter

143

requiredIconPath
String

To limit what MES custom properties are shown, set this filter. It can contain
wildcard characters including * or ?. The * character can be any characters and
the ? character represents any single character.
Example
Lot 150*

Scripting name
Data Type

nameFilter
String

Extension Functions
none

Events
none

Methods
none

2.6.9

MES Operation Info

Description
A component that is added to Ignition windows to display details of a MES Operation Response. In
addition to using this component to display the details, script can also be used. See MES Object Handling
scripts and Data and Analysis scripts for more information.
Properties of the MES Operation Info component control what details to show. By setting the Show
Material Info property to True, will cause all material details to be shown. The same is true for operations,
segment, material sublot, personnel and custom properties.

Inductive Automation

Track and Trace

144

MES Operation Info

The MES Operation Info component can run in two different modes that include Realtime and Historical.
In Realtime mode, the MES Operations Response object is determined by the active one for the
equipment specified by the Equipment Path property.
In Historical mode, the MES Operation Response object is determined by the Operation Response Link
property. The MES Object Selector or the MES Trace Graph can be use as a source for the MES
Operation Response link.
Properties
This component has standard Ignition properties with the addition of the following properties:
Mode

The mode to be used for the source of MES Operations Response. Read the
general description above for more information.
Valid Options:
0 = Realtim e
1 = Historical

Scripting name
Data Type

mode
Integer

Inductive Automation

Track and Trace

Equipment Path

145

In Realtime mode, this property specifies the equipment to retrieve the MES
Operations Response object to show information for.
Scripting name
Data Type

equipmentPath
String

Operation Response In Historical mode, this property specifies the MES Operations Response object
Link to show information for.

Scripting name
Data Type

operationResponseLink
MESObjectLink
See
MESObjectLink for more information.

Show Operation Info

Set to True to show operation details.

Scripting name
Data Type

Show Segment Info

Set to True to show segment details.

Scripting name
Data Type

Show Material Info

showCustomPropertyInfo
Boolean

Set to the font to use for the section headers.

Scripting name
Data Type

Inductive Automation

showPersonnelInfo
Boolean

Set to True to show production visible custom properties and their

values. This will display the custom properties and values for the
categories to be shown based on the show properties above.
Scripting name
Data Type

Section Title Font

showMaterialInfo
Boolean

Set to True to show personnel details.

Scripting name
Data Type

Show Custom Property Info

showSegmentInfo
Boolean

Set to True to show material details.

Scripting name
Data Type

Show Personnel Info

showOperationInfo
Boolean

sectionTitleFont
Font

Track and Trace

Section Label Font

Set to the font to use for the section labels.

Scripting name
Data Type

Item Label Font

itemLabelFont
Font

Set to the font to use for the item values.

Scripting name
Data Type

Date Format

sectionLabelFont
Font

Set to the font to use for the item names.

Scripting name
Data Type

Item Value Font

146

itemValueFont
Font

Set to the date format to use when displaying date and times. If this
property is blank, then the default based on the current localization
will be used.
Scripting name
Data Type

dateFormat
String

Extension Functions
none

Events
none

Methods
none

2.6.10 MES Lot Selector

Description
A component that is added to Ignition windows to allow auto complete selection of MES Material Lot or
MES Material Sublot objects. It contains many properties to filter the MES Material Lot or MES Material
Sublot objects to include in the list. The auto complete feature will include only appropriate names that
start with what the user has typed. This is very useful so scrolling of large lists does not have to be done
and full lot or serial number does not have to be typed in.

Inductive Automation

Track and Trace

147

MES Lot Selector

There are two possible modes that the MES Lot Selector component can be used. If the Mode property is
set to Lot, then the selector will be populated with MES Material Lot objects. If the Mode property is set to
Sublot, then the selector will be populated with MES Material Sublot objects.
The Max Results property prevents a huge number of options from being loaded from the database along
with all of the overhead of passing then to the client when the user will not use all of them. This along with
the Begin Date Time and End Date Time properties, keep from taking up unneeded resources.
Properties
This component has standard Ignition properties with the addition of the following properties:
Mode

The mode determines if MES Material Lot or MES Material Sublot objects should
be used to populate the selector.
Valid Options:
0 = Lot
1 = Sublot

Scripting name
Data Type
Include Active Lots

mode
Integer

If true, include active MES Material Lots or MES Material Sublots. Active items
are currently being processed.
includeActiveLots
Scripting name
Data Type
Boolean

Include Inactive Lots If true, include inactive MES Material Lots or MES Material Sublots. Inactive

items are not currently being processed.

includeInactionLots
Scripting name
Data Type
Boolean
Lot Status Filter

If the Final Lot Status setting of a material resource is set, then it can be filter
using this property. For example, MES Material Lot or MES Material Sublot
objects can be set to Hold or any other value and then can be filtered here. It
can contain wildcard characters including * or ?. The * character can be any
characters and the ? character represents any single character.
Scripting name
Data Type

Begin Date Time

When Include Inactive Lots property is set to True, the results are limited to only
include lots or sublots that began or were processed at or after this property.
Scripting name
Data Type

Inductive Automation

lotStatusFilter
String

beginDateTime
Calendar

Track and Trace

End Date Time

When Include Inactive Lots property is set to True, the results are limited to only
include lots or sublots that finished or were processed at or before this property.
Scripting name
Data Type

Max Results

Lot Name Filter

endDateTime
Calendar

The number of items that the selector will be populated with is determined by
this property. This along with the Begin Date Time and End Date Time
properties, keep from taking up unneeded resources. If more results exist than
what is shown, then the Partial Results property will be True.
Scripting name
Data Type

Partial Results

148

maxResults
Integer

If true, more results exist than what is shown as options in the selector. See
Max Results property for more information.
partialResults
Scripting name
Data Type
Boolean
The results can be limited to only include lots that match this property. It can
contain wildcard characters including * or ?. The * character can be any
characters and the ? character represents any single character.
Example
Lot 380*

Scripting name
Data Type
Sublot Name Filter

lotNameFilter
String

The results can be limited to only include sublots that match this property. It can
contain wildcard characters including * or ?. The * character can be any
characters and the ? character represents any single character.
Scripting name
Data Type

sublotNameFilter
String

Lot Equipment Name The results can be limited to only include lots or sublots that are or were stored
Filte at the equipment that match this property. It can contain wildcard characters
r
including * or ?. The * character can be any characters and the ? character

represents any single character.

Example
Vinegar Tank*

Scripting name
Data Type

lotEquipmentNameFilter
String

Inductive Automation

Track and Trace

149

Lot Equipment Class The results can be limited to only include lots or sublots that are or were stored
Filte at the equipment that are included in a material class that match this property. It
r
can contain wildcard characters including * or ?. The * character can be any

characters and the ? character represents any single character.

Example
Vinegar Storage Tanks

Scripting name
Data Type
Personnel Name

lotEquipmentClassFilter
String

The results can be limited to only include lots or sublots that are or were handled
Filte by personnel that match this property. It can contain wildcard characters
r
including * or ?. The * character can be any characters and the ? character

represents any single character.

Scripting name
Data Type
Personnel Class

personnelNameFilter
String

The results can be limited to only include lots or sublots that are or were handled
Filte by personnel that are included in a personnel class that match this property. It
r
can contain wildcard characters including * or ?. The * character can be any

characters and the ? character represents any single character.

Example
Unload Operator

Scripting name
Data Type

personnelClassFilter
String

Material Name Filter The results can be limited to only include lots or sublots that the associated

material matches this property. It can contain wildcard characters including *

or ?. The * character can be any characters and the ? character represents any
single character.
Example
*Balsamic*

Scripting name
Data Type

Inductive Automation

materialNameFilter
String

Track and Trace

150

Material Class Filter The results can be limited to only include lots or sublots that the associated

material is included in a material class that matches this property. It can contain
wildcard characters including * or ?. The * character can be any characters and
the ? character represents any single character.
Example
Vinegar

Scripting name
Data Type
Operation Name

materialClassFilter
String

The results can be limited to only include lots or sublots that were processed
Filte using an operation with a name that matches this property. It can contain
r
wildcard characters including * or ?. The * character can be any characters and

the ? character represents any single character.

Scripting name
Data Type

operationNameFilter
String

Segment Name Filter The results can be limited to only include lots or sublots that were processed

using a segment with a name that matches this property. It can contain wildcard
characters including * or ?. The * character can be any characters and the ?
character represents any single character.
Scripting name
Data Type

segmentNameFilter
String

Custom Property
The results can be limited to only include items that have a custom property
Valu expressions defined by this property that evaluates to true.
e
Filte Example
r
Kind > 3

Scripting name
Data Type
Selected UUID

The UUID of the selected MES object. See UUID for a description of UUIDs.
Scripting name
Data Type

Selected Name

customPropertyValueFilter
String

selectedUUID
String

The name of the selected MES object.

Scripting name
Data Type

selectedName
String

Inductive Automation

Track and Trace

Selected Lot UUID

The UUID of the selected MES Material Lot object. See UUID for a description of
UUIDs.
Scripting name
Data Type

Selected Lot Name

151

selectedLotUUID
String

The name of the selected MES Material Lot object.

Scripting name
Data Type

selectedLotName
String

Selected Sublot UUIDThe UUID of the selected MES Material Sublot object. See UUID for a description

of UUIDs.
Scripting name
Data Type

selectedSublotUUID
String

The name of the selected MES Material Sublot object.

Selected Sublot
Nam
e

Scripting name
Data Type

selectedSublotName
String

Extension Functions
lotSelected

The lotSelected extension function is called when the selected MES object changes. It can be
used to perform other operations based on the new selection. It can also prevent the new
selection by returning False.
def lotSelected(self, mesObjectLink):
argum ents

arguments
self

A reference to the component that is invoking this function.

mesObjectLink

The MESObjectLink object that contains a reference to the selected MES

object. Use mesObjectLink.getMESObject() to get the full MES object. See
MESObjectLink for more information.

Events
none

Methods
none

Inductive Automation

Track and Trace

152

2.6.11 MES Trace Graph

Description
A component that is added to Ignition windows to visually see traceability results. It shows the flow of
production for bulk lot (batch) and / or serialized items. This allows entering a lot (batch) number and
seeing what went into making it up from raw materials through the production steps to the finished
goods. Then if desired, product can be tracked beyond the production facility. Individual items can also by
tracked by using a serial number or other item identification.
If a node has a sublot that has a name that matches the Highlight Sublot Name, then text specified by the
Sublot Match Text property will be displayed in the lot node. This is valuable at determining which lots
contain the sublot (serial number) of interest.

MES Trace Graph

The nodes are laid out in chronological order from left to right. The node type alternates starting with a
segment then showing a lot. The idea behind this is there are lots that are inputs to an operation and there
are lot that the operation produced. In the image below, the upper left node titled Unload Station 1 is the
operation that vinegar was unloaded. When this operation was done, a new lot VIN 2988 was created.
Then that lot was used in the operation of making of balsamic dressing at Mix Station 1, which produced
balsamic dressing that resides in Holding Tank 2.

Inductive Automation

Track and Trace

153

MES Trace Graph Node Layout

The Trace Graph component also is an excellent navigation tool to zero in on non-trace information.
Because the date and times, material, equipment, lot numbers, serial number, etc. are known, other data
can be filtered to match the trace information being shown. This gives, otherwise just time series data,
context to specific lots and serialized items without the need to look it up manually potentially across
multiple systems.
To support this functionality, the trace graph component has very configurable menus that are used to
display additional non-trace information. When the menu is selected by the user, the associated date and
times, lot number, material, personnel, etc. is included in the menu event so that data within and outside
of Ignition can be looked up and displayed.
Properties
This component has standard Ignition properties with the addition of the following properties:
Lot Name

Set to the lot number to display the trace information for in the trace
graph.
Scripting name
Data Type

Lot UUID

Set to the UUID of the Material Lot object to display the trace
information for in the trace graph. A lot number can be the same for
multiple operations as is the case where more parts are being added
to a main assembly. To select one of the lots as the primary one to
focus the trace graph around, this property will have to be set instead
of the Lot Name property.
Scripting name
Data Type

Inductive Automation

lotName
String

lotUUID
String

Track and Trace

Highlight Sublot Name

Set to the name of the Material Sublot object, serial number or other
item identification, to highlight in the lot nodes.
Scripting name
Data Type

Lot Tool Tip Format

154

highlightSublotName
String

Set to format the display of lot node tooltip. It is formatted in HTML and
can reference the column names in the dataset that the trace graph
display is generated from. The dataset results are the same as the
Lot Trace Binding Function that has full documentation of the available
columns.
Example:
<html>{LotName}<br/>{LotSequence}<br/>{LotStatus}<br/>
{LotBeginDateTime}<br/>{LotEndDateTime}<br/>{MaterialName}<br/>
{LotLocationName}</html>

Scripting name
Data Type
Segment Tool Tip Format

lotToolTipFormat
String

Set to format to display the segment node tooltip. It is formatted in

HTML and can reference the column names in the dataset that the
trace graph display is generated from. The dataset results are the
same as the Lot Trace Binding Function that has full documentation of
the available columns.
Example:
<html>{SegmentName}<br/>{SegmentLocationName}</html>

Scripting name
Data Type
Enable Auto

segmentToolTipFormat
String

Set to True to enable resizing when the right mouse button is clicked in the open
Sarea. When a menu is shown when the right mouse button is clicked, it is better to
i set this property to False. See the autoFit() function of this component that can be
zcalled from a button.
i
n
g

Scripting name
Data Type
Edge Color

enableAutoSizing
Boolean

The color to use when displaying edges. Edge in graphing terms is the line between
the nodes.
Scripting name
Data Type

edgeColor
Color

Inductive Automation

Track and Trace

Sublot Match Text

Set to the text to display in a lot node when it contains a Material

Sublot object with a name that matches the Highlight Sublot Name
property.
Scripting name
Data Type

Inductive Automation

155

sublotMatchText
String

Track and Trace

Node Configuration

156

A dataset containing node configuration used when displaying nodes

in the MES Trace Graph component. The colors of the different parts
of a node can be changed using this property. This provides a visual
deference of the different types of MES objects.
This property is a dataset allowing any number of node configurations
keyed by first the name of the node and if a match is not found, then if
will look for match by node type. If no matches are found, the entry
named Default will be used.

Node Parts

Scripting name
Data Type

nodeConfiguration
Dataset

The Dataset must have the following columns that are reference by
column name when building node definitions:
Name

Str Name which can be the node name or node type. It can
ing contain wildcard characters including * or ?. The *
character can be any characters and the ? character
represents any single character.
The valid node types match the type of the MES object
and include:
MaterialLot
ResponseSegment

Examples:
Mix Station*
Unload Station ?
ResponseSegment

HeaderBack Col The color to use for the header background.

groundColor or
HeaderFont Col The color to use for the header text.
Color
or
BodyBackgr Col The color to use for the background of the body.
oundColor or
BodyFontCo Col The color to use for the body text.
lor
or
HasSublotF Col The color to use when displaying the has sublot text in
ontColor
or the node.
Inductive Automation
BorderColor Col The color to use for the border.

or

Track and Trace

User Menu Items

157

A dataset containing user menu item to show in popup menus for the
different nodes and names of the MES Trace Graph component. Both
the node type and the name must match before the menu item will
appear for the node.
Scripting name
Data Type

userMenuItems
Dataset

The Dataset must have the following columns that are reference by
column number when building the user menus:
0

String

Node type that determines which popup

menu the user menu item will appear in.
Valid options are:
The valid node types match the type of the
MES object and include:
MaterialLot
ResponseSegment

String

Node name to match that determines

which popup menu the user menu item
will appear in. It can contain wildcard
characters including * or ?. The *
character can be any characters and
the ? character represents any single
character.
Examples:
Bottling*
Oil Tank ?

String

Text to appear for the user menu item.

This is also used to identify the user menu
item that was clicked in the
userMenuItemClicked event.

String

Ignition image path of the icon to display

in the user menu item.

Events
meunu - userMenuItemClicked
Event Properties
event.getMenuItemName()
event.getNodeName()

Inductive Automation

Is fired whenever a user menu item is selected.

Returns the name of the user menu item that triggered the event.
Data Type
String
Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

Track and Trace

158

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

selectNode - nodeClicked
Event Properties
event.getNodeName()

Is fired whenever a user clicks the mouse button on a node.

Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

selectNode - nodeEntered
Event Properties
event.getNodeName()

Is fired whenever the mouse is moved over a node.

Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

selectNode - nodeExited
Event Properties
event.getNodeName()

Is fired whenever the mouse is moved off of a node.

Returns the name of the node. This is the same as the name of
the MES object that is associated with the node
Data Type
String

event.getObjectType()

Returns the name of the MES object type that is associated with
the node.
Data Type
String

event.getUUID()

Returns the UUID of the MES object that is associated to the node.
Data Type
String

Inductive Automation

Track and Trace

159

Methods
refresh()

Refresh the trace information. When the property values change the trace graph will be updated, but this
provides updating the data without changing a property.
parameters
none
returns

nothing

autoFix()

Automatically zoom and pan the node display to show the current node included in the MES Object Editor.
parameters
none
returns

nothing

Sample script to zoom and pan to fit the currently displayed node to fit in the editor.
Script from a button action event on the window
event.source.parent.getComponent('MES Object Editor').autoFit()

Inductive Automation

Track and Trace

2.7

160

Reports and Analysis

Besides using the track and trace components or scripting, the binding functions can be used to retrieve
trace information that can be used in reports or non track and trace components.
The image below shows the Ignition property binding screen that is commonly used when using building
in Ignition projects. To access the track and trace binding functions, select Functions and then select the
desired binding function in the Trace group.

Trace Binding Functions

Each of the Trace binding functions are described in the following sections.

2.7.1

Inventory

The Inventory binding function is used to retrieve inventory information based on the filter parameters
listed in the image below. It is an excellent method to get inventory of a particular material or class of
material. But much more can be done by combining filters specified by the parameters below to zero in
on the inventory information of interest.

Inductive Automation

Track and Trace

161

Inventory Binding Function

Parameters
Begin Date Time

When the Include Inactive Lots parameter is set to True, the results are limited
to only include results that were processed at or after this property.
Data Type

End Date Time

When the Include Inactive Lots parameter is set to True, the results are limited
to only include results that were processed at or before this property.
Data Type

Include Active Lots

Inductive Automation

Calendar

Calendar

If true, include active MES Material Lots or MES Material Sublots. Active items
are currently being processed.
Data Type
Boolean

Track and Trace

Include Completed
Lots

162

If true, include completed MES Material Lots or MES Material Sublots.

Data Type

Boolean

Include Custom Lot If the Final Lot Status setting of a material resource is set, then it can be filter
Stat using this property. For example, MES Material Lot or MES Material Sublot
us objects can be set to Hold or any other value and then can be filtered here. It

can contain wildcard characters including * or ?. The * character can be any

characters and the ? character represents any single character.
Data Type

String

Equipment Class
The results can be limited to only include lots or sublots that are or were stored
Nam at the equipment that are included in a material class that match this property. It
e
can contain wildcard characters including * or ?. The * character can be any

characters and the ? character represents any single character.

Only one of the Equipment Class Name, Equipment Class UUID, Equipment
Path or Equipment UUID properties can be specified at a time.
Example
Vinegar Storage Tanks

Data Type

String

Equipment Class
The results can be limited to only include lots or sublots that are or were stored
UUIDat the equipment that are included in a material class that match this property.

See UUIDs for more information.

Only one of the Equipment Class Name, Equipment Class UUID, Equipment
Path or Equipment UUID properties can be specified at a time.
Data Type
Equipment Path

String

The results can be limited to only include lots or sublots that are or were stored
at the equipment that match this property. See Equipment for more information
on equipment paths
Only one of the Equipment Class Name, Equipment Class UUID, Equipment
Path or Equipment UUID properties can be specified at a time.
Data Type

Equipment UUID

String

The results can be limited to only include lots or sublots that are or were stored
at the equipment that match this property. See UUIDs for more information.
Data Type

String
Inductive Automation

Track and Trace

163

Material Class Name The results can be limited to only include lots or sublots that the associated

material is included in a material class that matches this property. It can contain
wildcard characters including * or ?. The * character can be any characters and
the ? character represents any single character.
Only one of the Material Class Name, Material Class UUID, Material Definition
Name, Material Definition UUID properties can be specified at a time.
Example
Vinegar

Data Type

String

Material Class UUID The results can be limited to only include lots or sublots that the associated

material is included in a material class that matches this property. See UUIDs
for more information.
Only one of the Material Class Name, Material Class UUID, Material Definition
Name, Material Definition UUID properties can be specified at a time.
Data Type

String

Material Definition The results can be limited to only include lots or sublots that the associated
Nam material matches this property. It can contain wildcard characters including *
e
or ?. The * character can be any characters and the ? character represents any

single character.
Only one of the Material Class Name, Material Class UUID, Material Definition
Name, Material Definition UUID properties can be specified at a time.
Example
*Balsamic*

Data Type

String

Material Definition The results can be limited to only include lots or sublots that the associated
UUIDmaterial matches this property. See UUIDs for more information.

Only one of the Material Class Name, Material Class UUID, Material Definition
Name, Material Definition UUID properties can be specified at a time.
Data Type

Inductive Automation

String

Track and Trace

164

The results can be limited to only include lots or sublots that are or were handled

Personnel Class

Nam by personnel that are included in a personnel class that match this property. It
e
can contain wildcard characters including * or ?. The * character can be any

characters and the ? character represents any single character.

Only one of the Personnel Class Name, Personnel Class UUID or Person First
Name and Person Last Name combination properties can be specified at a time.
Example
Unload Operator

Data Type

String

Personnel Class UUIDThe results can be limited to only include lots or sublots that are or were handled

by personnel that are included in a personnel class that match this property.
See UUIDs for more information.
Only one of the Personnel Class Name, Personnel Class UUID or Person First
Name and Person Last Name combination properties can be specified at a time.
Data Type
Person First Name

String

The results can be limited to only include lots or sublots that are or were handled
by personnel that match this property. It can contain wildcard characters
including * or ?. The * character can be any characters and the ? character
represents any single character.
Data Type

Person Last Name

String

The results can be limited to only include lots or sublots that are or were handled
by personnel that match this property. It can contain wildcard characters
including * or ?. The * character can be any characters and the ? character
represents any single character.
Data Type

Person UUID

String

The results can be limited to only include lots or sublots that are or were handled
by personnel that match this property. See UUIDs for more information.
Data Type

String

Inventory Results
The inventory results are returned as a Dataset with the following columns.

Column Name
MESPropertyUUID

Data Type
String
Inductive Automation

Track and Trace

2.7.2

MESMaterialLotUUID

String

LotName

String

LotSequence

Integer

LotDescription

String

LotStatus

String

LotUnits

String

LotAssemblyType

String

MESMaterialDefUUID

String

MaterialName

String

MaterialDescription

String

MESEquipmentUUID

String

EquipmentPath

String

LotBeginDateTime

Date

LotEndDateTime

Date

LotQuantity int

Integer

LotPropertyStatus

String

MESPersonUUID

String

PersonFirstName

String

PersonLastName

String

Description

String

PersonBeginDateTime

Date

PersonEndDateTime

Date

PersonPropertyStatus

String

165

Lot Trace

The Lot Trace binding function is used to retrieve trace information for a lot based on the filter parameters
listed in the image below. It returns the same data that the Trace Graph component uses to display it's
information.

Inductive Automation

Track and Trace

166

Lot Trace Binding Function

Parameters

Lot Name

The lot name to return the trace details results. Optionally Lot UUID can be used
but not both.
Data Type

Lot UUID

The lot UUID to return the trace details results. Optionally Lot Name can be used
but not both. See UUIDs for more information.
Data Type

Highlight Sublot

String

String

If this property is not blank and a sublot of a lot name matches this property,
Nam then the LotContainsSublot column in the results will be set to 1. This indicates
e
that the lot contains the specified sublot.

Data Type

String

Inductive Automation

Track and Trace

167

If true, results will be retrieved. This provides a method to disable the retrieval of
lot trace results and the associated overhead.
Data Type
Boolean

Enable

Lot Trace Results

The lot trace results are returned as a Dataset with the following columns.

Column Name

Data Type

LotUUID

String

LotName

String

LotSequence

Integer

LotStatus

String

LotUse

String

LotBeginDateTime

Date

LotEndDateTime

Date

LotQuantity

Double

MaterialUUID

String

MaterialName

String

LotLocationUUID

String

LotLocationName

String

SegmentUUID

String

SegmentName

String

SegmentBeginDateTime

Date

SegmentEndDateTime

Date

SegmentLocationUUID

String

SegmentLocationName

String

PrevSegmentUUID

String

NextSegmentUUID

String

SegInCount

Integer

SegOutCount

Integer

LotInCount

Integer

LotOutCount

Integer

LotContainsSublot

Integer

Inductive Automation

Track and Trace

2.7.3

168

Sublot Trace

The Sublot Trace binding function is used to retrieve trace information for a sublot based on the filter
parameters listed in the image below. It returns the same data that the Trace Graph component used to
display it's information.

Sublot Trace Binding Function

Parameters
Enable

Sublot Name

If true, results will be retrieved. This provides a method to disable the retrieval of
lot trace results and the associated overhead.
Data Type
Boolean
The sublot name to return the trace details results. Optionally Sublot UUID can
be used but not both.
Data Type

Sublot UUID

String

The sublot UUID to return the trace details results. Optionally Sublot Name can
be used but not both. See UUIDs for more information.
Data Type

String
Inductive Automation

Track and Trace

Lot Trace Results

The sublot trace results are returned as a Dataset with the following columns.

Column Name

Data Type

LotUUID

String

LotName

String

LotSequence

Integer

LotStatus

String

LotUse

String

LotBeginDateTime

Date

LotEndDateTime

Date

LotQuantity

Double

MaterialUUID

String

MaterialName

String

LotLocationUUID

String

LotLocationName

String

SegmentUUID

String

SegmentName

String

SegmentBeginDateTime

Date

SegmentEndDateTime

Date

SegmentLocationUUID

String

SegmentLocationName

String

PrevSegmentUUID

String

NextSegmentUUID

String

SegInCount

Integer

SegOutCount

Integer

LotInCount

Integer

LotOutCount

Integer

LotContainsSublot

Integer

Inductive Automation

169

Track and Trace

2.7.4

170

Lot Info

The Lot Info binding function is used to retrieve information for a lot based on the filter parameters listed in
the image below. It can be used to display and report lot details including sublot information and custom
property values.

Lot Info Binding Function

Parameters
Enable

Lot Name

If true, results will be retrieved. This provides a method to disable the retrieval of
lot information results and the associated overhead.
Data Type
Boolean

The lot name to return the lot information results. Optionally Lot UUID can be
used but not both.
Data Type

Lot UUID

String

The lot UUID to return the lot information results. Optionally Lot Name can be
used but not both. See UUIDs for more information.
Data Type

String
Inductive Automation

Track and Trace

171

Include Sublots

If true, the results will include a column named Sublots that contains a Dataset
to hold sublot information.
Data Type
Boolean

Include Custom
Properties

If true, the results will include a column named CustomProperties that contains
a Dataset to hold custom property information.
Data Type
Boolean

Lot Trace Results

The lot information results are returned as a Dataset with the following columns.

Column Name

Data Type

LotUUID

String

LotName

String

LotSequence

Integer

LotDescription

String

LotEnabled

Integer

LotAssembly

String

LotStatus

String

LotUnits

String

MaterialUUID

String

MaterialName

String

MaterialDescription

String

MaterialEnabled

Integer

EquipmentUUID

String

EquipmentName

String

EquipmentDescription

String

EquipmentEnabled

Integer

Sublots

Dataset

CustomProperties

Dataset

If the Include Sublots parameter is set to True, then the Dataset in the Sublots column will have the
following columns.
Inductive Automation

Track and Trace

Column Name

172

Data Type

SublotUUID

String

SublotName

String

SublotDescription

String

SublotEnabled

Integer

SublotAssembly

String

SublotStatus

String

If the Include Custom Properties parameter is set to True, then the Dataset in the CustomProperties
column will have the following columns.

Column Name

Data Type

MESPropertyUUID

String

ParentMESPropertyUUID

String

Name

String

Description

String

Value

String

ValueUnits

String

ValueDataType

Integer

Enable

Integer

Required

Integer

ProductionVisible

Integer

Extract Sublots and Custom Properties Example:

data = event.source.parent.getComponent('Table').data
sublots = data.getValueAt(0, 'Sublots')
event.source.parent.getComponent('Table 1').data = sublots
customProps = data.getValueAt(0, 'CustomProperties')
event.source.parent.getComponent('Table 2').data = customProps

2.7.5

Sublot Info

The Sublot Info binding function is used to retrieve information for a sublot based on the filter parameters
listed in the image below. It can be used to display and report sublot details including custom property
values.
Inductive Automation

Track and Trace

173

Sublot Info Binding Function

Parameters
Enable

Sublot Name

If true, results will be retrieved. This provides a method to disable the retrieval of
lot information results and the associated overhead.
Data Type
Boolean
The sublot name to return the sublot information results. Optionally Sublot UUID
can be used but not both.
Data Type

Sublot UUID

The sublot UUID to return the sublot information results. Optionally Sublot Name
can be used but not both. See UUIDs for more information.
Data Type

Include Custom
Properties

Inductive Automation

String

String

If true, the results will include a column named CustomProperties that contains
a Dataset to hold custom property information.
Data Type
Boolean

Track and Trace

174

Lot Trace Results

Column Name

Data Type

SublotUUID

String

SublotName

String

SublotDescription

String

SublotEnabled

Integer

SublotAssembly

String

SublotStatus

String

CustomProperties

Dataset

If the Include Custom Properties parameter is set to True, then the Dataset in the CustomProperties
column will have the following columns.

Column Name

Data Type

MESPropertyUUID

String

ParentMESPropertyUUID

String

Name

String

Description

String

Value

String

ValueUnits

String

ValueDataType

Integer

Enable

Integer

Required

Integer

ProductionVisible

Integer

Extract Custom Properties Example:

data = event.source.parent.getComponent('Table').data
customProps = data.getValueAt(0, 'CustomProperties')
event.source.parent.getComponent('Table 1').data = customProps

Inductive Automation

Track and Trace

2.8

MES Objects

2.8.1

Overview

175

The Track and Trace Module is aligned with the ISA-95 standard which all of the MES Object covered
below are based on. The standard provides a model to control and track production in a variety of
industries. See the ISA-95 in the Introduction section for more information.
The list below, brief details of the MES object that are currently supported by the Ignition Track and Trace
Module.
MaterialClass
An object used as a category that can have Material Class or Material Definition objects as children.
MaterialDef
An object used to define material that can have Material Definition objects as children.
PersonnelClass
An object used as a category that can have Personnel Class or Person objects as children.
Person
An object used to define people and cannot have children.
MaterialLot
An object used to hold lot information that can have Material Sublot objects as children.
MaterialSublot
An object used to hold sublot information and cannot have children. Typically, Material Sublot objects
are used hold details about each item of a Material Lot as is the case where each item is of the same
type and each has a serial number or some other type of identifier.
EquipmentClass
An object used as a category that can have Equipment Class, MES Enterprise, MES Site, MES Area,
MES Line, MES Line Cell, MES Line Cell Group, MES Storage Zone or MES Storage Unit objects as
children.
Equipment
An object used to define soft or rolling equipment that can be included for a segment. This is not a
equipment that resides in the production model that is defined in the Ignition designer. The reason
equipment is defined in the Ignition designer is because tags are used to collect production data,
downtime, SPC sample data, etc. for it. Tags cannot be assigned in the client and involves
configuration from the control system, through the OPC server and tags to the equipment defined in
the production model.
ProcessSegment
An object used to hold definition of the basic tasks that are performed in a manufacturing facility.
Tasks can be as simple as "produce product", but can be more granular like changeover line, clean,
lab inspection, heat up, pre-production, produce product and run out line.
OperationsDefinition
Inductive Automation

Track and Trace

176

An object used to hold operational definition that contain one or more Operations Segment (tasks).
OperationsSegment
An object used to hold operational segment that is derived from a Process Segment (task). One or
more Operations Segment objects can be attached to a Operations Definition
OperationsResponse
An Operations Response object is based on an Operations Definition and holds actual results of a
operation that is being run or has been run at a piece of equipment configured in the production
model.
ResponseSegment
An Response Segment object is based on an Operations Segment and hold actual results of a
segment (task) that is being run at a piece of equipment configured in the production model.
MESEnterprise
An object that is based on the MES Enterprise configured in the production model which is done in the
designer. Operations cannot be run at a MES Enterprise. The MES Enterprise is used for enterprise
operations and analysis.
MESSite
An object that is based on the MES Site configured in the production model which is done in the
designer. Operations cannot be run at a MES Site. The MES Site is used for enterprise operations
and analysis.
MESArea
An object that is based on the MES Area configured in the production model which is done in the
designer. Operations cannot be run at a MES Area. The MES Area is used for analysis.
MESLine
An object that is based on the MES Line configured in the production model which is done in the
designer. Operations can be run at a MES Line. The MES Line can also be used for operations and
analysis.
MESLineCell
An object that is based on the MES Line Cell configured in the production model which is done in the
designer. Operations can be run at a MES Line Cell. The MES Line Cell can also be used for
operations and analysis.
MESLineCellGroup
An object that is based on the MES Line Cell Group configured in the production model which is done
in the designer. Operations can be run at a MES Line Cell Group. The MES Line Cell Group can also
be used for operations and analysis.
MESStorageZone
An object that is based on the MES Storage Zone configured in the production model which is done in
the designer. Operations cannot be run at a MES Storage Zone. The MES Storage Zone is used for
analysis.
MESStorageUnit
An object that is based on the MES Storage Unit configured in the production model which is done in
Inductive Automation

Track and Trace

177

the designer. Operations can be run at a MES Storage Unit. The MES Storage Unit can also be used
for operations and analysis.
All of these are inherited from the AbstractMESObject that provides common properties and functionality
for each MES object type.

2.8.2

Properties

Properties are broken into three different categories. The first are core properties and follow closely to
what the ISA-95 standard defines each object should support. The ISA-95 standard refers to these as
attributes, but the Track and Trace module uses the term "core properties" to keep consistent with
terminology already used in Ignition.
Next are custom properties, and the ISA-95 standards simply refers to these as properties. Again, the
term is consistent with the existing "custom properties" term already being used in Ignition.
An last, there are complex properties. Complex properties are not defined explicitly in the ISA -95
standard, but are inferred when defining resources needed for a operation and other aggregate lists.
The base AbstractMESObject object provides common core properties that are passed on to each of
specific MES objects types. Each specific MES object can have additional core properties.

Core Properties common to all MES Objects

The core properties exist for every Process Segment object and only the values can be modified.

Property Name

Description

Name

This is the name of the MES object. This name is used when referencing the object. It
must be a unique name meaning that no other MES object of it's type can have the same
name.

UUID

This will contain the Universally Unique Identifier for each instance of a MES object.

Enabled

This property will be set to true when the MES object is active and usable. When
MES objects are deleted they are still retained in the database and the Enabled
setting is set to false. This is done to maintain past traceability information.

Description

An optional settings to give more details for a MES Object.

The values of the core properties are accessed using the getPropertyValue() and setPropertyValue()
functions of the AbstractMESObject object.
Get MES object UUID example:
mesObject = system.mes.loadMESObject("Vinegar", "MaterialClass")
print mesObject.getPropertyValue('UUID')

Set MES object name example:

mesObject = system.mes.loadMESObject("Vinegar", "MaterialClass")
mesObject.setPropertyValue('Name', 'MyNewObjectName')

Custom Properties
Custom properties are added to any MES object by using the MES object editor component or by
Inductive Automation

Track and Trace

178

using script functions.

Custom properties can be nested, meaning a custom property can be added to a custom property.
This allows defining a structure to custom properties where Width, Height and Depth custom
properties can be add beneath Dimension custom property.
Custom properties have a production visible option that will show the property in the MES Property
Value Editor component. This provides a method to keep custom properties hidden and not show
then to operators or other end users. If the custom property is visible to the end users, the required
options will make sure a value is entered before ending an operation.
Adding / editing custom property using the MES Object Editor
The MES Object Editor component has built-in support to add custom properties to any of the
MES object types. The only MES object types that custom properties cannot be added are
MES objects that are not configured using the MES Object Editor. These include MES objects
like MaterialLot, MaterialSublot, OperationsResponse and ResponseSegment, because they
are only used during production and not used to define resources or operations.

Add Custom Property Menu

Next, the custom property setting panel is shown and the details for it can be configured.

Inductive Automation

Track and Trace

179

Custom Property Settings

Add and set custom property using script:

The following code will add a custom property named pH that is the Ignition Float8 data type.
After the custom property is added to the MaterialClass object named Vinegar, it is set to the
value of 5.1
mesObject = system.mes.loadMESObject('Vinegar', 'MaterialClass')
mesObject.addCustomProperty('pH', 'Float8')
mesObject.setPropertyValue('pH', 5.1)

Add and custom property with options using script:

This will add a custom property named pH, that is the Ignition Float8 data type, has not units,
will be shown in the MES Property Value Editor component and a value is not required.

mesObject = system.mes.loadMESObject('Vinegar', 'MaterialClass')

mesObject.mesObject.addCustomProperty('pH', 'Float8', 'pH of vinegar during unloading', '', Tru

Get MES custom property example using script:

mesObject = system.mes.loadMESObject("Vinegar", "MaterialClass")
print mesObject.getPropertyValue('pH')

Note: See the custom property section of the AbstractMESObject reference for all of the custom property functions.

Complex Properties
Complex properties are predefined and vary based on the type of MES object. In general, they are
named complex properties because they have a number of members and there can be multiple
instances for a given complex property type. A Process Segment to mix dressing will have multiple
material references. Each one will be an instance of a Material complex property. Even more complex
is the Lot complex property used by the Response Segment for mixing dressing, because there will
be multiple lots for each input material each with their own complex property base name. Then, if an
Inductive Automation

Track and Trace

180

input material lot is used up during production and switched over to another input lot, then there will be
multiple instances for the same input lot reference.
An example will help clarify this concept. If we are mixing dressing which requires vinegar that is
coming from Lot 123 in vinegar tank 1, then there will be an instance of a Lot complex property for it.
This complex property has a name to reference it by, and in this example we will call it "Ingredient
Vinegar". Then during production of mixing dressing, we run out of vinegar in tank 1 and we switch
over to vinegar tank 2. Vinegar tank 2 contains Lot 234 so there will be another Lot complex property
for it with the same name "Ingredient Vinegar". Now there are two Lot complex properties that are
referenced by the same name "Ingredient Vinegar". Behind the scenes, the names are modified with a
post fix. As a result the Lot complex property for Lot 123 will be named "Ingredient Vinegar-1" and the
one for Lot 234 will be named "Ingredient Vinegar-2". This is referred to as extended naming. Each will
hold complete details of when the lot start and when it finished, quantity, etc.
Refer to the Process Segment, Operations Definition, Operations Segment, Operations Response
and Response Segment for more details about the different types of complex properties.
Add complex property using the MES Object Editor
<Put image of adding complex material property here>
Create and add complex property using script:
mesObject = system.mes.createMESObject('ProcessSegment')
materialProp = mesObject.createComplexProperty('Material', 'Vinegar')
#Set materialProp values
mesObject.addComplexProperty(materialProp)

Cycle through all complex property types and print their names using script:
mesObject = system.mes.loadMESObject('Mix Dressing', 'ProcessSegment')
list = mesObject.getComplexPropertyTypeNames()
for i in range(list.size()):
complexPropType = list.get(i)
cnt = mesObject.getComplexPropertyCount(complexPropType)
for j in range(cnt):
complexProp = mesObject.getComplexProperty(complexPropType, j)
print complexProp.getName()

Note: See the complex property section of the AbstractMESObject reference for all of the complex property functions.

2.8.3

Script Functions

The AbstractMESObject object is the base that each of the MES object types are derived from, and
provide the basic functions for many of the common operations that are required by the Track and Trace
Module. All of these functions are available in script that can be executed on the gateway or in the client.
Below is a list of the script functions by category

Inductive Automation

Track and Trace

2.8.3.1

181

General Script Function

The AbstractMESObject object has general functions that can be used in scripting. All of the functions
detailed below act on a MES object. This means that a variable of an MES object is needed and then the
function is called on that variable.

General MES Object Script Functions

.
getUUID()

Returns the UUID for the MES object. The is automatically assigned and should not be
changed.
parameters
None

returns

The MES object UUID

Data Type

String

getName()

Returns the name for the MES object. This must be provided prior to saving a new MES object.
It can be changed afterwards and depending on the type of MES object, might have to be
unique from all of the other names of the same type of object.
Use the setPropertyValue('Name', 'New Name') function to rename a MES object.
parameters
None

returns

The name object UUID

Data Type

String

getMESObjectType()

Returns the type of MES object. The AbstractMESObject is the base type to all MES Objects
and having a instance to an MES object doesn't mean the type is known. Calling this function
the type of object can be determined.
See MESObjectTypes for how to get the text name of the type and more.
parameters
None

Inductive Automation

Track and Trace

182

returns

Type of MES object

Data Type

MESObjectTypes

getDescription()

Returns the description for the MES object. The description is optional.
Use the setPropertyValue('Description', 'New Description') function to assign or change a
description of a MES object.
parameters
None

returns

The name object UUID

Data Type

String

isModified()

Returns true if the MES object has changes that have not been saved.
parameters
None

returns

True is modified else False

Data Type

Boolean

Get UUID Example:

mesObject = system.mes.loadMESObject('Vinegar', 'MaterialClass')
print mesObject.getUUID()

output
6817badd-7d68-473b-b9ed-098bb8acafea

2.8.3.2

Property Script Functions

The AbstractMESObject object has general functions that can be used in scripting. All of the functions
detailed below act on a MES object. This means that a variable of an MES object is needed and then the
function is called on that variable.

General Property Script Functions

getPropertyValue(propertyPath)
Inductive Automation

Track and Trace

183

Get the value of a core, custom or complex property.

parameters
propertyPath

The path of the property. For core properties this is just the
property name. For custom properties that are nested or complex
properties, it is the path to the final property to set the value of.
Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
returns

The value of the property

Data Type Serializable
setPropertyValue(propertyPath, value)

Set the value of a core, custom or complex property.

parameters
propertyPath

The path of the property. For core properties this is just the
property name. For custom properties that are nested or complex
properties, it is the path to the final property to set the value of.
Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
value

The value to set the property to.

Data Type Serializable
returns
None

getModifiedMESProperties()

Return a ModifiedMESProperties object containing all of the properties that are dirty and have
not been saved in the MES object. This method is typically used to update MES objects that are
derived from the modified MES object. Saving the MES object will reset the modified flag.
parameters
None

returns

An object containing all modified properties.

Data Type ModifiedMESProperties
Inductive Automation

Track and Trace

184

Get Property Value Example:

mesObject = system.mes.loadMESObject('unload Vinegar', 'ProcessSegment')
print mesObject.getPropertyValue('UUID')

output
2064af20-5b4f-45d7-bb1a-cd81063d654b

Set Property Value Example:

mesObject = system.mes.loadMESObject('unload Vinegar', 'ProcessSegment')
mesObject.setPropertyValue('Description', 'This is my new description')

Custom Property Script Functions

addCustomProperty(name, dataTypeName)

Add a custom property to the MES object. To add a nested custom property, use
addCustomProperty(propertyPath, name, dataTypeName)
parameters
name

The name of the new custom property.

Data Type String
dataTypeName
The name of the Ignition data type.
Options:
Int2
Int4
Int8
Float4
Float8
Boolean
String
DateTime

Data Type String

returns
None

addCustomProperty(name, dataTypeName, description, units, productionVisible, required)

Add a custom property to the MES object specifying all of the options. To add a nested custom
property, use addCustomProperty(propertyPath, name, dataTypeName, description, units,
productionVisible, required)
parameters
name

The name of the new custom property.

Data Type String
dataTypeName
Inductive Automation

Track and Trace

185

The name of the Ignition data type.

Options:
Int2
Int4
Int8
Float4
Float8
Boolean
String
DateTime

Data Type String

description

A description for the custom property.

Data Type String
units

The unit for the custom property. This will show in the track and
trace components.
Data Type String

productionVisible

If true, the custom property will show in the track and trace
components.
Data Type Boolean
required

If true, a value must be entered when ending a Response

Segement.
Data Type Boolean

returns
None

addCustomProperty(propertyPath, name, dataTypeName)

Add a custom property to an existing custom property.

parameters
propertyPath

The path to the custom property to add the new custom

property to.
Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to
used to add new Width and Height custom properties is
"Dimensions"
Data Type String
name

The name of the new custom property.

Data Type String
dataTypeName
The name of the Ignition data type.
Options:
Inductive Automation

Track and Trace

186

Int2
Int4
Int8
Float4
Float8
Boolean
String
DateTime

Data Type String

returns
None

addCustomProperty(propertyPath, name, dataTypeName, description, units, productionVisible,

required)

Add a custom property to an existing custom property specifying all of the options.
parameters
propertyPath

The path to the custom property to add the new custom

property to.
Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to
used to add new Width and Height custom properties is
"Dimensions"
Data Type String

name

The name of the new custom property.

Data Type String
dataTypeName
The name of the Ignition data type.
Options:
Int2
Int4
Int8
Float4
Float8
Boolean
String
DateTime

Data Type String

description

A description for the custom property.

Data Type String
units

The unit for the custom property. This will show in the track and
trace components.
Data Type String
Inductive Automation

Track and Trace

187

productionVisible

If true, the custom property will show in the track and trace
components.
Data Type Boolean
required

If true, a value must be entered when ending a Response

Segement.
Data Type Boolean

returns
None

renameCustomProperty(propertyPath, newName)

Add a custom property to an existing custom property.

parameters
propertyPath

The path to the custom property to rename.

Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
newName

The name to rename the custom property to.

Data Type String
returns
None

setCustomPropertyEnabled(propertyPath, enable)

Set the enabled state of an existing custom property. To maintain historical data integrity,
custom properties are not deleted. Instead setting the enabled state to False will cause it not to
be shown or used.
parameters
propertyPath

The path to the custom property to rename.

Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
enable

Set to True to enable the custom property, which is the default

state, or False to disable.
Inductive Automation

Track and Trace

188

Data Type Boolean

returns
None

getCustomPropertyEnabled(propertyPath)

Get the enabled state of an existing custom property.

parameters
propertyPath

The path to the custom property to rename.

Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
returns
None

The current enabled state of the custom property.

Data Type Boolean
setCustomPropertyDescription(propertyPath, description)

Set the description for an existing custom property.

parameters
propertyPath

The path to the custom property to set the description for.

Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
description

A description for the custom property.

Data Type String
returns
None

getCustomPropertyDescription(propertyPath)

Get the description of an existing custom property.

parameters
Inductive Automation

Track and Trace

189

propertyPath

The path to the custom property to return the description for.

Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
returns
None

The current description.

Data Type String
setCustomPropertyUnits(propertyPath, units)

Set the units for an existing custom property.

parameters
propertyPath

The path to the custom property to set the units for.

Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
units

Units for the custom property.

Data Type String
returns
None

getCustomPropertyUnits(propertyPath)

Get the units of an existing custom property.

parameters
propertyPath

The path to the custom property to return the units for.

Example: if a custom property, say Dimensions, has child
properties, say Width and Height, then the property path to Width
is
"Dimensions.Width"
Data Type String
returns
None

The current units.

Inductive Automation

Track and Trace

190

Data Type String

Add Custom Property Example:
mesObject = system.mes.loadMESObject('unload Vinegar', 'ProcessSegment')
mesObject.addCustomProperty('Dimension', 'String')
mesObject.addCustomProperty('Dimension', 'Width', 'Int4')
mesObject.addCustomProperty('Dimension', 'Height', 'Int4')
mesObject.setPropertyValue('Dimension.Width', 25)
mesObject.setPropertyValue('Dimension.Height', 33)
print mesObject.getPropertyValue('Dimension.Width')
print mesObject.getPropertyValue('Dimension.Height')

output
25
33

Complex Property Script Functions

Complex properties are used to hold material, equipment, personnel and lot resources in the Process
Segment, Operations Segment and Response Segment MES object types. They are also used to hold
segment references in the Operations Definition and Operation Response MES object types.
In general they are named complex properties because they have a number of members and there can
be multiple instances for a given complex property type. A Process Segment to mix dressing will have
multiple material references. Each one will be an instance of a Material complex property. Even more
complex is the Lot complex property used by the Response Segment for mixing dressing, because there
will be multiple lots for each input material each with their own complex property base name. Then, if an
input material lot is used up during production and switched over to another input lot, then there will be
multiple instances for the same input lot reference.
An example will help clarify this concept. If we are mixing dressing which requires vinegar that is coming
from Lot 123 in vinegar tank 1, then there will be an instance of Lot complex property for it. This complex
property has a name to reference it by, and in this example we will call it "Ingredient Vinegar". Then during
production of mixing dressing, we run out of vinegar in tank 1 and we switch over to vinegar tank 2.
Vinegar tank 2 contains Lot 234 so there will be another Lot complex property for it with the same name
"Ingredient Vinegar". Now there are two Lot complex properties that are referenced by the same name
"Ingredient Vinegar". Behind the scenes, the name are modified with a post fix. As a result the Lot
complex property for Lot 123 will be named "Ingredient Vinegar-1" and the one for Lot 234 will be named
"Ingredient Vinegar-2". This is referred to as extended naming. Each will hold complete details of when
using the lot start and when it finished, quantity, etc.
createComplexProperty(complexPropertyType, name)

Create a new complex property for the specified type and name. When the new complex
property is created, it is then added to the collection in this function call. The Lot and Person
reference complex properties support extended naming and the name may have a postfix
attached. For example, if you specify Raw Ingredient A, it may return Raw Ingredient A-1.
parameters
complexPropertyName

The complex property type name which to create a new

Inductive Automation

Track and Trace

191

complex property.
Options:
Material
Personnel
Equipment
Lot
SegmentDependency

Data Type String

name

The name of the new complex property.

Data Type String
returns

The number of entries for the specified complex property

Data Type AbstractMESComplexProperty

removeComplexProperty(complexPropertyType, name)

Remove the specified complex property for the specified type and name.
parameters
complexPropertyName

The complex property type name which to remove.

Options:
Material
Personnel
Equipment
Lot
SegmentDependency

Data Type String

name

The name of the new complex property to remove.

Data Type String
returns
None

renameComplexProperty(complexPropertyType, name, newName)

Rename the existing specified complex property to the new name.

parameters
complexPropertyName

The complex property type name which to create a new

complex property.
Options:
Material
Personnel
Inductive Automation

Track and Trace

192

Equipment
Lot
SegmentDependency

Data Type String

name

The existing name of the complex property.

Data Type String
newName

The new name of the complex property.

Data Type String
returns
None

getComplexPropertyTypeNames()

Get a list containing the names of the complex properties of the MES object. Depending on the
type of MES object, the names that can be included in the list are Material, Personnel,
Equipment, Lot or SegmentDependency.
parameters
None

returns

A list of strings containing the complex property names.

Data Type List of Strings

getComplexPropertyCount(complexPropertyName)

Get the number of entries that exist for the specified complex property name. The name is one
of the values returned by the getComplexPropertyTypeNames()
parameters
complexPropertyName

The complex property name which to return the count of the

number of entries that exist for it.
Options:
Material
Personnel
Equipment
Lot
SegmentDependency

Data Type String

returns

The number of entries for the specified complex property

Data Type Integer
getComplexProperty(complexPropertyName, index)
Inductive Automation

Track and Trace

193

Get the complex property for the specified complex property type by index.
parameters
complexPropertyName

The complex property type name which to return complex

property for.
Options:
Material
Personnel
Equipment
Lot
SegmentDependency

Data Type String

index

The index of the complex property to return.

Data Type Integer
returns

A instance of a complex property

Data Type AbstractMESComplexProperty

getComplexProperty(complexPropertyName, name)

Get the complex property for the specified complex property type by name.
parameters
complexPropertyName

The complex property type name which to return complex

property for
Options:
Material
Personnel
Equipment
Lot
SegmentDependency

Data Type String

name

The name of the complex property to return.

Data Type String
returns

A instance of a complex property

Data Type AbstractMESComplexProperty

Get Complex Property Types Example:

mesObject = system.mes.loadMESObject('unload Vinegar', 'ProcessSegment')
typeNameList = mesObject.getComplexPropertyTypeNames()
for typeName in typeNameList:
Inductive Automation

Track and Trace

194

cnt = mesObject.getComplexPropertyCount(typeName)
print typeName, ": ", cnt

output
Material : 1
Equipment : 1
Personnel : 1

Iterate Complex Properties Example:

mesObject = system.mes.loadMESObject('unload Vinegar', 'ProcessSegment')
typeNameList = mesObject.getComplexPropertyTypeNames()
for typeName in typeNameList:
cnt = mesObject.getComplexPropertyCount(typeName)
print
print typeName, ": ", cnt
for ndx in range(cnt):
complexProp = mesObject.getComplexProperty(typeName, ndx)
print complexProp.getName(), ", ", complexProp.getMESPropertyID().getName()

output
Material : 1
Raw Material ,

Material

Equipment : 1
Unload Station ,

Equipment

Personnel : 1
Operator , Personnel

2.8.3.3

Parent/Child Script Functions

The AbstractMESObject object can have parent and child MES objects. The functions listed in this
section are for adding to, removing from and getting collection of parent or child MES object.
All of the functions detailed below act on a MES object. This means that a variable of an MES object is
needed and then the function is called on that variable.

Parent/Child Script Functions

addParent(parentMESObject)

Add a MES object as a parent to a MES object. For example, to add a Material Class, say
Toxic, to a Material Definition, say HCL, then the Toxic MES object can be added as a parent to
the HCL MES object.
parameters
parentMESObject

The MES object to add as a parent.

Data Type

AbstractMESObject

returns
None

addParent(parentMESObjectLink)
Inductive Automation

Track and Trace

195

Based on a MESObjectLink, add a MES object as a parent to a MES object. In cases where an
instance of a MES object is not available, a parent MES object can be added to a MES object
without the overhead of loading the parent MES object.
parameters
parentMESObjectLink

The MES object link to add as a parent.

Data Type

MESObjectLink

returns
None

removeParent(parentMESObject)

Remove a parent MES object from a MES object.

parameters
parentMESObject

The parent MES object to remove.

Data Type

AbstractMESObject

returns
None

getParentCollection()

Return the collection of MES objects that are parents of a MES object.
parameters
None

returns

A collection of MES objects.

Data Type

MESObjectCollection

addChild(childMESObject)

Add a MES object as a child to a MES object. For example, to add a Material Definition, say
HCL, to a Material Class, say Toxic, then the HCL MES object can be added as a child to the
Toxic MES object.
parameters
childMESObject

The MES object to add as a child.

Data Type
returns
Inductive Automation

AbstractMESObject

Track and Trace

196

None

addChild(childMESObjectLink)

Based on a MESObjectLink, add a MES object as a child to a MES object. In cases where an
instance of a MES object is not available, a child MES object can be added to a MES object
without the overhead of loading the child MES object.
parameters
childMESObjectLink

The MES object link to add as a child.

Data Type

MESObjectLink

returns
None

removeChild(childMESObject)

Remove a child MES object from a MES object.

parameters
childMESObject

The child MES object to remove.

Data Type

AbstractMESObject

returns
None

getChildCollection()

Return the collection of MES objects that are children of a MES object.
parameters
None

returns

A collection of MES objects.

Data Type

MESObjectCollection

Add Child Example:

parentMESObject = system.mes.loadMESObject('Toxic', 'Material Class');
childMESObject = system.mes.createMESObject('Material Definition')
childMESObject.setPropertyValue('Name', 'HCL')
parentMESObject.addChild(childMESObject)

Inductive Automation

Track and Trace

197

Iterate Children Example:

parentMESObject = system.mes.loadMESObject('Vinegar', 'MaterialClass')
childList = parentMESObject.getChildCollection().values()
for childMESObject in childList:
print childMESObject.getName()

output
Red Wine Vinegar
Balsamic Vinegar

2.8.4

Events

Each of the different MES object types have events that are run during the life cycle of the object. All MES
object types support the New event that is run every time a new instance is created. This is great place to
add custom properties for a given MES object type every time a new one is created.
Depending on the type of MES object, there maybe additional events that are run. For example, the
Material Lot MES object has an event that is run every time a new lot number is generated.
In addition to the system events, custom events can be configured in the designer on the General
Settings section for the Enterprise production item. Custom events have to be run form script, but provide
a common area to include custom functionality.

Common Events
The events are defined in the Ignition Designer in the ProductionModel section.

Setting Name
New

Description
This event is run every time a new MES object is created. It can be used to add
custom properties or to perform other task.

Example of Executing a Custom MES Event

mesObject = system.mes.loadMESObject('VIN 3344', 'MaterialLot')
if mesObject != None:
params = system.mes.object.parameters.create()
params.put('Kind', 'Dressing')
params.put('Priority', 'High')
system.mes.executeMESEvent(mesObject, 'My User Event', params)

See MESObjectEventParameters for more information.

2.8.5

MaterialClass

The Material Class object is used as a category that can have Material Class or Material Definition objects
as children. It provides a method to organize material definitions into categories and then later refer to a
group of material definitions as a category.
Inductive Automation

Track and Trace

198

Core Properties
Besides the common core properties, no other core properties exist for the Material Class.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Material Class.

Events
Besides the common MES object events, no other events exist for the Material Class.

2.8.6

MaterialDef

An object used to define material that can have Material Definition objects as children.

Core Properties
Besides the common core properties, no other core properties exist for the Material Definition.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Material
Definition.

Events
Besides the common MES object events, no other events exist for the Material Definition.

2.8.7

PersonnelClass

An object used as a category that can have Personnel Class or Person objects as children.

Core Properties
Besides the common core properties, no other core properties exist for the Personnel Class.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Personnel Class.

Events
Besides the common MES object events, no other events exist for the Personnel Class.

2.8.8

Person

An object used to define people and cannot have children.The Person object is automatically created
when the MES system is first started up and on a one hour interval. This can also be triggered at any time
using a script function. A Person object will be created for each user with a first and last name configured
in the Ignition user profile that is set for the MES modules.
Inductive Automation

Track and Trace

199

Core Properties
Besides the common core properties, the following core properties exist for Person objects.

Setting Name

Description

Person User Name

The user name that the user logs in with.

Person First Name

The users first name that is configured in the Ignition user profile.

Person Last Name

The users last name that is configured in the Ignition user profile.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Person.

Events
Besides the common MES object events, no other events exist for the Person.

2.8.9

MaterialLot

An object used to hold lot information that can have Material Sublot objects as children..

Core Properties
Besides the common core properties, the following core properties exist for Equipment objects.

Setting Name
Material UUID

Description
The UUID of the Material Definition to assign to the Material Lot object.

Response Segment UUID

The UUID of the Response Segment that created the Material Lot object.

Lot Assembly Type

Currently this is here for reference and is included to align with the ISA-95
standard and will become significant in the next phase of the Track and Trace
Module.

Lot Status

The status of the Material Lot object. When a Material Lot object is currently
being processed by a Response Segment, this will be set to Active. When the
Response Segment is ended, this will be set to the Final Lot Status setting in
the Operation Segment configuration. If a Final Lot Status is not defined, it will
be set to the default status of Complete.

Lot Location Reference Type

This is the type of equipment of where the lot is located.

Lot Location Reference UUID

This is the UUID for the specific equipment of where the lot is located.

Lot Units

The unit for the lot quantity. Notice, that there is not a quantity setting for the
Material Lot object. This is because the quantities are kept in the lot resource
properties of the Response Segment object. The reason for this is that a many
Response Segments may pull product from a single lot and it will have to be

Inductive Automation

Track and Trace

200

continually updated. In addition, details of how much a given Response

Segment used of a lot still has to be maintained and storing quantities in the
Material Lot object will be redundant which is never good.
Lot Sequence

The sequence property is incremented every time a new Material Lot is created
for a given lot number. This makes it unique as an unchanging lot number flows
through a manufacturing facility.

Material Reference UUID

The UUID of the Material Definition to assign to a Material Lot object.

Material Reference Type

The Type of the Material Definition to assign to a Material Lot object.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Material Lot.

Events
Besides the common MES object events, the following events exist for Material Lot objects.

Setting Name
CreateLotNumber

Description
This event is run every time a Material Lot object is requested to create a new lot number.
This event provides a method to intercept the generation of lot numbers so that the format of
the lot number or even the number itself can be modified. For systems that retrieve lot
numbers from a ERP or other system, this event will allow obtaining a lot number from it.
Script in this event can also read from a block of available lot numbers that are maintained in
a database.

2.8.10 MaterialSublot
An object used to hold lot information that can have Material Sublot objects as children..

Core Properties
Besides the common core properties, the following core properties exist for Equipment objects.

Setting Name

Description

Lot Assembly Type

Currently this is here for reference and is included to align with the ISA-95
standard and will become significant in the next phase of the Track and Trace
Module.

Sublot Status

The status of the Material Sublot object. When a Material Sublot object is
currently being processed by a Response Segment, this will be set to Active.
When the Response Segment is ended, this will be set to the Final Lot Status
setting in the Operation Segment configuration. If a Final Lot Status is not
defined, it will be set to the default status of Completed.

Inductive Automation

Track and Trace

201

Script Functions
Besides the common MES object script functions, no other script functions exist for the Material Sublot.

Events
Besides the common MES object events, the following events exist for Material Sublot objects.

Setting Name
CreateSerialNumber

Description
This event is run every time a Material Sublot object is requested to create a
new serial number. This event provides a method to intercept the generation of
serial numbers so that the format of the serial number or even the number
itself can be modified. For systems that retrieve serial numbers from a ERP or
other system, this event will allow obtaining a serial number from it. Script in
this event can also read from a block of available serial numbers that are
maintained in a database.

2.8.11 EquipmentClass
An object used as a category that can have Equipment Class, MES Enterprise, MES Site, MES Area,
MES Line, MES Line Cell, MES Line Cell Group, MES Storage Zone or MES Storage Unit objects as
children.

Core Properties
Besides the common core properties, no other core properties exist for the Equipment Class.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Equipment
Class.

Events
Besides the common MES object events, no other events exist for the Equipment Class.

2.8.12 Equipment
An object used to define soft or rolling equipment that can be included for a segment. This is not a
equipment that resides in the production model that is defined in the Ignition designer. The reason
equipment is defined in the Ignition designer is because tags are used to collect production data,
downtime, SPC sample data, etc. for it. Tags cannot be assigned in the designer and involves
configuration from the control system, through the OPC server and tags to the equipment defined in the
production model.
Inductive Automation

Track and Trace

202

Core Properties
Besides the common core properties, the following core properties exist for Equipment objects.

Setting Name
Equipment Path

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Equipment.

Events
Besides the common MES object events, no other events exist for the Equipment object.

2.8.13 ProcessSegment
The Process Segment is an object used to hold definition of basic tasks that are performed in a
manufacturing facility. Tasks can be as simple as "produce product", but can be more granular like
changeover line, clean, lab inspection, heat up, pre-production, produce product and run out line.

Core Properties
Besides the common core properties, no other core properties exist for the Process Segment.

Inductive Automation

Track and Trace

203

Material Resource Property

Material resource properties are added as needed to defined the materials feeding into or out of a
Process Segment. The setting name is what appears in the MES Object Editor component and the script
name is what is used to set or get the value using script. See AbstractMESComplexProperty for details
about accessing values using script.

Setting Name

Script Name

Material Name

Material Reference
Type

Description
This is the name to refer to this material resource by.
Many process segments have multiple material
resources and this is a unique name displayed to the
operator, shown in analysis and reports, and also
internally used to reference this material resource.

MaterialRef
MaterialRefType

MES Object Name

This can be set to a Material Class or a Material

Definition. By setting this to Material Class will cause
the operator to be prompted for the specific material for
this material resource. If set to a Material Definition,
then the selection will be automatically selected.
Depending on the setting of the type, Material Class or
Material Definition options will show. When Process
Segments or Operations Segments are inherited from a
Process Segment, then the options that show for the
Material Reference setting will by limited by the parent
settings.
For example: If Vinegar Material class is selected for a
Process Segment and a new child Process Segment is
created from it, then the only options will be limited to
the Vinegar Material Class and any child of it.

MaterialRefUUID

UUID of the Material Class or Material Definition

Units

MaterialUnits

This appears to the operator, analysis and reports.

Use

MaterialUse

This is a very important setting and complete

understanding of the possible options is critical.
Options
In - is used for material feeding into a segment that will
be part of the finished goods.
Out - is used for material feeding out of a segment that
is or will be part of the finished goods.
Consumable - is used for material feeding into a
segment that is not part of the finished goods.
By-product - is used for material feeding out of a
segment that is not part of the finished goods.

Lot Number Source

Inductive Automation

MaterialLotNoSource

This determines the source of the lot number.

Track and Trace

204

Options
Manual - prompt the operator for the lot number. This
is typically used when receiving raw materials or
entering a lot number generated by an outside system.
Auto - automatically generated lot number. The internal
lot number generator will generate a lot number and
assign it automatically for the operator. This option can
also be used if a different lot number format is used or
lot numbers are provided by another system that is
integrated with this system.
In Link - In cases where the lot number of output of a
segment will be the same as the lot number of one of
the inputs of the same segment, this setting will tie the
two together. Segments can be configured with multiple
material inputs and outputs and different lot number
links can be configured.
Lot Number Source Link

MaterialLotNoSourceLink

If the Lot Number Source setting is set to In Link, then

this is the name of the material resource to get the lot
number from.

Auto Generate Lot

MaterialAutoGenerateLot

If true, a new lot will be generated for the material

output of a segment. This is typically only done when
receiving material that a lot doesn't already exists.

Lot Equipment Reference

Type

MaterialEquipmentRef
MaterialEquipmentRefType

This is the type of equipment associated with this

material resource. It can be set to a Material Class or a
specific piece of equipment.
In the case where this material resource is an input to
the segment, this will be the equipment where the
material is coming from. This helps establish routes
that exist due to physical machinery. For example if
tanks 1 and 2 can only supply line 1 and tanks 3 and 4
can only supply line 2.

MES Object Name

In the case where this material resource is an output

from the segment, this will be the equipment where the
material is going to. And just like the case of the input,
routes that exist due to physical machinery can be
accommodated.
Depending on the setting of the type, Equipment Class,
Equipment, Line, Line Cell, Line Cell Group or Storage
Unit options will show. When Process Segments or
Operations Segments are inherited from a Process
Segment, then the options that show for the Material
Reference setting will by limited by the parent settings.
For example: If Vinegar Tanks class is selected for a
Process Segment and a new child Process Segment is
created from it, then the only options will be limited to
Inductive Automation

Track and Trace

205

the Vinegar Tanks class and any child of it.

MaterialEquipmentRefUUID

UUID for the Equipment Class or Equipment item.

Quantity

MaterialQuantity

Typically this is left blank, but it can be set to a fixed

value that will be constant every time the segment is
used for production.

Quantity Source

MaterialQuantitySource

This setting determines the source of the quantity for

this material resource.
Options
Auto - Obtain the quantity from the automatic
production counters defined for the associated
equipment. The associated equipment may change if
the Lot Equipment Reference setting is set to a
Material Class and the specific equipment is not known
until the segment is started for production.
Link - This option allows the quantity to come from an
input or output material resource of this segment. This
eliminates the need to type in the quantity multiple
times if they will always be the same as another
material resource.
Manual - The operator will be prompted for the
quantity. The quantity must be entered before the
segment is ended.
Split - For segments that are splitting a lot into two or
more streams, as is the case of separating good from
bad product, this option can be used. It is used by
having two or more material resources, that are
segment outputs, linked to the same material resource.
When the segment is ended, the system will ensure
that the sum of the quantities of the linking material
resources equal that of the linked material resources.
Sublots - The quantity will be automatically set based
on the number of Material Sublot items belonging to the
Material Lot. If sublots are used, then serial numbers,
or other unique identification number, can be assigned
to each sublot item.
For example, a Material Lot of batteries maybe have 25
individual batteries each with a serial number and each
with their own test results. The quantity of the Material
Lot will match the number of Material Sublot items of
the Material Lot. Or, the number of batteries in the lot.
Combine - For segments that are combining two or
more lots into one streams, as is the case of joining
goods after tests are done to only a portion of a lot, this
option can be used. It is used by having two or more
material resources, that are segment inputs, linked to

Inductive Automation

Track and Trace

206

the same material resource output. When the segment

is ended, the system will sum of the quantities of the
linked material resources to that of the linking material
resources.
Quantity Source Link

MaterialQuantitySourceLink This is used when the Quantity Source setting is set to

Link, Split or Combine. It is the name of the material
resource to link to of this segment.

Final Lot Status

MaterialFinalLotStatus

When a segment is started, the status of the Material

Lots will be set to Active. When the segment is ended
or a new lot is used for the material resource, the
status will be set to Complete. Optionally, the this value
of this setting can used instead of the default Complete.
Please note, the Active status while the lot is active
cannot be changed.
This is useful for setting a lot to Hold, In Process or
anything that can be used to filter lots or sublots.

Enable Sublots

MaterialEnableSublots

If this setting is selected, than sublot support will be

enabled for the material resource. If sublots are used,
then serial numbers, or other unique identification
number, can be assigned to each sublot item.
For example, a Material Lot of batteries maybe have 25
individual batteries each with a serial number and each
with their own test results.

Personnel Resource Property

Personnel resource properties are added as needed to defined the people that are required for the
Process Segment. The setting name is what appears in the MES Object Editor component and the script
name is what is used to set or get the value using script. See AbstractMESComplexProperty for details
about accessing values using script.

Setting Name

Script Name

Personnel Name

Personnel Reference
Type

MES Object Name

Description
This is the name to refer to this personnel resource by.
Some process segments have multiple personnel
resources and this is a unique name displayed to the
operator, shown in analysis and reports, and also
internally used to reference this personnel resource.

PersonnelRef
PersonnelRefType

This can be set to a Personnel Class or a Person. By

setting this to Personnel Class will cause the operator to
be prompted for the specific Person for this personnel
resource. If set to a Person, then the selection will be
automatically selected.
Depending on the setting of the type, Personnel Class or
Person options will show. When Process Segments or
Operations Segments are inherited from a Process
Segment, then the options that show for the Personnel
Inductive Automation

Track and Trace

207

Reference setting will by limited by the parent settings.

For example: If Unload Operator Personnel class is
selected for a Process Segment and a new child
Process Segment is created from it, then the only
options will be limited to the Unload Operator Class and
any child of it.
PersonnelRefUUID

UUID of the selected Personnel Class or Person.

Units

PersonnelUnits

This specifies the units for the quantity setting.

Use

PersonnelUse

Currently this is here for reference and is included to

align with the ISA-95 standard and will become
significant in the next phase of the Track and Trace
Module.

Quantity

PersonnelQuanity

Currently this is here for reference and is included to

align with the ISA-95 standard and will become
significant in the next phase of the Track and Trace
Module.

Equipment Resource Property

An equipment resource property is added to defined the equipment that the Process Segment will run on.
The setting name is what appears in the MES Object Editor component and the script name is what is
used to set or get the value using script. See AbstractMESComplexProperty for details about accessing
values using script.

Setting Name

Script Name

Equipment Resource Name

Equipment Reference
Type

MES Object Name

Inductive Automation

Description
This is the name to refer to this equipment resource
by. Some process segments may have multiple
equipment resources and this is a unique name
displayed to the operator, shown in analysis and
reports, and also internally used to reference this
equipment resource.

EquipmentRef
EquipmentRefType

This can be set to a Equipment Class or a

Equipment, Line, Line Cell, Line Cell Group or
Storage Unit. By setting this to Equipment Class will
cause the operator to be prompted for the specific
equipment for this equipment resource. If set to a
specific equipment item, then the selection will be
automatically selected.
Depending on the setting of the type, Equipment
Class or specific equipment item options will show.
When Process Segments or Operations Segments
are inherited from a Process Segment, then the
options that show for the Equipment Reference
setting will by limited by the parent settings.

Track and Trace

208

For example: If Unload Stations class is selected for

a Process Segment and a new child Process
Segment is created from it, then the only options will
be limited to the Unload Stations Class and any child
of it.
EquipmentRefUUID

UUID of the Equipment Class or Equipment item.

Units

EquipmentUnits

This specifies the units for the quantity setting.

Use

EquipmentUse

Currently this is here for reference and is included to

align with the ISA-95 standard and will become
significant in the next phase of the Track and Trace
Module.

Quantity

EquipmentQuantity

Currently this is here for reference and is included to

align with the ISA-95 standard and will become
significant in the next phase of the Track and Trace
Module.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Process
Segment.

Events
Besides the common MES object events, no other events exist for the Process Segment.

2.8.14 OperationsDefinition
The Operations Definition is an object used to hold multiple Operations Segments (basic tasks) into a
operations. Tasks can be as simple as "produce product", but can be more granular like changeover line,
clean, lab inspection, heat up, pre-production, produce product and run out line. If changeover line, clean
line, lab inspection and production are grouped together into an Operations Definition, each can task can
be tracked. In the next phase of the Track and Trace Module, this will be expanded to have control of each
Operations Segment and wether it should be done and when it should be done.

Core Properties
Besides the common core properties, the following core properties exist for Operations Definition objects.

Setting Name
Enable Update Event

Description
When this setting is set to true, the UpdateProgress event for the Response
Segments associated with this Operations Definition will be executed at the
interval set in the Update Event Interval. The UpdateProgress event is defined in
the Ignition Designer in the MES Events section.
Inductive Automation

Track and Trace

Update Event Interval

209

This setting defined the frequency (in mS) to execute the UpdateProgress
event.

Segment Dependency Property

Segment Dependency properties are added as needed to define the Operations Segments that are
associated with the operation. In the MES Object Editor component, the options shown when selecting a
segment are Process Segments. When the Operations Definition is saved, Operations Segments will be
derive from the Process Segment behind the scenes. Existing Operations Segments cannot be added
because the equipment resource properties may not apply.
When creating a new Operations Definition as a child of an existing Operations Definition, new
Operations Segments will be created for each of the parent's Operations Segments. The setting name is
what appears in the MES Object Editor component and the script name is what is used to set or get the
value using script. See AbstractMESComplexProperty for details about accessing values using script.

Setting Name

Script Name

Segment Dependency Name

Description
This is the name to refer to this segment
dependency resource by. Operations
Definitions may have multiple segment
resources and this is a unique name
displayed to the operator, shown in
analysis and reports, and also internally
used to reference this segment
dependency.

Segment Reference

SegmentRef

The reference to the Process Segment or

Operations Segment that this segment
dependency is link to.

Segment Dependency Type

SegmentRefType

Currently this is here for reference and is

included to align with the ISA-95 standard
and will become significant in the next
phase of the Track and Trace Module.

SegmentRefUUID
Segment Dependency Factor

SegmentDependencyFactor

Currently this is here for reference and is

included to align with the ISA-95 standard
and will become significant in the next
phase of the Track and Trace Module.

Segment Dependency Factor Units SegmentDependencyFactorUnits This is the units for the value of the
Segment Dependency Factor setting.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Operations
Definition.
Inductive Automation

Track and Trace

210

Events
Besides the common MES object events, no other events exist for the Operations Definition object.

2.8.15 OperationsSegment
The Operations Segment is an object used to hold definition of basic tasks that are performed in a
manufacturing facility. Tasks can be as simple as "produce product", but can be more granular like
changeover line, clean, lab inspection, heat up, pre-production, produce product and run out line.
Operations Segments are not created directly. Instead, they are derived from a Process Segment or an
existing Operations Segment. This is typically done using the MES Object Editor component, but can also
be done using script functions. When a new Operations Segment is derived from a Process Segment or
Operations Segment, the core, material resource, personnel resource and equipment resource
properties are copied from the derived from Process Segment or Operations Segment object. When
updating the derived from Process Segment or Operations Segment using the MES Object Editor
component, the user will be asked if they want to update the dependencies. If they answer yes, the
changes will be pushed to all Process Segments or Operations Segments that were derived from the
modified Process Segment.

Core Properties
Besides the common core properties, no other core properties exist for the Operations Segment.

Material Resource Property

Material resource properties are added as needed to defined the materials feeding into or out of a
Process Segment.

Setting Name
Material Resource Name

Material Reference
Type

MES Object Name

Description
This is the name to refer to this material resource by. Many process segments
have multiple material resources and this is a unique name displayed to the
operator, shown in analysis and reports, and also internally used to reference
this material resource.

This can be set to a Material Class or a Material Definition. By setting this to

Material Class will cause the operator to be prompted for the specific material
for this material resource. If set to a Material Definition, then the selection will
be automatically selected.
Depending on the setting of the type, Material Class or Material Definition
options will show. When Process Segments or Operations Segments are
inherited from a Process Segment, then the options that show for the Material
Reference setting will by limited by the parent settings.
For example: If Vinegar Material class is selected for a Process Segment and a
new child Process Segment is created from it, then the only options will be
limited to the Vinegar Material Class and any child of it.

Units

This appears to the operator, analysis and reports.

Inductive Automation

Track and Trace

Use

211

This is a very important setting and complete understanding of the possible

options is critical.
Options
In - is used for material feeding into a segment that will be part of the finished
goods.
Out - is used for material feeding out of a segment that is or will be part of the
finished goods.
Consumable - is used for material feeding into a segment that is not part of the
finished goods.
By-product - is used for material feeding out of a segment that is not part of the
finished goods.

Lot Number Source

This determines the source of the lot number.

Options
Manual - prompt the operator for the lot number. This is typically used when
receiving raw materials or entering a lot number generated by an outside
system.
Auto - automatically generated lot number. The internal lot number generator
will generate a lot number and assign it automatically for the operator. This
option can also be used if a different lot number format is used or lot numbers
are provided by another system that is integrated with this system.
In Link - In cases where the lot number of output of a segment will be the same
as the lot number of one of the inputs of the same segment, this setting will tie
the two together. Segments can be configured with multiple material inputs and
outputs and different lot number links can be configured.

Lot Number Source Link

If the Lot Number Source setting is set to In Link, then this is the name of the
material resource to get the lot number from.

Auto Generate Lot

If true, a new lot will be generated for the material output of a segment. This is
typically only done when receiving material that a lot doesn't already exists.

Lot Equipment Reference

Type

This is the type of equipment associated with this material resource. It can be
set to a Material Class or a specific piece of equipment.
In the case where this material resource is an input to the segment, this will be
the equipment where the material is coming from. This helps establish routes
that exist due to physical machinery. For example if tanks 1 and 2 can only
supply line 1 and tanks 3 and 4 can only supply line 2.
In the case where this material resource is an output from the segment, this will
be the equipment where the material is going to. And just like the case of the
input, routes that exist due to physical machinery can be accommodated.

MES Object Name

Inductive Automation

Depending on the setting of the type, Equipment Class, Equipment, Line, Line
Cell, Line Cell Group or Storage Unit options will show. When Process
Segments or Operations Segments are inherited from a Process Segment, then

Track and Trace

212

the options that show for the Material Reference setting will by limited by the
parent settings.
For example: If Vinegar Tanks class is selected for a Process Segment and a
new child Process Segment is created from it, then the only options will be
limited to the Vinegar Tanks class and any child of it.
Quantity

Typically this is left blank, but it can be set to a fixed value that will be constant
every time the segment is used for production.

Quantity Source

This setting determines the source of the quantity for this material resource.
Options
Auto - Obtain the quantity from the automatic production counters defined for
the associated equipment. The associated equipment may change if the Lot
Equipment Reference setting is set to a Material Class and the specific
equipment is not known until the segment is started for production.
Link - This option allows the quantity to come from an input or output material
resource of this segment. This eliminates the need to type in the quantity
multiple times if they will always be the same as another material resource.
Manual - The operator will be prompted for the quantity. The quantity must be
entered before the segment is ended.
Split - For segments that are splitting a lot into two or more streams, as is the
case of separating good from bad product, this option can be used. It is used by
having two or more material resources, that are segment outputs, linked to the
same material resource. When the segment is ended, the system will ensure
that the sum of the quantities of the linking material resources equal that of the
linked material resources.
Sublots - The quantity will be automatically set based on the number of
Material Sublot items belonging to the Material Lot. If sublots are used, then
serial numbers, or other unique identification number, can be assigned to each
sublot item.
For example, a Material Lot of batteries maybe have 25 individual batteries each
with a serial number and each with their own test results. The quantity of the
Material Lot will match the number of Material Sublot items of the Material Lot.
Or, the number of batteries in the lot.
Combine - For segments that are combining two or more lots into one
streams, as is the case of joining goods after tests are done to only a portion of
a lot, this option can be used. It is used by having two or more material
resources, that are segment inputs, linked to the same material resource
output. When the segment is ended, the system will sum of the quantities of
the linked material resources to that of the linking material resources.

Quantity Source Link

This is used when the Quantity Source setting is set to Link, Split or Combine.
It is the name of the material resource to link to of this segment.

Final Lot Status

When a segment is started, the status of the Material Lots will be set to Active.
When the segment is ended or a new lot is used for the material resource, the
status will be set to Complete. Optionally, the this value of this setting can used
Inductive Automation

Track and Trace

213

instead of the default Complete. Please note, the Active status while the lot is
active cannot be changed.
This is useful for setting a lot to Hold, In Process or anything that can be used
to filter lots or sublots.
Enable Sublots

If this setting is selected, than sublot support will be enabled for the material
resource. If sublots are used, then serial numbers, or other unique identification
number, can be assigned to each sublot item.
For example, a Material Lot of batteries maybe have 25 individual batteries each
with a serial number and each with their own test results.

Personnel Resource Property

Personnel resource properties are added as needed to defined the people that are required for the
Process Segment.

Setting Name
Personnel Resource Name

Personnel Reference
Type

MES Object Name

Description
This is the name to refer to this personnel resource by. Some process
segments have multiple personnel resources and this is a unique name
displayed to the operator, shown in analysis and reports, and also internally
used to reference this personnel resource.

This can be set to a Personnel Class or a Person. By setting this to Personnel

Class will cause the operator to be prompted for the specific Person for this
personnel resource. If set to a Person, then the selection will be automatically
selected.
Depending on the setting of the type, Personnel Class or Person options will
show. When Process Segments or Operations Segments are inherited from a
Process Segment, then the options that show for the Personnel Reference
setting will by limited by the parent settings.
For example: If Unload Operator Personnel class is selected for a Process
Segment and a new child Process Segment is created from it, then the only
options will be limited to the Unload Operator Class and any child of it.

Units

This specifies the units for the quantity setting.

Use

Currently this is here for reference and is included to align with the ISA-95
standard and will become significant in the next phase of the Track and Trace
Module.

Quantity

Currently this is here for reference and is included to align with the ISA-95
standard and will become significant in the next phase of the Track and Trace
Module.

Equipment Resource Property

An equipment resource property is added to defined the equipment that the Process Segment will run on.
Inductive Automation

Track and Trace

Setting Name
Equipment Resource Name

Equipment Reference
Type

MES Object Name

214

Description
This is the name to refer to this equipment resource by. Some process
segments may have multiple equipment resources and this is a unique name
displayed to the operator, shown in analysis and reports, and also internally
used to reference this equipment resource.

This can be set to a Equipment Class or a Equipment, Line, Line Cell, Line Cell
Group or Storage Unit. By setting this to Equipment Class will cause the
operator to be prompted for the specific equipment for this equipment resource.
If set to a specific equipment item, then the selection will be automatically
selected.
Depending on the setting of the type, Material Class or specific equipment item
options will show. When Process Segments or Operations Segments are
inherited from a Process Segment, then the options that show for the
Equipment Reference setting will by limited by the parent settings.
For example: If Unload Stations class is selected for a Process Segment and a
new child Process Segment is created from it, then the only options will be
limited to the Unload Stations Class and any child of it.

Units

This specifies the units for the quantity setting.

Use

Currently this is here for reference and is included to align with the ISA-95
standard and will become significant in the next phase of the Track and Trace
Module.

Quantity

Currently this is here for reference and is included to align with the ISA-95
standard and will become significant in the next phase of the Track and Trace
Module.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Operations
Segment.

Events
Besides the common MES object events, no other events exist for the Operations Segment object.

2.8.16 OperationsResponse
The Operations Response is an object that is created behind the scenes anytime a Operations Definition
is selected to begin. It hold the actual production or traceability information. It can also be created from
script and used to begin segments from script and not from the components provided with the Track and
Trace Module. For this reason, there is not a component that can be used to change the properties listed
for the Operations Response.
Inductive Automation

Track and Trace

215

Core Properties
Besides the common core properties, the following core properties exist for Operations Response
objects.

Setting Name

Description

Enable Update Event

When this setting is set to true, the UpdateProgress event for the Response
Segments associated with this Operations Definition will be executed at the
interval set in the Update Event Interval. The UpdateProgress event is defined in
the Ignition Designer in the MES Events section.

Update Event Interval

This setting defined the frequency (in mS) to execute the UpdateProgress event.

Begin Date Time

The date and time the operation started. This setting is set when the operation is
started, and it will automatically be set to the date and time of the Ignition server.

End Date Time

The date and time the operation ended. This setting is set when the operation is
ended, and it will automatically be set to the date and time of the Ignition server.

Operation Reference Type

This setting is automatically set and should not be changed. It will either be set
to Operations Definition or Operations Request depending on how the operation
was started. If the operation was scheduled prior to being run, then it will equal
Operations Request, otherwise it will equal Operations Definition.

Operation Reference UUID

This setting is automatically set and should not be changed. It refers to the UUID
of the Operations Definition or Operations Request, depending on how the
operation was started. If the operation was scheduled prior to being run, then it
will equal the UUID of the Operations Request it is based on, otherwise it will
equal the UUID of the Operations Definition it is based on.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Operations
Response.

Events
Besides the common MES object events, no other events exist for the Operations Response object.

2.8.17 ResponseSegment
The Response Segment is an object that is created behind the scenes anytime a Operations Segment is
selected to begin. It holds the actual production or traceability information. It can also be created from the
script and used to begin segments from script and not from the components provided with the Track and
Trace Module. For this reason, there is not a component that can be used to change the properties listed
for the Response Segment.
Inductive Automation

Track and Trace

216

Core Properties
Besides the common core properties, the following core properties exist for Response Segment objects.

Setting Name

Description

Begin Date Time

The date and time the operation started. This setting is set when the operation
is started, and it will be automatically set to the date and time of the Ignition
server.

End Date Time

The date and time the operation ended. This setting is set when the operation is
ended, and it will be automatically set to the date and time of the Ignition server.

Operation Segment Reference

Type

This setting is automatically set and should not be changed. It will either be set
to Operations Segment or Request Segment depending on how the operation
was started. If the operation was scheduled prior to being run, then it will equal
Request Segment, otherwise it will equal Operations Segment.

Operation Segment Reference

UUID

This setting is automatically set and should not be changed. It refers to the
UUID of the Operations Segment or Request Segment, depending on how the
operation was started. If the operation was scheduled prior to being run, then it
will equal the UUID of the Request Segment it is based on, otherwise it will
equal the UUID of the Operations Segment it is based on.

Operations Response Reference This setting is automatically set and should not be changed. It refers to the
UUID
UUID of the Operations Response this Response Segment is based on.
Running State

This is set by the system and should be changed. The possible values and their
meaning is as follows:

IDLE
RUNNIN
G
COMPLE
TE
ERROR

Segment is not in use.

Segment is currently being used.
Segment has completed and is used in the transition from RUNNING to
IDLE.
An unrecoverable error has occurred in the segment.

Lot Resource Property

A lot resource property is added for every material resource property that is defined in the Operations
Segment or Request Segment that this Response Segment is based on. It represents a lot supplying or
lot output from this Response Segment.
During the life of a Response Segment, multiple lot resource properties maybe created for a single
material resource property of the Operations Segment. This happens if a lot is changed as maybe the
case when a raw material tanks is emptied and changed to another tank.
The setting name is what appears in the MES Object Editor component and the script name is what is
used to set or get the value using script. See AbstractMESComplexProperty for details about accessing
values using script.

Setting Name

Script Name

Description
Inductive Automation

Track and Trace

Lot Resource Name

217

This is the name to refer to this lot resource

by. Many response segments have multiple
lot resources and this is a unique name
displayed to the operator, shown in analysis
and reports, and also internally used to
reference this lot resource.

Lot Reference UUID

LotRefUUID

The UUID of the Material Lot object that this

lot resource is linked to.

Lot Reference Sequence

LotRefSequence

The Material Lot object has a lot sequence

property that is incremented every time a new
Material Lot is created for a given lot number.
This makes it unique as an unchanging lot
number flows through a manufacturing facility.

Lot Number Source

LotNoSource

This determines the source of the lot number.

Options
Manual - prompt the operator for the lot
number. This is typically used when receiving
raw materials or entering a lot number
generated by an outside system.
Auto - automatically generated lot number.
The internal lot number generator will
generate a lot number and assign it
automatically for the operator. This option can
also be used if a different lot number format is
used or lot numbers are provided by another
system that is integrated with this system.
In Link - In cases where the lot number of
output of a segment will be the same as the
lot number of one of the inputs of the same
segment, this setting will tie the two together.
Segments can be configured with multiple
material inputs and outputs and different lot
number links can be configured.

Lot Number Source Link

LotNoSourceLink

If the Lot Number Source setting is set to In

Link, then this is the name of the material
resource to get the lot number from.

Lot Manual Lot Number

LotManualLotNo

The lot number, usually specified by the

operator, to use when the new Material Lot
object that is associated with this lot
resource is created.

Lot Auto Generate Lot

LotAutoGenerate

If true, a new lot will be generated for the

material output of a segment. This is typically
only done when receiving material that a lot
doesn't already exists.

Lot Material Reference UUID

LotMaterialRefUUID

The UUID of the Material Definition to assign

Inductive Automation

Track and Trace

218

to a new Material Lot when the auto generate

lot setting is true.
Lot Begin Date Time

LotBeginDateTime

The date and time that this lot resource

started. In cases

Lot End Date Time

LotEndDateTime

The date and time that this lot resource

ended.

Lot Use

LotUse

This follows the Use setting of the Process

Segment.
Options
In - is used for material feeding into a
segment that will be part of the finished
goods.
Out - is used for material feeding out of a
segment that is or will be part of the finished
goods.
Consumable - is used for material feeding
into a segment that is not part of the finished
goods.
By-product - is used for material feeding out
of a segment that is not part of the finished
goods.

Lot Equipment Reference Type

LotEquipmentRefType

When a Material Lot is not referenced for this

lot resource and a new Material Lot created
this setting will define the type of location of
the new lot.

Lot Equipment Reference UUID

LotEquipmentRefUUID

When a Material Lot is not referenced for this

lot resource and a new Material Lot created
this setting is the UUID of the specific
location of the new lot.

Lot Segment Reference UUID

LotSegmentRefUUID

This is set to the UUID of the Operations

Segment that this Response Segment is
based on.

Lot Allocated Quantity

LotAllocatedQuantity

Currently this is here for reference and is

included to align with the ISA-95 standard
and will become significant in the next phase
of the Track and Trace Module.

Lot Quantity

LotQuantity

The actual quantity for this lot resource. This

can be the current quantity at anytime during
the life of a Response Segment, but will equal
the final production quantity when this lot
resource is finalized.

Lot Quantity Source

LotQuantitySource

This setting determines the source of the

quantity for this material resource.
Inductive Automation

Track and Trace

219

Options
Auto - Obtain the quantity from the automatic
production counters defined for the
associated equipment. The associated
equipment may change if the Lot Equipment
Reference setting is set to a Material Class
and the specific equipment is not known until
the segment is started for production.
Link - This option allows the quantity to
come from an input or output material
resource of this segment. This eliminates the
need to type in the quantity multiple times if
they will always be the same as another
material resource.
Manual - The operator will be prompted for
the quantity. The quantity must be entered
before the segment is ended.
Split - For segments that are splitting a lot
into two or more streams, as is the case of
separating good from bad product, this option
can be used. It is used by having two or more
material resources, that are segment outputs,
linked to the same material resource. When
the segment is ended, the system will ensure
that the sum of the quantities of the linking
material resources equal that of the linked
material resources.
Sublots - The quantity will be automatically
set based on the number of Material Sublot
items belonging to the Material Lot. If sublots
are used, then serial numbers, or other
unique identification number, can be assigned
to each sublot item.
For example, a Material Lot of batteries
maybe have 25 individual batteries each with
a serial number and each with their own test
results. The quantity of the Material Lot will
match the number of Material Sublot items of
the Material Lot. Or, the number of batteries
in the lot.
Combine - For segments that are combining
two or more lots into one streams, as is the
case of joining goods after tests are done to
only a portion of a lot, this option can be
used. It is used by having two or more
material resources, that are segment inputs,
linked to the same material resource output.
When the segment is ended, the system will
Inductive Automation

Track and Trace

220

sum of the quantities of the linked material

resources to that of the linking material
resources.
Lot Quantity Source Link

LotQuantitySourceLink

This is used when the Quantity Source

setting is set to Link, Split or Combine. It is
the name of the material resource to link to of
this segment.

Lot Quantity Units

LotQuantityUnits

The units for the Lot Quantity value

Lot Property Status

LotPropertyStatus

The status of the lot resource. The system

changes this value through the life cycle of a
lot resource property.

BEGI It is a new lot resource property.

NNIN
G
ACTI The lot resource is currently active.
VE
ENDI The lot resource is ending and
NG information will be finalized for it.
COMP The lot resource is complete and is no
LETE longer begin used by the Response
Segment.
UPDA The list of associated Material Sublot
TE_S objects has changed and are being
UBLO updated.
TS
Lot Final Lot Status

LotFinalLotStatus

When a segment is started, the status of the

Material Lots will be set to Active. When the
segment is ended or a new lot is used for the
material resource, the status will be set to
Complete. Optionally, the this value of this
setting can used instead of the default
Complete. Please note, the Active status
while the lot is active cannot be changed.
This is useful for setting a lot to Hold, In
Process or anything that can be used to filter
lots or sublots.

Lot Enable Sublots

LotEnableSublots

If this setting is selected, than sublot support

will be enabled for the material resource. If
sublots are used, then serial numbers, or
other unique identification number, can be
assigned to each sublot item.
For example, a Material Lot of batteries
maybe have 25 individual batteries each with
a serial number and each with their own test
results.

Personnel Resource Property

Inductive Automation

Track and Trace

221

A personnel resource property is added for every personnel resource property that is defined in the
Operations Segment or Request Segment that this Response Segment is based on. It represents an
actual person involved in the Response Segment. The setting name is what appears in the MES Object
Editor component and the script name is what is used to set or get the value using script. See
AbstractMESComplexProperty for details about accessing values using script.

Setting Name

Script Name

Personnel Name

Personnel Reference
Type

Description
This is the name to refer to this personnel resource by.
Some process segments have multiple personnel
resources and this is a unique name displayed to the
operator, shown in analysis and reports, and also
internally used to reference this personnel resource.

PersonnelRef
PersonnelRefType

MES Object Name

This can be set to a Personnel Class or a Person. By

setting this to Personnel Class will cause the operator to
be prompted for the specific Person for this personnel
resource. If set to a Person, then the selection will be
automatically selected.
Depending on the setting of the type, Personnel Class or
Person options will show. When Process Segments or
Operations Segments are inherited from a Process
Segment, then the options that show for the Personnel
Reference setting will by limited by the parent settings.

PersonnelRefUUID

For example: If Unload Operator Personnel class is

selected for a Process Segment and a new child
Process Segment is created from it, then the only
options will be limited to the Unload Operator Class and
any child of it.
UUID of the selected Personnel Class or Person.

Units

PersonnelUnits

This specifies the units for the quantity setting.

Use

PersonnelUse

Currently this is here for reference and is included to

align with the ISA-95 standard and will become
significant in the next phase of the Track and Trace
Module.

Quantity

PersonnelQuanity

Currently this is here for reference and is included to

align with the ISA-95 standard and will become
significant in the next phase of the Track and Trace
Module.

Equipment Resource Property

An equipment resource property is added for every equipment resource property that is defined in the
Operations Segment or Request Segment that this Response Segment is based on. It represents an
actual equipment involved in the Response Segment. The setting name is what appears in the MES
Object Editor component and the script name is what is used to set or get the value using script. See
AbstractMESComplexProperty for details about accessing values using script.
Inductive Automation

Track and Trace

Setting Name

Script Name

Equipment Resource Name

Equipment Reference
Type

222

Description
This is the name to refer to this equipment
resource by. Some process segments may
have multiple equipment resources and this is
a unique name displayed to the operator,
shown in analysis and reports, and also
internally used to reference this equipment
resource.

EquipmentRef
EquipmentRefType

MES Object Name

EquipmentRefUUID

This can be set to a Equipment Class or a

Equipment, Line, Line Cell, Line Cell Group or
Storage Unit. By setting this to Equipment
Class will cause the operator to be prompted
for the specific equipment for this equipment
resource. If set to a specific equipment item,
then the selection will be automatically
selected.
Depending on the setting of the type, Material
Class or specific equipment item options will
show. When Process Segments or
Operations Segments are inherited from a
Process Segment, then the options that
show for the Equipment Reference setting will
by limited by the parent settings.
For example: If Unload Stations class is
selected for a Process Segment and a new
child Process Segment is created from it,
then the only options will be limited to the
Unload Stations Class and any child of it.
UUID of the Equipment Class or Equipment
item.

Units

EquipmentUnits

This specifies the units for the quantity

setting.

Use

EquipmentUse

Currently this is here for reference and is

included to align with the ISA-95 standard
and will become significant in the next phase
of the Track and Trace Module.

Quantity

EquipmentQuantity

Currently this is here for reference and is

included to align with the ISA-95 standard
and will become significant in the next phase
of the Track and Trace Module.

Script Functions
Besides the common MES object script functions, no other script functions exist for the Response
Segment.

Inductive Automation

Track and Trace

223

Events
Besides the common MES object events, the following events exist for Response Segment objects.

Setting Name

Description

BeginTrace

This event is run every time a Response Segment object starts. This event provides a
method to perform tasks when a Response Segment begins. Information about the
MES object is passed to the event in a MES Script Event object.

EndTrace

This event is run every time a Response Segment object ends. This event provides a
method to perform tasks when a Response Segment ends. Information about the
MES object is passed to the event in a MES Script Event object.

UpdateProgress

This event is run at an interval defined by the Update Event Interval in the Operations
Definition. The Enable Update Event setting must also be set to true. This event
provides a method to update production counts or other information associated with
an active Response Segment. Information about the MES object is passed to the
event in a MES Script Event object.

2.8.18 MESEnterprise
An object that is based on the MES Enterprise configured in the production model which is done in the
designer. The MES Enterprise object is automatically created when the MES system is first started up.
Operations cannot be run at a MES Enterprise. The MES Enterprise is used for enterprise operations and
analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Enterprise object.

Setting Name
Equipment Path

Inductive Automation

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Track and Trace

224

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Enterprise.

Events
Besides the common MES object events, no other events exist for the MES Enterprise object.

2.8.19 MESSite
An object that is based on the MES Site configured in the production model which is done in the designer.
The MES Area object is automatically created when the MES system is first started up. Operations
cannot be run at a MES Site. The MES Site is used for enterprise operations and analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Site object.

Setting Name
Equipment Path

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Inductive Automation

Track and Trace

225

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Site.

Events
Besides the common MES object events, no other events exist for the MES Site object.

2.8.20 MESArea
An object that is based on the MES Area configured in the production model which is done in the
designer. The MES Area object is automatically created when the MES system is first started up.
Operations cannot be run at a MES Area. The MES Area is used for analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Site object.

Setting Name
Equipment Path

Inductive Automation

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Track and Trace

226

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Area.

Events
Besides the common MES object events, no other events exist for the MES Area object.

2.8.21 MESLine
An object that is based on the MES Line configured in the production model which is done in the designer.
The MES Line object is automatically created when the MES system is first started up. Operations can be
run at a MES Line. The MES Line can also be used for operations and analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Line object.

Setting Name
Equipment Path

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Inductive Automation

Track and Trace

227

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Line.

Events
Besides the common MES object events, no other events exist for the MES Line object.

2.8.22 MESLineCell
An object that is based on the MES Line Cell configured in the production model which is done in the
designer. The MES Line Cell object is automatically created when the MES system is first started up.
Operations can be run at a MES Line Cell. The MES Line Cell can also be used for operations and
analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Line Cell object.

Setting Name
Equipment Path

Inductive Automation

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Track and Trace

228

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Line Cell.

Events
Besides the common MES object events, no other events exist for the MES Line Cell object.

2.8.23 MESLineCellGroup
An object that is based on the MES Line Cell Group configured in the production model which is done in
the designer. The MES Line Cell Group object is automatically created when the MES system is first
started up. Operations can be run at a MES Line Cell Group. The MES Line Cell Group can also be used
for operations and analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Line Cell Group object.

Setting Name
Equipment Path

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Inductive Automation

Track and Trace

229

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Line Cell
Group.

Events
Besides the common MES object events, no other events exist for the MES Line Cell Group object.

2.8.24 MESStorageZone
An object that is based on the MES Storage Zone configured in the production model which is done in the
designer. The MES Storage Zone object is automatically created when the MES system is first started up.
Operations cannot be run at a MES Storage Zone. The MES Storage Zone is used for analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Storage Zone object.

Setting Name
Equipment Path

Inductive Automation

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Track and Trace

230

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Storage
Zone.

Events
Besides the common MES object events, no other events exist for the MES Storage Zone object.

2.8.25 MESStorageUnit
An object that is based on the MES Storage Unit configured in the production model which is done in the
designer. The MES Storage Unit object is automatically created when the MES system is first started up.
Operations can be run at a MES Storage Unit. The MES Storage Unit can also be used for operations and
analysis.

Core Properties
Besides the common core properties, the following core properties exist for MES Storage Unit object.

Setting Name
Equipment Path

Description
The equipment path is based on the hierarchy in the item in the production model. Referring
to the image below, the equipment path for Bottling Line 1, is "Dressings
Inc\California\Bottling\Bottling Line 1". Equipment paths are used by some of the MES
components and script functions to easily identify equipment items.

Inductive Automation

Track and Trace

231

Script Functions
Besides the common MES object script functions, no other script functions exist for the MES Storage
Unit.

Events
Besides the common MES object events, no other events exist for the MES Storage Unit object.

Inductive Automation

Track and Trace

2.9

232

Scripting

This section is a reference for scripting functions provided by the Track and Trace Module. It also has a
reference for any objects that are used by or returned by the scripting functions.

2.9.1

Basics

This section covers some basic concepts that are useful when using track and trace scripting functions.
2.9.1.1

MESObjectTypes

The MESObjectTypes object has some helpful functions when working with MES objects. Both the
AbstractMESObject and the MESObjectLink objects have a getMESObjectType() function the get the type
of a MES object. With the returned type the following functions can be called.
getName()

Returns the name of the MES object type. This will be a short name without spaces.
parameters
None

returns

The name of the MES object type

Data Type String

getDisplayName()

Return the display name of the MES object type. This will be the long name with spaces.
parameters
None

returns

The name of the MES object type

Data Type

String

getDescription()

Returns description for the MES object type.

parameters
None

returns

The description of the MES object type.

Data Type String

Inductive Automation

Track and Trace

233

getTypeFromName(name)

Returns a MESObjectTypes object for the specified type name.

parameters
name

The short name of the MES object type.

Data Type String
returns

The a MESObjectTypes object

Data Type MESObjectTypes

2.9.1.2

UUIDs

Each MES object and even other properties or data has to be uniquely identified. The typically method of
doing this is to use an identification number generated by the database, which a integer, starting at 1 and
increasing over time. But, this method becomes a problem when data from multiple systems, that each
have their own database that are generating identification numbers, is push up to an enterprise or higher
level system. In the database of the enterprise or higher level system, the identification numbers will have
duplicates which causes inconsistencies of historical data.
For this reason, the Ignition MES system uses Universally Unique Identifiers (UUID). A UUID represents a
128-bit value that the enables distributed systems to uniquely identify information without significant
central coordination. Information identified with a UUID can therefore be combined into a single database
without needing to be concerned about duplicates.
Even though true UUIDs are a data type of their own, all UUID values within the Ignition MES modules are
strings.
Sample UUID value: 5253ccae-47b4-4dc2-954f-900ffa8636eb

Tip: M enta lly, it is ha rd to keep tra ck of the full U U ID va lue, so usua lly the la st 3 or 4 dig its w ill be unique a nd is
ea sier to keep tra ck in ones hea d.
2.9.1.3

AbstractMESObject

There are many different types of MES objects in the Ignition MES system. All of these are inherited from
the AbstractMESObject. Many of the scripting functions and properties refer to the common
AbstractMESObject objects. The specific MES object types can be obtained by using the
getMESObjectType() method on the object.
Example:
filter = system.mes.object.filter.createFilter()
filter.setMesObjectNamePattern('Vinegar')
list = system.mes.searchMESObjects(filter)
for ndx in range(list.size()):
Inductive Automation

Track and Trace

234

mesObject = list.get(ndx)
print mesObject.getMESObjectType().getDisplayName()

2.9.2

Client / Gateway Scripts

The Track and Trace Module exposes many script functions that support tracking product, obtaining trace
results and other associated functions. In fact, the internal functions used by all of the track and trace
components are exposed as script functions that can be used on the client or the gateway.
In the Ignition script editor, the documentation for the script functions can be accessed by pressing
control-space after typing in "system.". For all the track and trace script functions, type in "system.mes."
and press control-space to see the associated function and documentation.

Ignition Script Auto Docum ent Feature

2.9.2.1

Operations

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.1.1 getAvailableOperations

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
Inductive Automation

Track and Trace

235

2.9.2.1.2 getAvailableReferenceOptions

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.1.3 createOperation

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.1.4 beginOperation

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.1.5 endOperation

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.1.6 getCurrentOperation

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.1.7 getAvailableSegments

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.

Inductive Automation

Track and Trace

236

2.9.2.1.8 getOperationSegments

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.2

Segments

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.2.1 createSegment

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.2.2 executeSegment

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.2.3 beginSegment

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.2.4 endSegment

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
during import.")

2.9.2.2.5 getCurrentSegments

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
Inductive Automation

Track and Trace

237

function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.2.6 updateSegment

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.3

Lots

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.3.1 createSublots

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.3.2 getLotList

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4

MES Object Handling

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.1 invalidateCache

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.2 synchronizeMESPersonnel

Under Construction
Inductive Automation

Track and Trace

238

In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.3 updateSegmentDependencies

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.4 createMESObject
system.mes.createMESObject(mesObjectTypeName)

Returns a new instance of a MES object based on the mesObjectType parameter. Generally, MES
objects do not need to be created in script because they are typically handled by the system. But, it is
provided for those situations that fall outside of the normal functionality of the system.
This script function can be used in both gateway and client scripts.
parameters
mesObjectTypeName The MES object type to base the new instance. This can be one of

MES object types defined in MESObjectTypes.

Data Type
String

returns
AbstractMESObject An AbstractMESObject object. The returned AbstractMESObject is a

generic representation of one of the MES Objects. The actual

returned MES Object will be the type that was specified in the
mesObjectTypeName parameter.
In the example below, a new MaterialClass MES object is created. After it is created, the name is set then
a custom property is added to it and then it is saved.
Example
matClass = system.mes.createMESObject('MaterialClass')
matClass.setPropertyValue('Name', 'Turkey')
matClass.addCustomProperty('Weight', 'Float8', 'Weight of the turkey', 'Lbs', True, True)
system.mes.saveMESObject(matClass)

2.9.2.4.5 deriveMESObject

There are two versions of the deriveMESObject script function. The first requires an existing instance of a
MES object to derive from and the second only requires the UUID of an existing MES object to derive
from.
Inductive Automation

Track and Trace

239

Both are used when a new MES object that is based on an existing MES object is needed. For example,
creating a response segment MES object that is based on a process segment. They are two different
MES object types, so the concept of cloning will not apply. After an instance of the new MES object is
created, common properties will be created in it. For example, a process segment MES object will have
one or more material definitions. These will be created in the new instance of the MES object. Based on
the copyPropertyValues parameter, the property values of the common properties will also be copied
across.

Generally, MES objects do not need to be derived in script because they are typically handled by the
system. But, it is provided for those situations that fall outside of the normal functionality of the system.
system.mes.deriveMESObject(mesObject, mesObjectTypeName, copyPropertyValues)

Returns a new instance of a MES object based on the mesObjectType parameter. Generally, MES object
do not need to be created in script because they are typically handled by the system. But, it is provided for
those situations that fall outside of the normal functionality of the system.
This script function can be used in both gateway and client scripts.
parameters
mesObject

The MES object to derive the new MES object from.

Data Type
AbstractMESObject

mesObjectTypeName

The MES object type to base the new instance. This can be one
of MES object types defined in MESObjectTypes.
Data Type
String

copyPropertyValues

If true, copy the values of the properties to the the new MES
object.
Data Type
Boolean

returns
AbstractMESObject

An AbstractMESObject object. The returned AbstractMESObject is

a generic representation of one of the MES Objects. The actual
returned MES Object will be the type that was specified in the
mesObjectTypeName parameter.

In the example below, a new MaterialClass MES object is created. After it is created the name is set, a
custom property is added to it and then it is saved.
Example
matClass = system.mes.createMESObject('MaterialClass')
matClass.setPropertyValue('Name', 'Turkey')
matClass.addCustomProperty('Weight', 'Float8', 'Weight of the turkey', 'Lbs', True, True)
Inductive Automation

Track and Trace

240

system.mes.saveMESObject(matClass)

2.9.2.4.6 loadMESObject

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.7 getMESObjectLink

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.8 getMESObjectChildLinks

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.9 searchMESObjects

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.4.10 saveMESObject

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
value = '99'
system.recipe.setPathRecipeValue(itemPath, recipe, valueName, value, '')

2.9.2.4.11 hasDependencies

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.

Inductive Automation

Track and Trace

2.9.2.5

241

Data and Analysis

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.5.1 executeMESEvent

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.5.2 getInventory

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
Example
csv = system.file.readFileAsString("C:\\Temp\\recipe_export.csv")
itemPath = event.source.parent.getComponent('Production Line Selector').selectedLinePath
system.recipe.importRecipe(csv, "Values set during import.")

2.9.2.5.3 getLotTraceByLotName

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.5.4 getLotTraceByLotUUID

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.5.5 getLotTraceBySublotName

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.

Inductive Automation

Track and Trace

242

2.9.2.5.6 getLotTraceBySublotUUID

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.5.7 getLotInfoByName

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.5.8 getLotInfoByUUID

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
2.9.2.5.9 getSublotInfoByName

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
import.")

2.9.2.5.10 getSublotInfoByUUID

Under Construction
In the meantime, the script auto documentation feature in Ignition provide information about this script
function. See Client / Gateway Scripts for how to access the script auto documentation.
during import.")

2.9.3

Miscellaneous Object Reference

In addition to the MES objects, there are support objects that are used for script functions or when using
functions on the MES objects. An example is the MESLotFilter object where several properties can be set
to narrow down the MES lots to return when using the system.mes.getLotList() script function.
If the MESLotFilter was not provided, then each option would have to be passed as a parameter in the
system.mes.getLotList() call. There are over a dozen options to filter lot on. This would make it vary
difficult to use because the line of script would look something like the following:
Cumbersome method that is NOT used:
system.mes.getLotList('', '000*', '', '', '', '', '', '', '', '', '', beginDate, endDate,'', '', '')

Inductive Automation

Track and Trace

243

Instead, using the MESLotFilter object the script look like:

filter = system.mes.lot.filter.createFilter()
filter.setLotNameFilter('000*')
filter.setBeginDateTime(beginDate)
filter.setEndDateTime(endDate)
list = system.mes.getLotList(filter)

The second example is the supported method and is much more readable.
2.9.3.1

MESObjectLink

The MESObjectLink object is a lite weight version of a fully MES object. Think of it as a reference to the
full MES object. In many cases, just the general information about a MES object is needed instead of the
full details of the MES object. Look at the case of displaying options in the MES object selector
component, where there can be 100 different names to select from. Loading the full details of each MES
object does nothing except generate a lot of unneeded overhead. Instead a reference of each option is
loaded that includes the name, UUID and type of the MES object.
From the MESObjectLink object the full MES object can be loaded by calling the getMESObject() function.
Example
mesObject = mesObjectLink.getMESObject()

methods:
system.mes.object.link.create(mesObject)

Returns a new instance of a MESObjectLink object for the supplied mesObject. This is
typically used when a script function requires a MESObjectLink object as a parameter and the
full MES object exists.
parameters
mesObject

A MES object object to based the new MESObjectLink.

The MES object can be any of the MES objects such
as MaterialClass, MaterialLot, OperationSegment, etc.
that inherit from AbstractMESObject.
Data Type

AbstractMESObject

returns
MESObjectLink

Inductive Automation

A new instance of a MESObjectLink object.

Track and Trace

244

system.mes.object.link.create(mesObjectType, mesObjectUUID)

Returns a new instance of a MESObjectLink object for the supplied mesObjectType and
mesObjectUUID. This is typically used when a script function requires a MESObjectLink
object as a parameter and the MES object type and UUID are known.
parameters
mesObjectType

The type of MES object to create a link for. See MES

Object Types for the available types.
Data Type

mesObjectUUID

MESObjectTypes

The UUID of MES object to create a link for. See UUIDs

for more information.
Data Type

String

returns
MESObjectLink

A new instance of a MESObjectLink object.

system.mes.object.link.create(mesObjectTypeName, mesObjectUUID)

Returns a new instance of a MESObjectLink object for the supplied mesObjectType and
mesObjectUUID. This is typically used when a script function requires a MESObjectLink
object as a parameter and the MES object type and UUID are known.
parameters
mesObjectType

The name of the type of MES object to create a link for.

See MES Object Types for the available types.
Data Type

mesObjectUUID

String

The UUID of MES object to create a link for. See UUIDs

for more information.
Data Type

String

returns
MESObjectLink

A new instance of a MESObjectLink object.

Inductive Automation

Track and Trace

245

system.mes.object.link.create(mesObjectType, mesObjectUUID, name)

Returns a new instance of a MESObjectLink object for the supplied mesObjectType,

mesObjectUUID and name. This is typically used when a script function requires a
MESObjectLink object as a parameter and the MES object type, UUID and name are known.
parameters
mesObjectType

The type of MES object to create a link for. See MES

Object Types for the available types.
Data Type

mesObjectUUID

The UUID of MES object to create a link for. See UUIDs

for more information.
Data Type

name

MESObjectTypes

String

The name of the MES object.

Data Type

String

returns
MESObjectLink

Inductive Automation

A new instance of a MESObjectLink object.

Track and Trace

246

system.mes.object.link.create(mesObjectTypeName, mesObjectUUID, name)

Returns a new instance of a MESObjectLink object for the supplied mesObjectType name,
mesObjectUUID and name. This is typically used when a script function requires a
MESObjectLink object as a parameter and the MES object type, UUID and name are known.
parameters
mesObjectType

The name of the type of MES object to create a link for.

See MES Object Types for the available types.
Data Type

mesObjectUUID

The UUID of MES object to create a link for. See UUIDs

for more information.
Data Type

name

String

String

The name of the MES object.

Data Type

String

returns
MESObjectLink

A new instance of a MESObjectLink object.

invalidateMESObject()

This clears the previously loaded MES object associated with this MESObjectLink. This can
be used to reuse a MESObjectLink object.
parameters
None
returns
Nothing

properties:
hasName()

Returns True if the MES object name is available.

parameters
None
returns
Boolean
Inductive Automation

Track and Trace

247

getName()

Return the MES object name.

parameters
None
returns
String

hasMESObjectInfo()

Returns True if MES object information exists. This includes the MES object type and UUID.
The name is not required for this property to return True.
parameters
None
returns
Boolean
hasMESObject()

Returns True if MES object has been loaded into this MESObjectLink. This will be the case
either after the system.mes.create(mesObject) constructor or the getMESObject() property
of a MESObjectLink object has been called.
parameters
None
returns
Boolean
getMESObjectType()

Returns MES object type that this MESObjectLink object is set to.
parameters
None
returns
MESObjectTypes

Inductive Automation

Track and Trace

248

getMESObjectUUID()

Returns MES object UUID that this MESObjectLink object is set to.
parameters
None
returns
String
getMESObject()

Returns MES object associated with a MESObjectLink object. If the MES object has not been
previously loaded, it will be loaded.
parameters
None
returns
AbstractMESObject

2.9.3.2

MESObjectFilter

The MESObjectFilter object is used to specify the MES objects to return for various components like the
MES Object Selector and script functions.

methods:
system.mes.object.link.createFilter()

Returns a new instance of a MESObjectFilter object for that properties can be set on. This is
typically used when a script function requires a MESObjectFilter object as a parameter.
parameters
returns
MESObjectFilter

A new instance of a MESObjectFilter object.

Inductive Automation

Track and Trace

Example
filter = system.mes.object.filter.createFilter()
filter.setEnableStateName('ENABLED')
filter.setMESObjectTypeName('EquipmentClass')
filter.setMESObjectNamePattern('Unload *')
results = system.mes.loadMESObjects(filter)
for link in results:
print link.getName()

properties:
setMESObjectTypeName(name)

Set the MES object type name to filter the results.

parameters
name

The name of the MES object type to limit the results.

Data Type

returns
Nothing

getMESObjectTypeName()

Return the MES object type name the filter is set for.
parameters
None
returns

St The MES
ri object type
ng name.

Inductive Automation

String

249

Track and Trace

250

setEnableStateName(name)

Set the enable state to filter the results.

parameters
name

The name of the enable state.

Data Type

String

Options:
DISABLED
ENABLED
BOTH
returns
Nothing

getEnabledStateName()

Get the enable state to filter the results.

parameters
None
returns

St The name of
ri the enabled
ng state.
setMESObjectUUIDList(mesObjectUUIDList)

Set the UUIDs of the MES objects to return in the results.

parameters
mesObjectUUIDList

The list of UUIDs to include the the results.

Data Type

List of String

returns
Nothing

Inductive Automation

Track and Trace

251

getMESObjectUUIDList()

Returns a list of MES object UUIDs to return in the results.

parameters
None
returns

List of String

A list of MES object UUIDs.

Example
filter = system.mes.object.filter.createFilter()
list = filter.getMESObjectUUIDList()
list.add('5253ccae-47b4-4dc2-954f-900ffa8636eb')

setPrimaryMESObjectUUID(primaryMESObjectUUID)

Set the UUID of the primary MES object to include in the results. Child MES objects will also be
included in the results.
parameters
primaryMESObjectUUID The UUID of the primary MES object to include the results.

Data Type
returns
Nothing

getPrimaryMESObjectUUID()

Get the UUID of the primary MES object to include in the results.
parameters
None
returns

St The primary
ri MES object
ng UUID.

Inductive Automation

String

Track and Trace

252

setMESObjectNamePattern(mesObjectNamePattern)

Set the MES object name pattern to include in the results. It can contain wildcard characters
including * or ?. The * character can be any characters and the ? character represents any
single character.
parameters
mesObjectNamePattern The MES object name pattern used to filter the results.

Data Type

String

returns
Nothing

getMESObjectNamePattern()

Get the MES object name pattern used to filter the results.
parameters
None
returns

String

The MES object name pattern.

setCustomPropertyNamePattern(customPropertyNamePattern)

Set the custom property name pattern to filter the results. If a MES object contains a custom
property that matches the custom property name pattern, then it will be included in the results.
parameters

customPropertyNamePattern The custom property name pattern used to filter the results

Data Type

String

returns
Nothing

Inductive Automation

Track and Trace

253

getCustomPropertyNamePattern()

Get the custom property name pattern used to filter the results.
parameters
None
returns

St The custom
ri property
ng name pattern.
setCustomPropertyValueFilter(customPropertyValueFilter)

Set the custom property filter expressions to filter the results. If a custom property of a MES
object matches an expression in this list, then it will be included in the results. Use system.
mes.object.filter.parseCustomPropertyValueFilter() script function to create the list
of MESPropertyValueFilter objects.
paramete
rs
customPropertyVal The custom property value list to filter the results.
ueFilter

Data Type
List of
MESPropertyValueFilter
returns
Nothing
Example
filter = system.mes.object.filter.createFilter()
list = system.mes.object.filter.parseCustomPropertyValueFilter('pH > 5.0,Width = 2.5')
filter.s etCustomPropertyValueFilter(list )

getCustomPropertyValueFilter()

Get the list of MESPropertyValueFilter used to filter the results.

paramete
rs
None
returns

List
of
MESPr
opert
yValu
eFilt
er
Inductive Automation

The
custom
property
value list.

Track and Trace

2.9.3.3

254

MESPropertyValueFilter

The MESPropertyValueFilter object is used to define custom property value filters that are used by script
functions.
methods:
system.mes.object.filter.parseCustomPropertyValueFilter(filterExpression)

Parses a string expression and returns a list of MESPropertyValueFilter objects that are used
in filters. The expression consists of the custom property path, a comparison and a constant
value.
The custom property path starts with the MES object types and continues with the route
including nested custom properties to the final custom property to be used in the comparison.
Example Paths:
MaterialLot.pH
MaterialLot.Dimension.Width

The path is followed by a comparison that can be any one of the following:
>

Greater than

>=

Greater than equal

<

Less than

<=

Less than equal

Equal

!=

Not equal

Multiple expressions can be included by separating then with commas. When this is done, all
sub expressions must match for the overall expression to evaluate to true.
Example Expressions:
MaterialLot.pH >= 4.5
MaterialLot.Dimension.Width = 5
ResponseSegment.BreadType = Wheat
MaterialLot.Dimension.Depth >= 6.2,MaterialLot.Dimension.Width = 5

parameters
filterExpression

The custom property filter expression to parse.

Data Type

String

returns
List of
MESPropertyValueFilter

Based on the filterExpression, a list of

MESPropertyValueFilter objects.

Inductive Automation

Track and Trace

255

Example
filter = system.mes.object.filter.createFilter()
list = system.mes.object.filter.parseCustomPropertyValueFilter('pH > 5.0,Width = 2.5')
filter.setCustomPropertyValueFilter(list)
results = system.mes.loadMESObjects(filter)
for link in results:
print link.getName()

properties:
None

2.9.3.4

ModifiedMESProperties

The ModifiedMESProperties object holds the modified properties for a MES object. Whenever properties
of a MES object are changed, only those changes may need to propagated to MES objects that were
derived from the modified MES object. The system.mes.updateSegmentDependencies() script function
takes a ModifiedMESProperties object as a parameter to updated any derived segment dependencies of
the changed properties. By calling the getModifiedMESProperties() function on any MES object, a
ModifiedMESProperties object containing modified properties since the last time it was saved will be
returned.
methods:
None

properties:
None

Example
This is an example of modifying a process segment and updating all Process Segment and
Operations Segment MES objects that derived from it.
mesObject = system.mes.loadMESObject('Unload Vinegar', 'ProcessSegment')
mesObject.setPropertyValue('Description', 'This is a new description')
modProps = mesObject.getModifiedMESProperties()
system.mes.updateSegmentDependencies(mesObject, modProps)

2.9.3.5

MESLotFilter

A MESLotFilter object used to search lots or sublots and is required for certain script methods. Lot or
sublot search results can be limited by known values and this object is used to hold the filter settings.
methods:

Inductive Automation

Track and Trace

256

system.mes.lot.filter.createFilter()

Returns a new instance of a MESLotFilter object for that properties can be set on. This is
typically used when a script function requires a MESLotFilter object as a parameter.
parameters
returns
MESLotFilter

A new instance of a MESLotFilter object.

Example
from java.util import Calendar
filter = system.mes.lot.filter.createFilter()
filter.setModeName('LOT')
filter.setIncludeInactiveLots(True)
beginCal = Calendar.getInstance()
beginCal.add(Calendar.DAY_OF_MONTH, -30)
filter.setBeginDateTime(beginCal)
endCal = Calendar.getInstance()
filter.setEndDateTime(endCal)
results = system.mes.getLotList(filter)
for link in results:
print link.getName()

properties:
setModeName(modeName)

Set the type of results to return. It can be return results for lots (batches) of material or
serialized items (sublots).
parameters
modeName

The name of the mode for the type of results to return.

Data Type

String

Options
LOT
SUBLOT

returns
Nothing

Inductive Automation

Track and Trace

257

getModeName()

Get the type of results to return. It can be return results for lots (batches) of material or
serialized items (sublots).
parameters
None
returns

String

The name of the type of results to return.

setIncludeActiveLots(includeActiveLots)

If set to True, lots or sublot that are actively being processed will be included in the results.
parameters
includeActiveLots If True, include active lots or sublots in results.

Data Type

Boolean

returns
Nothing

includeActiveLots()

If True, lots or sublots currently being processed will be included in the results.
parameters
None
returns

Boolean

If True, active lots will be return in the results.

setIncludeInactiveLots(includeInactiveLots)

If set to True, lots or sublot that are completed will be included in the results.
parameters
includeActiveLots If True, include completed lots or sublots in results.

Data Type
returns
Nothing

Inductive Automation

Boolean

Track and Trace

258

includeInactiveLots()

If True, lots or sublots that are complete will be included in the results.
parameters
None
returns

Boolean

If True, completed lots will be return in the results.

setLotStatusFilter(lotStatusFilter)

Set the custom lot status of results to return. If the Final Lot Status property in a resource
definition of a Process Segment or Operations Segment is set to a custom lot status, it can be
filtered with this property.
parameters
lotStatusFilter Custom lot status value to filter results.

Data Type

String

returns
Nothing

getLotStatusFilter()

Get the custom lot status of results to return.

parameters
None
returns

String

The custom lot status value.

setBeingDateTime(beginDateTime)

Set the beginning date and time to limit results to return. This applies to lots or sublots that are
completed or have a custom lot status.
parameters
beginDateTime

Beginning date and time to filter results.

Data Type

Calendar

returns
Nothing

Inductive Automation

Track and Trace

259

getBeginDateTime()

Get the beginning date and time to limit the results to return.
parameters
None
returns

Calendar

The beginning date and time to filter results.

setEndDateTime(endDateTime)

Set the ending date and time to limit results to return. This applies to lots or sublots that are
completed or have a custom lot status.
parameters
endDateTime

Ending date and time to filter results.

Data Type

Calendar

returns
Nothing

getEndDateTime()

Get the ending date and time to limit the results to return.
parameters
None
returns

Calendar

The ending date and time to filter results.

setMaxResults(maxResults)

Set the maximum results to return. This prevents a large list from being returned which
reduces database operations, memory usage and other resources when most of the time, the
results are not used. If large results are needed, then this property can be increased.
parameters
maxResults

The maximum number of items to return.

Data Type

returns
Nothing

Inductive Automation

Integer

Track and Trace

260

getMaxResults()

Get the maximum number of results to that will returned.

parameters
None
returns

Integer

The maximum number of items to return.

setLotNameFilter(lotNameFilter)

Set the lot name to filter to include in the results. It can contain wildcard characters including *
or ?. The * character can be any characters and the ? character represents any single
character.
parameters
lotNameFilter

The lot name filter used to filter the results.

Data Type

String

returns
Nothing

getLotNameFilter()

Get the lot name filter used to filter the results.

parameters
None
returns

String

The lot name filter.

Inductive Automation

Track and Trace

261

setSublotNameFilter(sublotNameFilter)

Set the sublot name to filter to include in the results. It can contain wildcard characters
including * or ?. The * character can be any characters and the ? character represents any
single character.
parameters
sublotNameFilter

The sublot name filter used to filter the results.

Data Type

String

returns
Nothing

getSublotNameFilter()

Get the sublot name filter used to filter the results.

parameters
None
returns

String

The sublot name filter.

setLotEquipmentNameFilter(lotEquipmentNameFilter)

Set the lot equipment name filter to include lots that were stored in the equipment with a name
that matches this property. It can contain wildcard characters including * or ?. The * character
can be any characters and the ? character represents any single character.
parameters
lotEquipmentNameFilter

The lot equipment name filter used to filter the results.

Data Type

returns
Nothing

Inductive Automation

String

Track and Trace

262

getLotEquipmentNameFilter()

Get the lot equipment name filter used to filter the results.
parameters
None
returns

String

The lot equipment name filter.

setLotEquipmentClassFilter(lotEquipmentClassFilter)

Set the lot equipment class filter to include lots that were stored in the equipment that belong to
the equipment class that matches this property. It can contain wildcard characters including *
or ?. The * character can be any characters and the ? character represents any single
character.
parameters
lotEquipmentClassFilter The lot equipment class filter used to filter the results.

Data Type

String

returns
Nothing

getLotEquipmentClassFilter()

Get the lot equipment class filter used to filter the results.
parameters
None
returns

String

The lot equipment class filter.

Inductive Automation

Track and Trace

263

setPersonnelNameFilter(personnelNameFilter)

Set the personnel name filter to include lots that were processed with a name that matches
this property. It can contain wildcard characters including * or ?. The * character can be any
characters and the ? character represents any single character.
parameters
personnelNameFilter

The personnel name filter used to filter the results.

Data Type

String

returns
Nothing

getPersonnelNameFilter()

Get the personnel name filter used to filter the results.

parameters
None
returns

String

The personnel name filter.

setPersonnelClassFilter(personnelClassFilter)

Set the personnel class filter to include lots that were processed by personnel that belong to
the personnel class that matches this property. It can contain wildcard characters including *
or ?. The * character can be any characters and the ? character represents any single
character.
parameters
personnelClassFilter

The personnel class filter used to filter the results.

Data Type

returns
Nothing

Inductive Automation

String

Track and Trace

264

getPersonnelClassFilter()

Get the personnel class filter used to filter the results.

parameters
None
returns

String

The personnel class filter.

setMaterialNameFilter(materialNameFilter)

Set the material definition name filter to include lots that have material with a name that
matches this property. It can contain wildcard characters including * or ?. The * character can
be any characters and the ? character represents any single character.
parameters
materialNameFilter

The material definition name filter used to filter the results.

Data Type

String

returns
Nothing

getMaterialNameFilter()

Get the material name filter used to filter the results.

parameters
None
returns

String

The material name filter.

Inductive Automation

Track and Trace

265

setMaterialClassFilter(materialClassFilter)

Set the material class filter to include lots that have material that belong to the material class
that matches this property. It can contain wildcard characters including * or ?. The * character
can be any characters and the ? character represents any single character.
parameters
materialClassFilter

The material class filter used to filter the results.

Data Type

String

returns
Nothing

getMaterialClassFilter()

Get the material class filter used to filter the results.

parameters
None
returns

String

The material class filter.

setOperationNameFilter(operationNameFilter)

Set the operation name filter to include lots that were processed by the operation with a name
that matches this property. It can contain wildcard characters including * or ?. The * character
can be any characters and the ? character represents any single character.
parameters
operationNameFilter

The operation name filter used to filter the results.

Data Type

returns
Nothing

Inductive Automation

String

Track and Trace

266

getOperationNameFilter()

Get the operation name filter used to filter the results.

parameters
None
returns

String

The operation name filter.

setSegmentNameFilter(segmentNameFilter)

Set the segment name filter to include lots that were processed by the segment with a name
that matches this property. It can contain wildcard characters including * or ?. The * character
can be any characters and the ? character represents any single character.
parameters
segmentNameFilter

The segment name filter used to filter the results.

Data Type

String

returns
Nothing

getSegmentNameFilter()

Get the segment name filter used to filter the results.

parameters
None
returns

String

The segment name filter.

Inductive Automation

Track and Trace

267

setSegmentEquipmentNameFilter(segmentEquipmentNameFilter)

Set the segment equipment name filter to include lots that were processed at the equipment
with a name that matches this property. It can contain wildcard characters including * or ?. The
* character can be any characters and the ? character represents any single character.
parameters
segmentEquipmentNameFil The segment equipment name filter used to filter the results.
ter

Data Type

String

returns
Nothing

getSegmentEquipmentNameFilter()

Get the segment equipment name filter used to filter the results.
parameters
None
returns

String

The lot equipment name filter.

setSegmentEquipmentClassFilter(segmentEquipmentClassFilter)

Set the segment equipment class filter to include lots that were processed at the equipment
that belong to the equipment class that matches this property. It can contain wildcard
characters including * or ?. The * character can be any characters and the ? character
represents any single character.
parameters
segmentEquipmentClassFilter

The segment equipment class filter used to filter the res

Data Type

returns
Nothing

Inductive Automation

String

Track and Trace

268

getSegmentEquipmentClassFilter()

Get the segment equipment class filter used to filter the results.
parameters
None
returns

The segment equipment class filter.

String

setCustomPropertyValueFilter(customPropertyValueFilter)

Set the custom property filter expressions to filter the results. If a custom property of a lot
matches an expression in this list, then it will be included in the results. Use system.mes.
object.filter.parseCustomPropertyValueFilter() script function to create the list of
MESPropertyValueFilter objects.
paramete
rs
customPropertyVal The custom property value list to filter the results.
ueFilter

Data Type
List of
MESPropertyValueFilter
returns
Nothing
Example
filter = system.mes.object.filter.createFilter()
list = system.mes.object.filter.parseCustomPropertyValueFilter('pH > 5.0,Width = 2.5')
filter.s etCustomPropertyValueFilter(list )

getCustomPropertyValueFilter()

Get the list of MESPropertyValueFilter used to filter the results.

paramete
rs
None
returns

List
of
MESPr
opert
yValu
eFilt
er

The
custom
property
value list.

Inductive Automation

Track and Trace

Custom Property
Val
ue
Filt
er

The results can be limited to only include items that have a custom property
expressions defined by this property that evaluates to true.
Example
Kind > 3

Scripting name
Data Type

2.9.3.6

269

customPropertyValueFilter
String

MESInventoryFilter

A MESInventoryFilter object used to query inventory information and is required by certain script methods.
Because inventory results maybe specific to known materials, locations, etc., this object is used to hold
the filter settings.
methods:
system.mes.inventory.filter.createFilter()

Returns a new instance of a MESInventoryFilter object for that properties can be set on. This
is typically used when a script function requires a MESInventoryFilter object as a parameter.
parameters
returns
MESInventoryFilter

A new instance of a MESInventoryFilter object.

Example
from java.util import Calendar
filter = system.mes.inventory.filter.createFilter()
filter.setIncludeCompleteLots(True)
filter.setEquipmentClassName('Vinegar Tanks')
beginCal = Calendar.getInstance()
beginCal.add(Calendar.DAY_OF_MONTH, -30)
filter.setBeginDateTime(beginCal)
endCal = Calendar.getInstance()
filter.setEndDateTime(endCal)
results = system.mes.getInventory(filter)
for rowIndex in range(results.getRowCount()):
print str(results.getValueAt(rowIndex, 0))

properties:

Inductive Automation

Track and Trace

270

setIncludeActiveLots(includeActiveLots)

If set to True, lots or sublot that are actively being processed will be included in the results.
parameters
includeActiveLots If True, include active lots or sublots in results.

Data Type

Boolean

returns
Nothing

includeActiveLots()

If True, lots currently being processed will be included in the results.

parameters
None
returns

Boolean

If True, active lots will be return in the results.

setIncludeCompleteLots(includeCompleteLots)

If set to True, lots or sublot that are completed will be included in the results.
parameters
includeActiveLots If True, include completed lots or sublots in results.

Data Type

Boolean

returns
Nothing

includeCompleteLots()

If True, lots that are complete will be included in the results.

parameters
None
returns

Boolean

If True, completed lots will be return in the results.

Inductive Automation

Track and Trace

271

setCustomLotStatus(customLotStatus)

Set the custom lot status of results to return. If the Final Lot Status property in a resource
definition of a Process Segment or Operations Segment is set to a custom lot status, it can be
filtered with this property.
parameters
customLotStatus Custom lot status value to filter results.

Data Type

String

returns
Nothing

getCustomLotStatus()

Get the custom lot status of results to return.

parameters
None
returns

String

The custom lot status value.

setBeingDateTime(beginDateTime)

Set the beginning date and time to limit results to return. This applies to lots or sublots that are
completed or have a custom lot status.
parameters
beginDateTime

Beginning date and time to filter results.

Data Type

Calendar

returns
Nothing

getBeginDateTime()

Get the beginning date and time to limit the results to return.
parameters
None
returns

Calendar

Inductive Automation

The beginning date and time to filter results.

Track and Trace

272

setEndDateTime(endDateTime)

Set the ending date and time to limit results to return. This applies to lots or sublots that are
completed or have a custom lot status.
parameters
endDateTime

Ending date and time to filter results.

Data Type

Calendar

returns
Nothing

getEndDateTime()

Get the ending date and time to limit the results to return.
parameters
None
returns

Calendar

The ending date and time to filter results.

setEquipmentClassName(equipmentClassName)

The results can be limited to only include lots or sublots that are or were stored at the
equipment that are included in a material class that match this property. It can contain
wildcard characters including * or ?. The * character can be any characters and the ?
character represents any single character.
Only one of the Equipment Class Name, Equipment Class UUID, Equipment Path or
Equipment UUID properties can be specified at a time.
Example
Vinegar Storage Tanks .
parameters
equipmentClassName

The lot equipment class name used to filter the results.

Data Type

String

returns
Nothing

Inductive Automation

Track and Trace

273

getEquipmentClassName()

Get the lot equipment class name used to filter the results.
parameters
None
returns

String

The lot equipment class name.

setEquipmentClassUUID(equipmentClassUUID)

The results can be limited to only include lots or sublots that are or were stored at the
equipment that are included in a material class that match this property. See UUIDs for
more information.
Only one of the Equipment Class Name, Equipment Class UUID, Equipment Path or
Equipment UUID properties can be specified at a time.
parameters
equipmentClassUUID

The lot equipment class UUID used to filter the results.

Data Type

returns
Nothing

getEquipmentClassUUID()

Get the lot equipment class UUID used to filter the results.
parameters
None
returns

String

Inductive Automation

The lot equipment class UUID.

String

Track and Trace

274

setEquipmentPath(equipmentPath)

The results can be limited to only include lots or sublots that are or were stored at the
equipment that match this property. See Equipment for more information on equipment
paths
Only one of the Equipment Class Name, Equipment Class UUID, Equipment Path or
Equipment UUID properties can be specified at a time.
parameters

The lot equipment path used to filter the results.

equipmentPath

Data Type

String

returns
Nothing

getEquipmentPath()

Get the lot equipment path used to filter the results.

parameters
None
returns

String

The lot equipment path.

setEquipmentUUID(equipmentUUID)

The results can be limited to only include lots or sublots that are or were stored at the
equipment that match this property. See UUIDs for more information.
parameters
equipmentClassUUID

The lot equipment UUID used to filter the results.

Data Type

String

returns
Nothing

Inductive Automation

Track and Trace

275

getEquipmentUUID()

Get the lot equipment UUID used to filter the results.

parameters
None
returns

String

The lot equipment UUID.

setMaterialClassName(materialClassName)

The results can be limited to only include lots or sublots that the associated material is
included in a material class that matches this property. It can contain wildcard characters
including * or ?. The * character can be any characters and the ? character represents any
single character.
Only one of the Material Class Name, Material Class UUID, Material Definition Name,
Material Definition UUID properties can be specified at a time.
Example
Vinegar
parameters
materialClassName

The material class name used to filter the results.

Data Type

returns
Nothing

getMaterialClassName()

Get the material class name used to filter the results.

parameters
None
returns

String

Inductive Automation

The material class name.

String

Track and Trace

276

setMaterialClassUUID(materialClassUUID)

The results can be limited to only include lots or sublots that the associated material is
included in a material class that matches this property. See UUIDs for more information.
Only one of the Material Class Name, Material Class UUID, Material Definition Name,
Material Definition UUID properties can be specified at a time.
parameters
materialClassUUID

The material class name used to filter the results.

Data Type

String

returns
Nothing

getMaterialClassUUID()

Get the material class UUID used to filter the results.

parameters
None
returns

String

The material class UUID.

setMaterialDefName(materialDefName)

The results can be limited to only include lots or sublots that the associated material
matches this property. It can contain wildcard characters including * or ?. The * character
can be any characters and the ? character represents any single character.
Only one of the Material Class Name, Material Class UUID, Material Definition Name,
Material Definition UUID properties can be specified at a time.
Example
*Balsamic*
parameters
materialDefName

The material definition name filter used to filter the results.

Data Type

String

returns
Nothing

Inductive Automation

Track and Trace

277

getMaterialNameFilter()

Get the material definition name used to filter the results.

parameters
None
returns

String

The material name filter.

setMaterialDefUUID(materialDefUUID)

The results can be limited to only include lots or sublots that the associated material
matches this property. See UUIDs for more information.
Only one of the Material Class Name, Material Class UUID, Material Definition Name,
Material Definition UUID properties can be specified at a time.
parameters
materialDefUUID

The material definition UUID used to filter the results.

Data Type

returns
Nothing

getMaterialDefUUID()

Get the material definition UUID used to filter the results.

parameters
None
returns

String

Inductive Automation

The material name UUID.

String

Track and Trace

278

setPersonnelClassName(personnelClassName)

The results can be limited to only include lots or sublots that are or were handled by
personnel that are included in a personnel class that match this property. It can contain
wildcard characters including * or ?. The * character can be any characters and the ?
character represents any single character.
Only one of the Personnel Class Name, Personnel Class UUID or Person First Name and
Person Last Name combination properties can be specified at a time.
Example
Unload Operator
parameters
personnelClassName

The personnel class name used to filter the results.

Data Type

String

returns
Nothing

getPersonnelClassName()

Get the personnel class name used to filter the results.

parameters
None
returns

String

The personnel class name.

setPersonnelClassUUID(personnelClassUUID)

The results can be limited to only include lots or sublots that are or were handled by
personnel that are included in a personnel class that match this property. See UUIDs for
more information.
Only one of the Personnel Class Name, Personnel Class UUID or Person First Name and
Person Last Name combination properties can be specified at a time.
parameters
personnelClassUUID

The personnel class UUID used to filter the results.

Data Type

String

returns
Nothing

Inductive Automation

Track and Trace

279

getPersonnelClassUUID()

Get the personnel class UUID used to filter the results.

parameters
None
returns

String

The personnel class UUID.

setPersonFirstName(personFirstName)

The results can be limited to only include lots or sublots that are or were handled by
personnel that match this property. It can contain wildcard characters including * or ?. The
* character can be any characters and the ? character represents any single character.
parameters
personFirstName

The person first name used to filter the results.

Data Type

returns
Nothing

getPersonFirstName()

Get the person first name used to filter the results.

parameters
None
returns

String

Inductive Automation

The person first name filter.

String

Track and Trace

280

setPersonLastName(personLastName)

The results can be limited to only include lots or sublots that are or were handled by
personnel that match this property. It can contain wildcard characters including * or ?. The
* character can be any characters and the ? character represents any single character.
parameters
personLastName

The person last name used to filter the results.

Data Type

String

returns
Nothing

getPersonLastName()

Get the person last name used to filter the results.

parameters
None
returns

String

The person last name filter.

setPersonUUID(personUUID)

The results can be limited to only include lots or sublots that are or were handled by
personnel that match this property. See UUIDs for more information.
parameters
personUUID

The person UUID used to filter the results.

Data Type

String

returns
Nothing

getPersonUUID()

Get the person UUID used to filter the results.

parameters
None
returns

String

The person UUID filter.

Inductive Automation

Track and Trace

2.9.3.7

281

MESScriptEvent

The MESScriptEvent object is passed when a MES object event is executed. Script for MES object
events are defined in the Designer on the General Tab of the enterprise production item. See Events in
the MES object reference chapter. Optionally, the script defined for the event can execute the
runDefaultHandler function on the event object to execute the built-in logic for the event.
From the MESScriptEvent object the full MES object can be loaded by calling the getMESObject function
on the event.
methods:
runDefaultHandler()

Executes the built-in logic for the event. This allows pre or post logic to be executed around
the built-in logic or completely replace the built-in logic.
Note that user events will not have a default handler and no logic will be executed if this
function is called.
parameters
None
returns
Nothing

properties:
getMESObject()

Returns the MES object that the event is being executed for.
parameters
None
returns
AbstractMESObject
getParameters()

Return the MESObjectEventParameters object that contains any parameter values

parameters
None
returns
MESObjectEventParameters

Inductive Automation

Track and Trace

2.9.3.8

282

MESObjectEventParameters

A MESObjectEventParameters object used with the MESScriptEvent to pass parameters to the MES
object event. The MESObjectEventParameters object just holds name value pairs where both the name
and the value are Strings.
This object is typically used when executing user MES object events to allow passing values to the event
script.
methods:
system.mes.object.parameters.create()

Returns a new instance of a MESObjectEventParameters object that name value pairs can be
add to.
parameters
returns
MESObjectEventParameters

A new instance of a MESObjectEventParameters object.

Example
mesObject = system.mes.loadMESObject('VIN 3344', 'MaterialLot')
if mesObject != None:
params = system.mes.object.parameters.create()
params.put('Kind', 'Dressing')
params.put('Priority', 'High')
system.mes.executeMESEvent(mesObject, 'My User Event', params)

properties:
put(name, value)

Add a name value pair to the parameters collection.

parameters
name

The name of the value to add to the parameters collection.

Data Type

value

String

The value to add to the parameters collection.

Data Type

String

returns
Nothing
2.9.3.9

MESObjectCollection

A MESObjectCollection object is used by MES objects to hold parents and children. Normally, the parent
and child script functions of the MES objects should be used, but this is provided as a reference to the
MESObjectCollection object itself and provides some additional functionality.

Inductive Automation

Track and Trace

283

methods:
getList()

Returns a list of MES object links. Depending if getParentCollection() or getChildCollection

() is called to get the MESObjectCollection object, it will contain MES object links that are
parents or children.
parameters
None
returns
List of
MESObjectLink

A list of MES object links.

This example reads the child MES object links that belong to the Vinegar Material Class.
Example
mesObject = system.mes.loadMESObject('Vinegar', 'MaterialClass')
if mesObject != None:
childList = mesObject.getChildCollection().getList()
for child in childList:
print child.getName()

get(uuid)

Returns the MES object link for the specified UUID. If the specified UUID does not exist, None
will be returned.
parameters
None
returns
MESObjectLink

A MES object link.

size()

Returns the number of MES object links in the collection. Depending if getParentCollection()
or getChildCollection() is called to get the MESObjectCollection object, it will represent the
number of parents or children.
parameters
None
returns
Integer

Inductive Automation

The number of MES object links in the collection.

Track and Trace

284

isEmpty()

Returns True if no MES object links exist in the collection.

parameters
None
returns
Boolean

True if there are no MES object links in the collection.

properties:
None

2.9.3.10 AbstractMESComplexProperty

An AbstractMESComplexProperty object is used as a base object for Material Resource Property,

Personnel Resource Property, Equipment Resource Property (which are detailed in Process Segment
reference), the Segment Dependency Property (which is detailed in the Operations Definition reference)
and the Lot Reference Property (which is detailed in the Response Segment reference).
The complex property script functions (which are detailed in Property Script Functions section of the MES
Object reference) return an AbstractMESComplexProperty object. This is done because duplicate
functions would have to be implemented for Material Resource Property, Personnel Resource Property,
etc. reference type.
Read Complex Property Value Example:
mesObject = system.mes.loadMESObject('Unload Vinegar', 'ProcessSegment')
matRef = mesObject.getComplexProperty('Material', 'Raw Material')
print matRef.getValue('MaterialUse')

output
Out

methods:

Inductive Automation

Track and Trace

285

getValue(valueName)

Returns the value for the specified name. Complex properties have various values of various
data types. For the specific value names see:
Process Segment for details about Material Resource Property, Personnel Resource
Property and Equipment Resource Property.
Operations Definition for details about Segment Dependency.
Operations Response for details about Lot.
parameters
valueName

The name of the value to return.

Data Type

String

returns
Object

The value as an object.

setValue(valueName, value)

Set the value for the specified value name. Complex properties have various values of various
data types. For the specific value names see:
Process Segment for details about Material Resource Property, Personnel Resource
Property and Equipment Resource Property.
Operations Definition for details about Segment Dependency.
Operations Response for details about Lot.
parameters
valueName

The name of the value to set.

Data Type

value

The new value.

Data Type

returns
None

Inductive Automation

String

Serializable Object

Track and Trace

286

getName()

Get the name for the complex property. Complex properties that use extended naming have
an associated base name and a number following it. This is used with Lot Reference Property
that the Response Segment uses. Each time a lot reference is created it is named the base
name with an extension added to it.
For example:
If balsamic vinegar is being unloaded and the tank it is being stored in fills up before the truck
is fully unloaded. When it is switched to another storage tank a new lot reference is created. If
the name of the material reference in the Process Segment is named Vinegar, then the first lot
reference is named Vinegar-1 for the first storage tank and the second is Vinegar-2 for the
second storage tank.
parameters
None
returns
String

The name for the complex property.

getBaseName()

Get the base name for the complex property. Complex properties that use extended naming
have an associated base name and a number following it. This is used with Lot Reference
Property that the Response Segment uses. Each time a lot reference is created it is named
the base name with an extension added to it.
For example:
If balsamic vinegar is being unloaded and the tank it is being stored in fills up before the truck
is fully unloaded. When it is switched to another storage tank a new lot reference is created. If
the name of the material reference in the Process Segment is named Vinegar, then the first lot
reference is named Vinegar-1 for the first storage tank and the second is Vinegar-2 for the
second storage tank.
parameters
None
returns
String

The base name for the complex property.

properties:
None

Inductive Automation

OEE Downtime
Part III

OEE Downtime

288

OEE Downtime

Inductive Automation

OEE Downtime

3.1

289

Introduction

Improving production efficiency is the key to improving profit and reducing capital expenditures. It can
make the difference competitively; however, it can also be very challenging because it requires more than
just installing software. Improving efficiency requires commitment from management, maintenance,
production and IT departments, as well as integration, training, actions to reduce downtime and new
operational procedures. The OEE Downtime and Scheduling Module helps you to diagnose the
inefficiencies within your production, allowing you to make improvements on the line and between
employees.
The first step in improving efficiency is knowing where you are starting from. Think of it like improving the
gas mileage of your car. You must start by determining your current gas mileage before you can begin
making changes to improve your mileage. Once you know your existing OEE and have tracked the
causes of downtime, then you can finish the process and start fixing the sources of your production
inefficiencies.
But why combine OEE, downtime and scheduling into one module? The OEE Downtime and Scheduling
Module does not require the use of all three functions, but we packaged them together because the
combination provides the best tools for the improvement of production efficiency. If only downtime was
tracked, then you would not see the full picture. Downtime only informs you as to whether or not a
machine is running, not if the machine is actually producing a quality product. Or if only OEE was tracked,
you would know that efficiency is lower than normal, but not why or what actions to take to improve it. Low
efficiencies also result from ineffective procedures or a lack of communications between departments.
This is where the scheduling helps by providing current schedule information to all associated
departments, improving communication and reducing unnecessary delays. The OEE Downtime and
Scheduling Module allows you to see the whole picture, resulting in the improvement of your production in
every aspect.

3.1.1

OEE

OEE stands for Overall Equipment Effectiveness and is used to monitor manufacturing effectiveness.
The resulting OEE number, represented as a percentage, is generic and allows comparisons across
differing industries.
Efficiency is not simply the ratio of machine run time to scheduled time. Look at the situation of your
manufacturing line or process running at half speed with 0 downtime. This is truly only 50% efficient. Or
what if 10% of the product being produced does not meet your minimum quality and must be reworked.
This equates to 90% efficient, which does not take into account the effort to rework or the losses of raw
material.

Inductive Automation

OEE Downtime

290

There are three factors, all represented as a percentage, taken into consideration for the final OEE result:
OEE Availability
OEE Availability is the ratio between the actual run time and the scheduled run time. The scheduled run
time does not included breaks, lunches and other pre-arranged time a production line or process may be
down.
Example:
If a line is scheduled for one 8 hour shift with two 15 minute break s and one 30 minute lunch, then the scheduled time
is 7 hours (determined from 8 hours - 15 minute break - 15 minute break - 30 minute lunch). If during the production
run, there are 25 downtime events totaling to 45 minutes of downtime, then the run time is 6 hours and 15 minutes
(derived from 7 hours of scheduled time - 45 minutes). The OEE Availability of 89% is calculated by actual run time
divided by scheduled run time, or 6 hours 15 minutes divided by 7 hours.

OEE Performance
OEE Performance is the ratio between the actual number of units produced and the number of units that
theoretically can be produced based on the standard rate. The standard rate is rate the equipment is
designed for.
Example:
If a work cell is designed to produce 10 units per minute we can calculate the theoretical amount of units it can
produce in a given amount of time. Using the 6 hours and 15 minutes of actual run time from the above example, a
total of 3750 units would be produced. Calculated by tak ing 6 hours and 15 minutes (375 minutes) times 10 units per
minute. If the actual number of units produced is 3000, then the OEE Performance is 80% (calculated by 3000 /
3750).

OEE Quality
OEE Quality is the ratio between good units produced and the total units that were started.
Example:
Tak ing the number of units produced from above of 3000, if 200 units were rejected at the quality inspection station,
then 2800 good units are produced . The OEE Quality is 93% calculated from 2800 divided by 3000.

The final calculation is OEE = Availability x Performance x Quality.

Example:
Using all the numbers from above, 89% x 80% x 93% = 66%.

This may seem like a low number but it is important to kept in mind that the OEE is not to be compared to
100%. The OEE result from this production run is compared to other production runs; however, using
Inductive Automations OEE Downtime and Scheduling module allows much more than just comparing
OEE results between production runs. It allows you to compare OEE results between operators,
viscosity, mechanics, products, raw material vendors and any user defined factor you can think of.

Inductive Automation

OEE Downtime

3.1.2

291

TEEP

Where OEE represents the equipment efficiency during a production run, Total Effective Equipment
Performance (TEEP) represents the equipment utilization against a calendar period. For example, 365
days a year, or 24 hours a day. It can also be thought of as asset utilization and will help in the decision
making process of purchasing new equipment.
There are two factors used to calculate TEEP:
Loading
Loading is the ratio between the scheduled time for the production line (or process) and the calendar
time.
Example:
If a production line is scheduled for 5 days, 24 hours each day, over a 7 day period, then the loading is 71%
calculated by (5 x 24) / (7 x 24).

OEE
OEE = Availability x Performance x Quality as described in the previous section.
The calculation is TEEP = Loading * OEE
Example:
To simplify this example we will use made up OEE result of 82%. The actual OEE value used must be the OEE result
for all production runs of the same calendar time period that were used to calculate the Loading value.
TEEP = 71% * 82%
The TEEP result is 58% .

3.1.3

Production Count Tracking

For OEE calculations to be performed, production count information is required. At a minimum, the
outfeed production count for a production line is needed. Additional production count information can be
configured, leading to more OEE calculations.
For example, if the infeed production count is configured for a production, then product accumulation and
waste can be calculated.

3.1.4

Down Time Tracking

OEE provides a method to monitor the efficiency of your production facility and tracking downtime
provides information of where to focus efforts to improve efficiency. Think of it this way, if your production
line typically runs at 69% OEE, what actions do you take to increase it? OEE alone doesn't tell you what
factors are preventing your efficiency from being higher than 69%.
In the simplest form, downtime tracking will identify the production cell (machine or process) that is
preventing you production line from producing product. This can be done manually, but history has shown
that manually collected downtime information is not accurate. In addition, if it is manually collected on
paper log sheets, then someone has to further enter the details into a program or spreadsheet to be able
to organize it into actionable information used to focus your efforts to make improvements. Putting
recording inaccuracies, extra labor and typos aside, by the time the information is available, it is old.
Tracking downtime automatically or semi-automatically solves the issues associated with manual
Inductive Automation

OEE Downtime

292

tracking. In a perfect world, monitoring all downtime reasons automatically is the ideal solution. But in the
real world, this can be difficult, pricey, or just not practical. For this reason, it is important for downtime
tracking software to support an automatic reason detection with a manual override. For example: if an
operator presses the stop button because they see a bottle laying on its side feeding into a filler, then the
only automatic reason that can be detected is "operator pressed stop button". Now the operator should be
able to override this reason with more specific information.
Once the period of time that production cells were not producing product and the associated reasons are
recorded, analyzing the summary of the reasons will identify where effort should be focused to improve
efficiency.

3.1.5

Production Scheduling

A lot of coordination must be used when scheduling production. If one item is not in unison with the rest,
then production line efficiencies will drop. If raw material is not at the line when the line is ready to start
production, then line production is waiting. Even if this is just 10 minutes, it negatively reduces the
production line efficiency.
In some operations, production schedules change, sometimes at the last minute, making if difficult and
forcing employees to rely on a verbal updates involving multiple people. It becomes an issue of how much
effort is being consumed to do so and how many times are there hiccups.
By instantaneously propagating schedule changes to all departments, combined with tools to track
required, scheduled, produced and remaining production information, can help make an operation run
smoother.

Inductive Automation

OEE Downtime

3.2

293

Getting Started

This getting started guide will step you though OEE Downtime and Scheduling module installation, demo
installation, the demo user interface and configuration features.

3.2.1

Installation

Follow the next four sections to install the complete OEE Downtime and Scheduling. If you just want in
install the core modules and skip the demo, follow the next three sections.
3.2.1.1

Installing Modules

To install the OEE Downtime and Scheduling module on to an existing Ignition server, follow the steps
below:
Before installing the OEE Downtime and Scheduling module, it is recommended to first setup the
database connection that will be used to store OEE, downtime and scheduling data.
1. Download the OEEDT Installer.modl module
from the Inductive Automation download website. It will be under the MES modules heading.
2. Install the OEEDT Installer.modl module
Navigate to the Modules page of the Ignition gateway. At the bottom of the list of already installed modules,
click the
install button as shown below.

link. Next, browse to the OEEDT Installer.modl file and click the

Install Ignition Module

Inductive Automation

OEE Downtime

294

The OEEDT Installer module will install all required modules. These are the Production, OEE Downtime
and Scheduling modules. It is important to keep in mind not to install or update these module individually.
Instead, it should be done by updating the OEEDT Installer module.
3.2.1.2

Configure Database

OEE, downtime and schedule data is stored in databases external to Ignition. These database(s) are
setup in the gateway configuration section by selecting the Databases> Connections section from the
left-hand configuration menu. See the Ignition documentation for more information on setting up a
database connection. Below shows a typical database connection that is required for the OEE, Downtime
and Scheduling module.

Sam ple Database Connection

3.2.1.3

MES Module Settings

The OEE Downtime and Scheduling module stores data in a SQL database. Because Ignition can be
configured to multiple databases, the MES Module Settings configuration page is used to select which
databases to store OEE, downtime and scheduling data. If only one database has been configured in
Ignition, then it will be selected by default.
To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules.
If more than one database connection exists, then the desired database connection can be selected to be
used by the MES modules as shown below.

Inductive Automation

OEE Downtime

295

MES Module Settings Page

For more information on the MES Module Settings, see MES Module Configuration.

3.2.2

User Interface

This section will walk through the user screens of the OEE Demo. As you are going through this section,
it is important that you keep in mind that these screens are just provided for demo, training and to reduce
the time required to get up and running. They can be modified, deleted or add new screens using the
Ignition designer. But we will save that for the next section. To start the OEE Demo, go to the home
section in the gateway and click on the launch button as shown below.

Inductive Automation

OEE Downtime

296

Launch OEE Dem o Client

Inductive Automation

OEE Downtime
3.2.2.1

297

Work Orders

Work orders track the progress of production of a given product. They can span across multiple
production runs of a given product. As shown below, the total number of products in the first work order is
10,000. We can also see that no cases have been scheduled, no cases have been produced so far, so all
the cases are remaining. As production runs are scheduled and product is manufactured against a work
order, these values will update.

Work Order Screen

It is possible to remove work orders that are closed or hide an open work order by selecting one of the
two check boxes to the left of the work order. It is also possible to show these work orders again by
selecting "Show Closed Work Orders" or "Show Hidden Work Orders" in the top, right-hand corner of the
screen. In order to show work orders in a specific date or the time range, there is a slide bar at the bottom
of the screen which can be dragged to the correct date. The magnifying glasses allow a more specific
time or a broader range of dates to be viewed.
The system supports adding work orders, as well as editing and removing work orders. For companies
that have ERP (Enterprise Resource Planning) or other systems containing work order information, work
orders can be added or updated automatically. To add a work order, simply click "Add" and fill in the
necessary information. A product code must be entered before a work order can be added.

New Work Order Window

Inductive Automation

OEE Downtime

3.2.2.2

298

Product Codes

Product codes or pack codes represent the products that are manufactured within your facility. If you
have multiple production lines, this screen is where product codes are assigned to individual production
lines. In addition, the settings for a product code may vary depending on the line it is being produced on.
Those settings are also set on this screen in the Properties section.

Product Code Screen

To assign a product code to one or more production lines, select the product code, then select the
"Enable" box next to the appropriate line. It is also possible to disable a product code altogether by
selecting the box to the right of the product code. To edit the properties, select the product code and the
line you wish to edit, then double click the value to be changed. Pressing Enter or clicking off of the value
will save the change. Product code descriptions can also be edited by double clicking.
The demo demonstrates adding product codes, but the system also supports editing and removing
product codes. For companies that have ERP (Enterprise Resource Planning) or other systems
containing product code information, product codes can be added or updated automatically from them.
3.2.2.3

Production Schedule

The scheduling screen is similar to Outlook calendar and is easy for new users to learn how to use. It has
month, week and day views that are selected by clicking on the

buttons. Select the

Inductive Automation

OEE Downtime

299

production line to view and edit the schedule by using the drop-down list as shown below.

Line Selection on Calendar

Production runs can be scheduled for part of a shift, across multiple shifts, days and even months.

To see how editing production run entries works, select the week view. Next, using the mouse, right-click
on a day and time to start the production run and click New Entry. Here, you can also chose to edit or
delete an existing scheduled production run. The New Schedule Entry popup window allows for
scheduling production runs, maintenance and other entries. By selecting the Work Order Run schedule
type, work order options appear. Continue by selecting a work order (these must be created before
adding a new schedule entry). Notice, the total work order units to be produced, units produced, units
scheduled and units remaining information is shown for the selected work order. The quantity entry is
automatically set to the remaining units for the work order. A C/O duration may also by added to account
for the change over duration before the production line begins.

Inductive Automation

OEE Downtime

300

Schedule New Production Run

After entering the desired quantity, the finish time for the work order will automatically update to show the
predicted production end time and date. The system forecasts the finish time based on the schedule rate
for the product code associated with the work order and all breaks or meals that are configured. You can
override the finish time by selecting the Override Automatic Finish option and manually selecting a date
and time.
3.2.2.4

Operator Screen

The operator screen provides an interface to allow the operator to control the current production run,
select downtime reasons and monitor the current production run. This screen is used as a demo, but can
reduce the amount of time needed to implement an OEE, downtime and scheduling system. It can be
modified using the Ignition designer to accommodate your requirements.

Inductive Automation

OEE Downtime

301

Operator Screen

The portion of the operator screen shown below, allows the operator to start, end and resume production
runs. By clicking on the down arrow of the scheduled entry drop-down box, a list of scheduled production
runs that have not been started will be shown for the operator to select from. Before a different
production run can be selected, the current production run must be ended.

Scheduled Run Selection

Inductive Automation

OEE Downtime

302

Once the run has started, the downtime events for the selected line will show in the downtime reason
table. Sometimes downtime events occurred for more than one reason. When this happens, downtime
events can be split by clicking on the split icon as shown below. Comments can also be added by
clicking
to the right of the split icon.

Dow ntim e Reason Table

You will notice other information of the screen that give the operator realtime indication of how the
production run is progressing. The indictor shown below displays the target and actual production for the
current shift. At the start of every shift change, new targets are calculated for the new shift. This always
provides the operator relevant production information on their shift to keep the entire production run on
track.

Production Progress Indicator

Below this, the OEE information is displayed for the shift. Here, the total OEE for the shift is displayed, as
well as the Quality, Performance, and Availability individually.

Inductive Automation

OEE Downtime

303

OEE Indicator

3.2.2.5

Line Charts

The line charts screen provides realtime information as the production runs progresses. Completed
production runs can be selected using the production run drop-down list. At the bottom of the screen, a
graph showing the top reasons for down time is displayed and the number of minutes of down time
caused by each of the given reasons. It is possible to zoom in on any of the graphs by clicking and
dragging over the desired area, or by right-clicking and selecting Zoom In. To restore the previous view,
you can right-click and select Zoom Out or Reset Axes. Auto Range can also be used to see more of
the graph.

Sam ple Line Charts Screen

Inductive Automation

OEE Downtime
3.2.2.6

304

Analysis Screen

The analysis screen allows for ad-hoc analysis of production data. OEE, TEEP, downtime, production
and even user defined data can be viewed across a date range. This data can also be filtered to only
include specific criteria. Additionally, comparisons can be made between different factors. For example,
downtime by operator can be analyzed or even downtime by operator by shift.

Ad-hoc Analysis Screen

The date range selector at the bottom is used to define the data range to include in the analysis. As you
change the start or end dates, only the production runs that are within that range will be included in the
analysis.
Stored Analysis
In the demo project, there are pre-configured analyses that can be selected in the store reports section.
As different stored analyses are selected, the values in the Selections section will change. The demo
project, has a Downtime by Line stored analysis. Selecting it will make the selection to view downtime
occurrences and downtime minutes values by individual lines.

Saved Reports

Inductive Automation

OEE Downtime

305

If the pie chart is selected, only the downtime occurrences will be represented graphically. However, if the
bar chart is selected, then both the downtime occurrences and the downtime length in minutes will be
shown graphically in separate bars.
Filter By
Once an stored analysis has been selected, you can change the selections to zero in on the data that you
desire. The filter section allows you to limit the data that is included in the analysis. Filters can be added
by clicking on the
icon on the right side of the Filter By section. Within the popup filter selection
window, scroll down to the Factor:Operator option and click the icon. Notice the names of operator
that can be selected. Clicking on George Gonzalez will add the Factor:Operator = George Gonzalez
causing the analysis results to included downtime data while George Gonzalez was the operator.

Filter By Options

The list of available filters change based on the date range. For example, if George Gonzalez was on
vacation for the desired date range, then his name will not show as an available options.
The filter selection shown below includes data for only Line 1 when George Gonzalez was the operator
and excluding all planned downtime.

Inductive Automation

OEE Downtime

306

Filter By Selections

Filter By items can be removed by clicking on the

located to the left of the name.

Compare By
Breaking up information into groups is more meaningful than just seeing a total for a given date range. For
example, knowing the total downtime for Line 1 for a given data range really does not provide actionable
information that can be used to improve efficiencies. Now, by comparing the total downtime for each
machine on Line 1, it is possible to identify the machine(s) causing the most downtime. Focusing efforts
on these machines and solving sources of downtime will result in better efficiencies.
Additional Compare By items can be added by clicking on the
icon on the right side of the Compare
By section. Within the popup Compare By selection window, click on the desire item that you want to
compare analysis results between.

Com pare By Selections

Compare By items can be removed by clicking on the

located to the left of the name.

Data Points
Data points are the individual pieces of information that will be present in the analysis. For example,
downtime minutes or downtime occurrences are just two of the many available data points. To add a data
point, click on the
icon on the right side of the Data Points section. Within the popup Data Point
selection window, click on the data point item to include in the analysis.

Data Point Selections

Data Points can be removed by clicking on the

located to the left of the name.

Inductive Automation

OEE Downtime

307

Drill Down
The drill down feature simplifies the compare by and filter selections. Click on a chart series to display the
available drill down options. As shown in Drill Down Example 1 below, clicking on the Line 1 pie segment
will show a popup menu of drill down options. If the Cell Name option is selected, then the analysis filters
to show the information by Cell Name . The Filter By and the Compare By sections add Cell Name. The
result is shown in Drill Down Example 2. Again, by clicking on the "Filler" pie segment and selecting
Operator Reason, the Filter By and Compare By selections will change to show information for only Line
1 Filler and Compare By Operator Reason as shown in Drill Down Example 3.

Drill Dow n Exam ple 1

Drill Dow n Exam ple 2

Drill Dow n Exam ple 3

Inductive Automation

OEE Downtime
3.2.2.7

308

Report Screen

This is a very basic sample report that shows downtime information for a line during a given date range. It
can be expanded to include much more information. It is built using the Ignition Reporting Module and
presents data provided by the OEE Downtime and Scheduling module. All the flexibility of how data is
presented in the analysis screen is also available in reports and multiple analysis results can be included
in reports.
In addition to viewing reports in a screen, they can be printed, saved to PDF, HTML or image.

Sam ple Report

3.2.3

Dashboard

The executive dashboard provides a high level view of OEE, downtime, and production information.
3.2.3.1

Area Summary

The Dashboard Area Summary shows OEE, Downtime, and Production and Waste Count comparisons
between different areas through various graphs. The slide at the bottom of the page causes the date to be
changed, allowing the user to select a specific day or time, or a broad range of dates to view. These
graphs may also be saved or printed by right-clicking on the desired graph.

Inductive Automation

OEE Downtime

309

Area Sum m ary Screen

Line Graph Settings

There are many settings for lines graphs which can be adjusted by right-clicking on a line graph. These
options can be used to improve graphs and select specific areas to save and print.
Mode
Zoom: Allows the user to click and drag over the specific area of the graph that he or she wants to
enlarge.
Pan: Allows the user to click and drag to move to a different area of the graph.
Mark: Gives the domain and range values of a single line at 12:00 AM on the day selected by clicking
on the graph.
X-trace: Gives the domain value of all lines on the graph at 12:00 AM on the day selected by clicking
on the graph.
Background
The background color of a line graph is white by default, but may be changed to black to allow the
user to see lighter colors.
Zoom
Allows the user to zoom in or out along the domain axis, the range axis, or both axes. Can also be
used with bar graphs.
Auto Range
Automatically selects the best range of values for the domain axis, the range axis, or both axes to in
order to see the entire graph for the date or time range selected at the bottom of the screen. Can also be
used with bar graphs.
Reset Axes
Resets both axes to their original ranges.

Inductive Automation

OEE Downtime
3.2.3.2

310

Enterprise Summary

Similar to the Area Summary, the Dashboard Enterprise Summary compares OEE, Production
Counts, Downtime, and Waste Counts between different enterprises in a production, or a single
enterprise over time. The slide at the bottom of the page causes the date to be changed, allowing the
user to select a specific day or time, or a broad range of dates to view. These graphs may also be saved
or printed by right-clicking on the desired graph.

Enterprise Sum m ary Screen

Line Graph Settings

There are many settings for lines graphs which can be adjusted by right-clicking on a line graph. These
options can be used to improve graphs and select specific areas to save and print.
Mode
Zoom: Allows the user to click and drag over the specific area of the graph that he or she wants to
enlarge.
Pan: Allows the user to click and drag to move to a different area of the graph.
Mark: Gives the domain and range values of a single line at 12:00 AM on the day selected by clicking
on the graph.
X-trace: Gives the domain value of all lines on the graph at 12:00 AM on the day selected by clicking
on the graph.
Background
The background color of a line graph is white by default, but may be changed to black to allow the
user to see lighter colors.
Zoom
Allows the user to zoom in or out along the domain axis, the range axis, or both axes. Can also be
used with bar graphs.
Inductive Automation

OEE Downtime

311

Auto Range
Automatically selects the best range of values for the domain axis, the range axis, or both axes to in
order to see the entire graph for the date or time range selected at the bottom of the screen. Can also be
used with bar graphs.
Reset Axes
Resets both axes to their original ranges.
3.2.3.3

Impromptu Analysis

See Data Analysis.

3.2.3.4

Line Summary

The Dashboard Line Summary is also similar to the Dashboard Area Summary. After selecting a line,
the OEE, Production Counts, and Run Time for that line can be viewed. Downtime by Cell is also
available on this screen, showing which cells could by upgraded or changed to improve efficiency.
Another important element on this screen is the Top Downtime Reasons graph, which displays downtime
reasons, such as a labeler running out of labels, and the total amount of downtime that is caused each
event. This increases the amount of information that can used to increase efficiency. The slide at the
bottom of the page causes the date to be changed, allowing the user to select a specific day or time, or a
broad range of dates to view. These graphs may also be saved or printed by right-clicking on the desired
graph.

Line Sum m ary Screen

Line Graph Settings

There are many settings for lines graphs which can be adjusted by right-clicking on a line graph. These
options can be used to improve graphs and select specific areas to save and print.

Inductive Automation

OEE Downtime

312

Mode
Zoom: Allows the user to click and drag over the specific area of the graph that he or she wants to
enlarge.
Pan: Allows the user to click and drag to move to a different area of the graph.
Mark: Gives the domain and range values of a single line at 12:00 AM on the day selected by clicking
on the graph.
X-trace: Gives the domain value of all lines on the graph at 12:00 AM on the day selected by clicking
on the graph.
Background
The background color of a line graph is white by default, but may be changed to black to allow the
user to see lighter colors.
Zoom
Allows the user to zoom in or out along the domain axis, the range axis, or both axes. Can also be
used with bar graphs.
Auto Range
Automatically selects the best range of values for the domain axis, the range axis, or both axes to in
order to see the entire graph for the date or time range selected at the bottom of the screen. Can also be
used with bar graphs.
Reset Axes
Resets both axes to their original ranges.
3.2.3.5

Site Summary

The Dashboard Site Summary shows OEE, Production Counts, Downtime, and Waste Count
comparisons between different sites through bar or line graphs. The slide at the bottom of the page
causes the date to be changed, allowing the user to select a specific day or time, or a broad range of
dates to view. These graphs may also be saved or printed by right-clicking on the desired graph.

Site Sum m ary Screen

Line Graph Settings

Inductive Automation

OEE Downtime

313

There are many settings for lines graphs which can be adjusted by right-clicking on a line graph. These
options can be used to improve graphs and select specific areas to save and print.
Mode
Zoom: Allows the user to click and drag over the specific area of the graph that he or she wants to
enlarge.
Pan: Allows the user to click and drag to move to a different area of the graph.
Mark: Gives the domain and range values of a single line at 12:00 AM on the day selected by clicking
on the graph.
X-trace: Gives the domain value of all lines on the graph at 12:00 AM on the day selected by clicking
on the graph.
Background
The background color of a line graph is white by default, but may be changed to black to allow the
user to see lighter colors.
Zoom
Allows the user to zoom in or out along the domain axis, the range axis, or both axes. Can also be
used with bar graphs.
Auto Range
Automatically selects the best range of values for the domain axis, the range axis, or both axes to in
order to see the entire graph for the date or time range selected at the bottom of the screen. Can also be
used with bar graphs.
Reset Axes
Resets both axes to their original ranges.
3.2.3.6

TEEP

The Dashboard TEEP screen compares the TEEP and the OEE between all lines with production data
though bar graphs. The slide at the bottom of the page causes the date to be changed, allowing the user
to select a specific day or time, or a broad range of dates to view. These graphs may also be saved or
printed by right-clicking on the desired graph. For more information on TEEP, click here. For more
information on OEE, click here.

TEEP Screen

Inductive Automation

OEE Downtime

3.2.4

314

Production Model

A production model defines your manufacturing or process in tree view form. It enables an organized
manor to easily configure, control and analysis your facility. See Production Model for more detailed
information.
3.2.4.1

Production Item Settings

General Settings
When you click on the "Your Site" production item in the production model, there are settings that are
accessible in the open workspace. By clicking the General tab, the current general settings are visible
and can be changed. As shown below the Default Shift Start Time settings are visible and can be
changed.

Default Shift Start Tim e Settings

When configuring a production Area the Shift Start Times can be inherited from the production Site or
overridden. The same is true for production Lines.
Workday Routine Settings
From the Schedule tab, daily activities that are considered scheduled downtime can be entered. This
includes activities such as breaks, meals, safety meetings, etc. When production runs are scheduled
they are scheduled around these activities.

Inductive Automation

OEE Downtime

315

Workday Routine List

These settings can be inherited or overridden by a production Area. A production Line can in turn inherit
or override the entries from the production Area.
OEE Settings
For OEE values to be calculated, production data is needed. This is configured by clicking on the OEE
tab and configuring the system to collect production counts. True OEE calculations use product infeed
counts to determine OEE Performance. The production outfeed is used to determine waste which affects
OEE Quality. At a minimum, a product outfeed for the production line must be configured, but for more
accurate results, a product infeed should be configured as well.

Line OEE Settings

Optionally, each cell can be configured with product outfeed and infeeds. This will enable OEE data to be
Inductive Automation

OEE Downtime

316

calculated for each cell as well as the production line.

Product Infeed Settings

The Count SQL Tag property is set to the Ignition SQLTag that will provide infeed production counts. This
is typically from a PLC, but can be from a barcode scanner, database or other source. The programming
required in the PLC is simplified greatly because no handshaking or start of resets are required. In the
PLC, the counter can simply rollover from the maximum value of a counter back to 0 and continue
counting. The OEE module tracks the production count at the start of the run and all rollovers. This
tracking is even maintained during power outages.
Downtime Settings
The OEE Downtime and Scheduling module uses a single numeric value, typically read from a PLC, to
determine the current state. This applies to both a production line or production cells of a line. If the state
value is 0, it is considered that the line or cell is idle and if it is 1, it is considered the line or cell is running.
State values 2 on up (typically to 32767), are user defined and can be automatically detected or can tied
to a operator selectable downtime reason.
Below is a list containing sample downtime reasons. Notice the Record Downtime, Planned Downtime
and Operator Selectable columns. If the Record Downtime option is true, then downtime events with
this reason will be treated as unplanned downtime. This allows for downtime reasons such as outfeed
backup to not be counted as unplanned downtime. If the Planned Downtime option is true, then
downtime events with this reason will be treated as planned downtime.

Inductive Automation

OEE Downtime

317

Cell Dow ntim e List

Downtime tracking can be done three different methods. The first two methods focus on the primary
reason the production line is not producing product. The third method tracks all downtime for production
cell regardless of whether it caused production loss for the line.
In cases where there is a single PLC controlling the production line, downtime events can be read from a
single numeric value representing the line state. The State SQLTag and downtime reasons are
configured in the production line.
It is common that each cell of a production line has its own PLC. To set up communication between the
PLC and a master PLC, and to add the logic to determine the cause of why production line is not
producing product is a complex process; however, the OEE Downtime module eliminates this complexity
with a feature called Use Key Reason Detection. When this option is selected on the Downtime tab for
a line, the module will determine the primary cause as to why the line is not producing product. This
method uses the flow of the line to determine the cause for the line not being able to product. It also
assumes there is a primary cell that, if down, will cause the line to stop producing product. If the first cell
is down for a reason that is not configured as Record Downtime, the next cell will be checked. If it is down
for a reason that is configured as Record Downtime, then it will be assigned as line downtime cell and
reason. When the second cell that caused the line downtime restarts but the first cell has not started yet
because its discharge is still backed up, then the original cell and reason will still be the cause until the
first cell restarts.

Flow of Key Reason Detection

Inductive Automation

OEE Downtime
3.2.4.2

318

Adding Production Items

New production model items can be added by right clicking on the parent item. A popup menu with the
available options will appear. For example, right clicking on the "Your Area" production item, then clicking
on the New Production Item > New Production Line menu item will add a new line below "Your Area."

Adding A New Production Line

After production items are added, their OEE downtime and scheduling configuration settings and runtime
values are available for use in Ignition windows, transaction groups, scripting, etc. Before values from the
Production OPC Server can be used, they must be added to the Ignition SQLTags. This is done in the
designer by selecting the SQLTags Browser and clicking on the
icon. This will cause the OPC
Browser to appear. Next, drill down in the Production node within the OPC Browser. Drag any of the
Production OPC Values over to the SQLTags Browser as depicted below.

Add Production OPC Server Values to SQLTags

3.2.5

Configuration

Because the OEE Downtime and Scheduling Module is built on the Ignition platform, configuration is done
using the Ignition Designer.

Inductive Automation

OEE Downtime
3.2.5.1

319

Components

In addition to the components that come with Ignition, the OEE Downtime and Scheduling Module
provides additional components that make implementing an OEE, downtime and scheduling system
easier. These components greatly reduce, or in some cases eliminate, the need for custom SQL
statements and scripting.

Schedule Com ponents

OEE and Dow ntim e Com ponents

Production Com ponents

For example the Production Line Selector component

, allows users to select a production line.
When a new production line is added to the system, it will automatically appear in the list as shown below.
No SQL statements, script or configuration is needed.

Production Line Selector Com ponent

If the functionality of the components that come with OEE Downtime and Scheduling Module does not
meet the project requirements, you can still use custom SQL statements, customer script and the
standard Ignition components.
3.2.5.2

Creating a Screen

To add a new window in Ignition, right-click on the Windows node in the Project Browser and select the
New Window menu item.

Inductive Automation

OEE Downtime

320

Adding a New Window

A new blank window will appear. Here is an example of a window you can create in Ignition.
First, drag a Analysis Controller, Production Line Selector, Production Bar Chart and Date Range
components onto the new window as shown below.

Exam ple of a New Window

Inductive Automation

OEE Downtime

321

With the Analysis Controller selected, enter in the properties as shown below.

Property Editor

Now we will bind the date properties of the Analysis Controller component to the Date Range date
properties. This will allow the user to select the date range that will affect the analysis results.
Do so by clicking the
for the Start Date property, select Property binding type, navigate to the Date
Range component and select Start Date property as shown below. Then click on the OK button.

Property Selector

Inductive Automation

OEE Downtime

322

Do the same for the End Date property, but select the End Date property of the Date Range component.
To allow the users to filter the analysis results by production line, we need to bind the Analysis Controller
Line filter property to the Production Line Selector component.
Click on the
for the Line property, select Property binding type, navigate to the Production Line
Controller component and select Selected Line Name property as shown below. Click the OK button.

Property Selector

Now, click the Production Bar Chart on the new window. Next click the
for the Data property, select
Property binding type, navigate to the Analysis Controller component and select the Chart Data property
as shown below. Click the OK button.

Inductive Automation

OEE Downtime

323

Property Selector

To test, click on the preview button

. This will allow use to use the screen as a user.

Select "Line 1" in the Production Line Selector component and you should see result as shown below.

Finished Exam ple Window

Go ahead and play with the selected line and date range.

Inductive Automation

OEE Downtime

3.3

324

Configuration

There are two areas to configure the OEE Downtime and Scheduling module. The first area is in the
Ignition Gateway and affects all MES Modules.
The second is in the Ignition Designer and is used to configure production models, user screens and the
like. These settings are saved in an Ignition project and can be backed up and restored using the built-in
project backup and restore features of Ignition.

3.3.1

MES Module Configuration

The OEE, Downtime and Scheduling is just one of the MES (Manufacturing Execution System) modules
that has settings which can be set.
3.3.1.1

Datasource Settings

OEE, downtime and schedule data is stored in databases external to Ignition. These database(s) are
setup in the gateway configuration section by selecting the Databases> Connections section from the
left-hand configuration menu in Ignition. See the Ignition documentation for more information on setting up
a database connection.
Below shows a typical database connection that is required for the OEE, Downtime and Scheduling
module.

Sam ple Database Connection

To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules.
If more than one database connection exists, then the desired database connection can be selected to be
used by the MES modules as shown below.

Inductive Automation

OEE Downtime

325

MES Module Settings Page

Runtime Database
The runtime database is where production and downtime data is stored during a production run. During a
production run data is logged every minute or partial minute if a downtime event occurs, so a larger
amount of data is stored in the runtime database.
Data Retention Duration
This setting specifies the number of days to retain the data in the runtime database after a production run
has completed. The default setting is 30 days, This allows for viewing current and past production run
information, down to the minute, for the past 30 days.
Analysis Database
The analysis database is where summarized production and downtime data is saved. For single
production site installations, this can be the set to the same database as the runtime database. For multiproduction site installations, all sites must set the analysis database to the same database to allow for
enterprise analysis and reporting.
Analysis Database (Auxiliary)
The MES Modules will mirror the historical analysis data that is written to the local analysis database to
this database. For single site implementations, set this to "-none-". For multi-site implementations, set
this to the datasource for the common remote enterprise database.
Analysis Query Cache Duration
This setting represents the number of seconds to cache analysis results.

3.3.2

Production Model Configuration

A production model defines your manufacturing or process in tree view form. It provides an organized way
to easily configure, control and analyze your facility. It starts with your enterprise, which represents your
company, and continues down to the site (physical location), area, line and cells.
Inductive Automation

OEE Downtime

3.3.2.1

326

Production Model

The production model is configured within the Ignition designer and is accessed by selecting the
"Production" folder in the project browser. From here your enterprise, site, area(s), line(s) and cell(s) can
be added, renamed and deleted.

Production Model Tree

3.3.2.1.1 Enterprise Configuration

Adding an Enterprise
To add your enterprise, right-click on the "Production" folder in the project browser and select the New
Production Item > New Production Enterprise menu item. An enterprise named "New Enterprise" will
be added to the "Production" folder.
Renaming an Enterprise
To rename it to the name of your enterprise, right-click on it and select Rename, then enter the new
name.

Enterprise Nam e

Deleting an Enterprise
To remove an existing enterprise, right-click on the enterprise item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production enterprise. Please note
Inductive Automation

OEE Downtime

327

that the site, area(s), line(s) and cell(s) underneath the enterprise will also be permanently removed.

Inductive Automation

OEE Downtime

328

General Enterprise Settings

For the enterprise, there are only general settings. These settings are accessed by selecting the
enterprise item contained in the"Production" folder in the project browser and then selecting the
"General" tab as shown below.

Enterprise General Settings

Enabled

By default, added enterprises are enabled. It can be disabled by un-checking the

Enabled setting and saving the project. This will stop the OEE, downtime and
scheduling module from executing the enterprise, the site and all area(s), line(s) and
cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

3.3.2.1.2 Site Configuration

Adding a Site
To add your site, right-click on your enterprise folder in the project browser and select the New
Production Item > New Production Site menu item. A site named "New Site" will be added to the
enterprise folder.
Renaming a Site
To rename it to the name representing the site's physical location, right-click on it and select Rename,
then enter the new name.
Deleting a Site
To remove an existing site, right-click on the site item and select the Delete menu item. A window will
appear confirming that you permanently want to delete the production site. Please note that the area(s),
line(s) and cell(s) underneath the site will also be permanently removed.

Inductive Automation

OEE Downtime

329

New Site

General Site Settings

These settings are accessed by selecting the site item contained in the enterprise folder in the project
browser, and then selecting the "General" tab.
Enabled

By default, added sites are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the site and all area(s), line(s) and cell(s) that are underneath
it.

Description

This is an optional description and is just for your reference.

Shift 1:
Default Enabled If checked, shift 1 will be included during scheduling. If not checked, shift 1 will be
Default Start
Time

scheduled around.
The time of day that first shift starts. The first shift ends at the start of second shift.

Shift 2:
Default Enabled If checked, shift 2 will be included during scheduling. If not checked, shift 2 will be
Default Start
Time

scheduled around.
The time of day that second shift starts. The second shift ends at the start of third
shift.

Shift 3:
Default Enabled If checked, shift 3 will be included during scheduling. If not checked, shift 3 will be
Default Start
Time

scheduled around.
The time of day that third shift starts. The third shift ends at the start of first shift.

Note: The shift enabled and shift start times are the default for your production site and can be overridden
by the production area and/or production line.
Schedule Settings
These settings are accessed by selecting the site item contained in the enterprise folder in the project
browser and then selecting the "Schedule" tab as shown below. See Workday Routines for more
information.

Inductive Automation

OEE Downtime

330

Site Workday Routing List

Workday Routine Entry

See the Workday Routines section for more information.
Note: The workday routine entries are the default for your production site and can be overridden by the
production area and/or production line.
3.3.2.1.3 Area Configuration

Adding an Area
To add a production area, right-click on your site folder in the project browser and select the New
Production Item > New Production Area menu item. An area named "New Area" will be added to the
site folder. Multiple production areas can be added to your production site. Each area can represent a
physical or logical production area within your production site. Some examples of production areas are:
packaging, cracking, filtration, fabrication, etc.
Renaming an Area
To rename it to the name representing the production area, right-click on it and select Rename, then
enter the new name.
Deleting an Area
To remove an existing production area, right-click on the area item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production area. Please note that
the line(s) and cell(s) underneath the area will also be permanently removed.

New Area
Inductive Automation

OEE Downtime

331

Area General Settings

These settings are accessed by selecting the desired area item contained in the site folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added areas are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the area and all line(s) and cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Shift 1
Default Enabled If checked, shift 1 will be included during scheduling. If not checked, shift 1 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the site, select the
"Inherit From Parent" option.
The time of day that first shift starts. The first shift ends at the start of second shift. To
inherit the time of day that first shift starts setting from the site, select the "Inherit
From Parent" option.

Shift 2
Default Enabled If checked, shift 2 will be included during scheduling. If not checked, shift 2 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the site, select the
"Inherit From Parent" option.
The time of day that second shift starts. The second shift ends at the start of third
shift. To inherit the time of day that second shift starts setting from the site, select the
"Inherit From Parent" option.

Shift 3
Default Enabled If checked, shift 3 will be included during scheduling. If not checked, shift 3 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the site, select the
"Inherit From Parent" option.
The time of day that third shift starts. The third shift ends at the start of first shift. To
inherit the time of day that third shift starts setting from the site, select the "Inherit
From Parent" option.

Note: The shift start times are the default for your production site and can be overridden by the production
area and/or production line.
Area Schedule Settings
These settings are accessed by selecting the area item contained in the site folder in the project browser
and then selecting the "Schedule" tab as shown below. See the Site Schedule Settings section for more
information on workday routines.
If no area workday routine entries are entered, then they will be inherited from the production site as
shown below.

Inductive Automation

OEE Downtime

332

Area Workday Routine List

Workday Routine Entry

See the Workday Routines section for more information.
Note: The workday routine entries are the default for your production area and can be overridden by the
production line.
3.3.2.1.4 Line Configuration

Adding a Line
To add a production line, right-click on an area folder in the project browser and select the New
Production Item > New Production Line menu item. A line named "New Line" will be added to the area
folder. Multiple production lines can be added to a production area.
Renaming a Line
To rename it to the name representing the production line, right-click on it and select Rename, then enter
the new name.
Deleting a Line
To remove an existing production line, right-click on the line item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production line. Please note that
the cell(s) underneath the line will also be permanently removed.

New Line
Inductive Automation

OEE Downtime

333

Line General Settings

These settings are accessed by selecting the desired line item contained in the area folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added lines are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the line and cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Shift 1
Default Enabled If checked, shift 1 will be included during scheduling. If not checked, shift 1 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that first shift starts. The first shift ends at the start of second shift. To
inherit the time of day that first shift starts setting from the area, select the "Inherit
From Parent" option.

Shift 2
Default Enabled If checked, shift 2 will be included during scheduling. If not checked, shift 2 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that second shift starts. The second shift ends at the start of third
shift. To inherit the time of day that second shift starts setting from the area, select
the "Inherit From Parent" option.

Shift 3
Default Enabled If checked, shift 3 will be included during scheduling. If not checked, shift 3 will be

Default Start
Time

Additional
Factors

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that third shift starts. The third shift ends at the start of first shift. To
inherit the time of day that third shift starts setting from the area, select the "Inherit
From Parent" option.
Additional Factors are user defined data points that are logged along with the
production and downtime information. Once they are logged, they can be shown in
charts, tables and reports. Additionally, other analysis can be done by filtering and/or
setting up comparisons by their values.

Any value that can be read from an Ignition SQLTag can be added as a additional factor. This
includes, values from barcode readers, databases, calculations, PLCs, or values derived from
scripts, etc.
Example: An additional factor named cardboard manufacturer can be added. The operator can select
the manufacturer that provided the cardboard or it can be obtained from some other source. Now,
OEE and downtime results can be shown for each cardboard manufacturer. This can identify quality
problems with raw material that directly affect efficiencies.

Inductive Automation

OEE Downtime

334

Below is an example of an operator additional factor. The operators name will be logged along with the
production and downtime data. By doing so, OEE and downtime information can be filtered and
grouped by the operator name.

Additional Factor List

Adding an Additional Factor

To add an additional factor, right-click anywhere on the additional factor table and select the New menu
item. A dialog box will appear to allow entry of a new additional factor as shown below.

Additional Factor Settings

Factor Name
The required name of the additional factor is used to reference one additional factor from another. You
can have any number of additional factors, but user usability will be hindered if too many are added. This
is because the additional factors are added to user menus and if too many are added, the menus can
become too long and confuse the end user.
Inductive Automation

OEE Downtime

335

The name given to an additional factor should be meaningful to the end user. Again, this is because
additional factors appear in menus allowing the end user to filter and group analysis and report data by
them.
Factor Description
The optional description is just for reference or to keep internal notes about the additional factor.
Factor SQLTag
The required SQLTag is the source of the data value that will be logged. It is an Ignition SQLTag and the
values can come from a PLC, a database query, other device in the field such as a barcode reader,
expression, user input, or script. This opens the door to mesh any type of outside data into the MES
module analysis and reporting.
Any type (format) of data that can be stored in an SQLTag can be logged. If SQLTag value is a string,
then the end user can filter and group by the additional factor. If the SQLTag is a number, the option to
filter and group by the additional factor will not be shown to the end user.
The SQLTag can be manually typed or pasted into the Factor SQLTag edit box. Optionally, clicking on
the

icon will display a browser where a SQLTag can be selected.

Editing an Additional Factor

To edit an existing additional factor, right-click on the desired entry in the additional factor table and select
the Edit menu item. A dialog box similar to the add dialog box will appear, allowing editing of the additional
factor.
Deleting an Additional Factor
To remove an existing additional factor entry, right-click on the desired entry in the additional factor table
and select the Delete menu item. A window will appear confirming that you want to remove the additional
factor. The additional factor will no longer be logged. However, any production runs that occurred before
the additional factor was deleted, will still show in the analysis and reporting.
Line Schedule Settings
These settings are accessed by selecting the line item contained in the area folder in the project browser
and then selecting the "Schedule" tab as shown below. See the Site Schedule Settings section for more
information on workday routines.
If no area workday routine entries are entered, then they will be inherited from the production area as
shown below.

Inductive Automation

OEE Downtime

336

Line Workday Routine List

Workday Routine Entry

See the Workday Routines section for more information.
Other Line Schedule Settings
Default Schedule
Rate

This default production rate used for scheduling purposes. Because the standard
production rate is typically not achieved, a scheduling rate is used when
determining the work order finish time during scheduling. The actual scheduling
rate used is determined from the product code and line that is being scheduled.

Schedule Rate
Period

The period of time used for the scheduling rate. The options are Hour and Minute.

Auto Start
Schedule Entries

If true, the scheduled entries on the calendar will automatically start at the
scheduled time. If false, scheduled entries can be chosen out of order and started
manually, typically by the operator clicking the Start button.

Auto Start
Production After
Changeover

Determines the behaviour when the scheduled change over time has expired. If
true, the production run will automatically start. If the line is not running, then
downtime will start being accumulated and the reason code will be set to the
Changeover Overrun Reason Code that was set in the Downtime configuration
section.
If false, the production run must be started by some other means. Typically, this is
done by the operator clicking the Start button but it can be accomplished by
programmatically setting the Enable Run property for the line.

Inductive Automation

OEE Downtime

337

Line OEE Settings

The Line OEE settings are accessed by selecting the line item contained in the area folder in the project
browser, and then selecting the "OEE" tab as shown below.
Before OEE calculations can be performed, production count information is required. At a minimum, the
outfeed production count for a production line is needed. Additional production count information can be
configured, which will result in more OEE calculations. For example, if the infeed production count is
configured for a production, then product accumulation and waste can also be calculated. Also, OEE
Performance uses items started vs. standard rate so that it is isolated from quality factors. When the
infeed production count is not used and quality is being used, then quality will not be isolated from
performance.
If a production line is configured for more than one infeed or outfeed, then accumulation and waste
calculations will be performed for each combination. For example, a production line can be configured to
track container, caps and product as infeeds, and a single outfeed of full containers. The independent
waste calculations for containers, caps and production will be performed. See Production Count Tracking
section for more information.
Below is an example showing a single infeed and outfeed configure for a production line.

Line OEE Settings

Primary Infeed
The production line OEE waste is derived from the primary infeed. If a production line has been configured for
multiple infeeds, select the infeed that is to be used for the waste calculation.
Product Infeeds
For each infeed, the OEE module will start calculating production rate per minute or production rate per
hour values. These values can be accessed through the Production OPC Server. See the section on
Production OPC Values, and the section on Product Infeed for more information.
Inductive Automation

OEE Downtime

338

Adding a Product Infeed

See the section on Adding a Product Infeed for details on adding product infeed entries.
Editing a Product Infeed
See the section on Editing a Product Infeed for details on editing product infeed entries.
Deleting a Product Infeed
See the section on Deleting a Product Infeed for details on deleting product infeed entries.
Primary Outfeed
The production line OEE waste is derived from the primary outfeed. If a production line has been
configured for multiple outfeeds, select the outfeed that is to be used for the waste calculation.
Product Outfeeds
For each outfeed, the OEE module will start calculating production rate per minute, or production rate per
hour values. These values can be accessed through the Production OPC Server. See the section on
Production OPC Values for more information. See the section on Product Outfeed for more information.
Adding a Product Outfeed
See the section on Adding a Product Outfeed for details on adding product outfeed entries.
Editing a Product Outfeed
See the section on Editing a Product Outfeed for details on editing product outfeed entries.
Deleting a Product Outfeed
See the section on Deleting a Product Outfeed for details on deleting product outfeed entries.
Product Waste
For each waste entry, the OEE module will start tracking true waste count values. These values can be
accessed through the Production OPC Server. See the section on Production OPC Values for more
information. See the section on Product Waste for more information.
Adding a Product Waste Entry
See the section on Adding a Product Waste Counter for details on adding product waste entries.
Editing a Product Outfeed
See the section on Editing a Product Waste Counter for details on editing product waste entries.
Deleting a Product Outfeed
See the section on Deleting a Product Waste Counter for details on deleting product waste entries.

Inductive Automation

OEE Downtime

339

Waste Calculation Methods

Waste Calculation Methods

There are several ways to calculate the amount of waste coming from a production line:
None
No waste calculation methods will be used to determine waste counts.
Run Waste Count Tag
Waste will be calculated based on what is entered in the Run Waste Count tag. This may be a unique
formula used to calculate waste or a manual entry of the waste count.
Started vs. Finished
When this method is used, outfeed will be compared to infeed to determine how many units were lost
to waste. If 1000 units enter the production line, and 900 finished products exit the production line, then
it is assumed that 100 units were lost to waste. A Waste Transit time other than 0 must be entered for
the primary outfeed. The Waste Transit time should be the normal amount of time a production unit
takes to travel from infeed (started) to outfeed (finished).
Product Waste Entries
In order to calculate waste by this method, one or more entries must be in the Product Waste table.
The waste from each entry is added together to equal the total amount of waste. For example, there
may be two cells on the line that inspect and discard faulty products. If the first cell discarded 10 units,
and the second cell discarded 5 units, the total waste count would be 15 units.
Sum Product Waste From Each Cell
This method will sum up each of the cell's waste values. Product Waste Entries will be ignored.
Ignore Changeover Overrun Production
Changeover overrun is the state a line is in when a schedule is selected but the run has not be started.
(The "Production After Changeover" property must also be set, see Line Schedule Settings.)
During changeover overrun, any production and waste counts that are seen will be recorded even though
the run has not been officially started.
If this property is set to true then any production or waste is not recorded until the run is started
(changeover overrun recording is canceled). This can be used if still wish to record that the changeover
time has been exceeded.
Line Downtime Settings
Inductive Automation

OEE Downtime

340

These settings are accessed by selecting the line item contained in the site folder in the project browser
and then selecting the "Downtime" tab as shown below. Once downtime reasons have be added, the
OEE, Downtime and Scheduling module will either check the list if the line stops running or allow the
operator to select reason. See the section on Downtime Reasons for more information.

Line Dow ntim e Settings

Downtime Detection Method

To determine the reason a production line or process is down, set the Downtime Detection Method
setting:
1. Select Initial Reason to select the initial cell that is down as the reason the line is down. If there is
a cell group on the line and the Minimum Cells Running Threshold has not been reached for that
cell group, the first cell with recordable downtime within the cell group is the reason that the line is
down. If the Minimum Cells Running Threshold has been reached, no part of the cell group will be
recorded as the cause of downtime, and the next cell or cell group will be examined.
2. Select Key Reason to select the first cell, in the order they appear in the designer, that is down as
the reason the line is down. The line state will be checked first, overriding the cell state if the line is
already down. If there is a cell group on the line and the Minimum Cells Running Threshold has not
been reached for that cell group, the last cell within the cell group that guarantees the threshold will
not be reached with recordable downtime is the reason that the line is down. If the Minimum Cells
Running Threshold has been reached, no part of the cell group will be recorded as the cause of
downtime, and the next cell or cell group will be examined.
3. Select Line State to ignore the cells and use the value of the State SQLTag that is configured for
the line.
See the section on Downtime Reasons for more information on each method.

Inductive Automation

OEE Downtime

341

State SQLTag
This SQLTag is to read the current state of the line or process. Note that if this tag is set, then if its
current state is not 1 it will supersede Key Reason or Initial Reason methods states.
It is an Ignition SQLTag and the values can come from a PLC, a database query, other device in the field
such as a barcode reader, an expression, user input, or script.
The data type (format) of the SQLTag containing the state must be a number. The SQLTag can be
manually typed or pasted in to the Factor SQLTag edit box. Optionally, clicking on the
a browser where a SQLTag can be selected.

icon will display

Remote Operator Reason Code SQLTag

This code will allow changing of the active downtime Operator reason code from a tag instead of directly
in the downtime table. It is up to you to determine the proper code to write to the tag. If the code is not
valid then the code will not be changed. For instance, if the current active code is from the "Capper" cell of
the line then the remote code must be an operator selectable code from the "Capper".
Downtime Reasons
Adding a Downtime Reason
See the section on Adding a Downtime Reason for details on adding downtime reason entries.
Editing a Downtime Reason
See the section on Editing a Downtime Reason for details on editing downtime reason entries.
Deleting a Downtime Reason
See the section on Deleting a Downtime Reason for details on deleting downtime reason entries.
Short Downtime Threshold Seconds
Short downtime are events that last a small specified time, 120 seconds for instance. Short events will
not affect the OEE availability calculation. If set to 0 then all downtime events are considered long and will
always affect the OEE availability calculation. This setting affects this Line and all Cells associated to this
Line. Short downtime events are always recorded and can be displayed via the analysis components.
Run Disabled Reason Code
Anytime a production run is ended and then later resumed, this reason code will be used as a downtime
reason. A downtime reason with the same reason code must exist in the downtime reason table. The
reason can be set to planned or unplanned downtime to produce the desired results during analysis and
reporting.
Changeover Time Reason Code
When changeover time is scheduled for a production run, but production does not begin when the
changeover ends, this reason code will be used as a downtime reason. A downtime reason with the
same reason code must exist in the downtime reason table. The reason can be set to planned or
unplanned downtime to produce the desired results during analysis and reporting.
See the section on Downtime Reasons for more information.
3.3.2.1.5 Cell Group Configuration

Adding a Cell Group

To add a production cell group, right-click on a line folder in the project browser and select the New
Production Item > New Production Cell Group menu item. A cell group named "New Cell Group" will
Inductive Automation

OEE Downtime

342

be added to the line folder. Multiple production cell groups can be added to a production line.
Renaming a Cell Group
To rename it to the name representing the production cell group, right-click on it and select Rename,
then enter the new name.
Deleting a Cell Group
To remove an existing production cell group, right-click on the cell group item and select the Delete menu
item. A window will appear confirming that you permanently want to delete the production cell group.

Adding a Cell Group

Cell Group General Settings

These settings are accessed by selecting the desired cell group item contained in the line folder in the
project browser and then selecting the "General" tab.
Enabled

By default, added cell groups are enabled. It can be disabled by un-checking the
Enabled setting and saving the project. This will stop the OEE, downtime and
scheduling module from executing the cell group.

Description

This is an optional description and is just for your reference.

Cell Group OEE

There are no additional settings for cell group OEE; however, the OEE of the cell group is calculated by
averaging the OEE and Production Counts of all the cells within the group.
Cell Group Downtime Settings
Minimum Cells Running Threshold: This is the minimum number of cells that must be running within the

cell group in order for the cell group to be considered running. If there are five cells within a cell group, and
the Minimum Cells Running Threshold is 3, then three cells must be running. If two out of the five cells are
Inductive Automation

OEE Downtime

343

down, there are still three cells running, so the cell group is running. If three out of the five cells are down,
there are only two cells running, meaning the cell group is down because the threshold has not been met.
3.3.2.1.6 Cell Configuration

Adding a Cell
To add a production cell, right-click on a line folder in the project browser and select the New Production
Item > New Production Cell menu item. A cell named "New Cell" will be added to the line folder. Multiple
production cells can be added to a production line.
Renaming a Cell
To rename it to the name representing the production cell, right-click on it and select Rename, then enter
the new name.
Deleting a Cell
To remove an existing production cell, right-click on the cell item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production cell.

Deleting a Cell

Cell General Settings

These settings are accessed by selecting the desired cell item contained in the line folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added cells are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the cell.

Description

This is an optional description and is just for your reference.

Inductive Automation

OEE Downtime

344

Cell OEE Settings

The Cell OEE settings are accessed by selecting the cell item contained in the line folder in the project
browser and then selecting the "OEE" tab as shown below.
For production cells, the OEE settings are optional and are only needed if you want to track efficiencies,
waste or monitor production rate by individual production cells. It is also important to note that the OEE
information is not required to track downtime for the cell.
Before OEE calculations can be performed, production count information is required. At a minimum, the
outfeed production count for a production cell is needed if tracking OEE for it is desired . Additional
production count information can be configured, which will result in more OEE calculations. For example,
if the infeed production count is configured for a production, then product accumulation and waste is
calculated.
If a production cell is configured for more than one infeed or outfeed, then accumulation and waste
calculations will be performed for each combination. For example, a production cell can be configured to
track containers and caps as infeeds and a single outfeed of full containers. The independent waste
calculations for containers and caps will be performed. See Production Count Tracking section for more
information.
Below is an example showing a single infeed and outfeed configure for a production cell.

Cell OEE Settings

Primary Infeed
The production cell OEE waste is derived from the primary infeed. If a production cell has been
configured for multiple infeeds, select the infeed that is to be used for the waste calculation.

Inductive Automation

OEE Downtime

345

Product Infeeds
For each infeed, the OEE module will start calculating production rate per minute, production rate per
hour values. These values can be accessed through the Production OPC Server. See the section on
Production OPC Values for more information. For the section on Product Infeed for more information.
Adding a Product Infeed
See the section on Adding a Product Infeed for details on adding product infeed entries.
Editing a Product Infeed
See the section on Editing a Product Infeed for details on editing product infeed entries.
Deleting a Product Infeed
See the section on Deleting a Product Infeed for details on deleting product infeed entries.
Primary Outfeed
The production line OEE waste is derived from the primary outfeed. If a production cell has been
configured for multiple outfeeds, select the outfeed that is to be used for the waste calculation.
Product Outfeeds
For each outfeed, the OEE module will start calculating production rate per minute, or production rate
per hour values. These values can be accessed through the Production OPC Server. See the section
on Production OPC Values, and the section on Product Outfeed for more information.
Adding a Product Outfeed
See the section on Adding a Product Outfeed for details on adding product outfeed entries.
Editing a Product Outfeed
See the section on Editing a Product Outfeed for details on editing product outfeed entries.
Deleting a Product Outfeed
See the section on Deleting a Product Outfeed for details on deleting product outfeed entries.
Product Waste
For each waste entry, the OEE module will start tracking true waste count values. These values can
be accessed through the Production OPC Server. See the section on Production OPC Values, and
the section on Product Waste for more information.
Adding a Product Waste Entry
See the section on Adding a Product Waste Counter for details on adding product waste entries.
Editing a Product Outfeed
See the section on Editing a Product Waste Counter for details on editing product waste entries.
Deleting a Product Outfeed
See the section on Deleting a Product Waste Counter for details on deleting product waste entries.
Waste Calculation Methods
There are several ways to calculate the amount of waste coming from a production cell:
None
No waste calculation methods will be used to determine waste counts.
Inductive Automation

OEE Downtime

346

Run Waste Count Tag

Waste will be calculated based on what is entered in the Run Waste Count tag. This may be a unique
formula used to calculate waste or a manual entry of the waste count.
Started vs. Finished
When this method is used, outfeed will be compared to infeed to determine how many units were lost
to waste. If 1000 units enter the production cell, and 900 finished products exit the production cell, then
it is assumed that 100 units were lost to waste. A Waste Transit time other than 0 must be entered for
the primary outfeed. The Waste Transit time should be the normal amount of time a production unit
takes to travel from infeed (started) to outfeed (finished).
Product Waste Entries
In order to calculate waste by this method, one or more entries must be in the Product Waste table.
The waste from each entry is added together to equal the total amount of waste. For example, there
may be two points on the cell that inspect and discard faulty products. If the first point discarded 10
units, and the second point discarded 5 units, the total waste count would be 15 units.
Cell Downtime Settings
These settings are accessed by selecting the line item contained in the site folder in the project browser
and then selecting the "Downtime" tab as shown below. Once downtime reasons have be added, the
OEE, Downtime and Scheduling module will either check the list if the line stops running or allow the
operator to select the reason. See the section on Downtime Reasons for more information.

Cell Dow ntim e Settings

Log Downtime Details

Cell downtime logging is independent from line downtime. To log all of the downtime details for a cell,
check the Log Downtime Details setting. This will cause all downtime events for the cell to be logged to
the database. If this amount of detail is not used, it is recommended to uncheck this setting as it saves
space in the database.
See Downtime Reasons for more information.
State SQLTag
This is the SQLTag used to read the current state of the cell. It is an Ignition SQLTag and the values can
come from a PLC, a database query, other device in the field such as a barcode reader, an expression,
Inductive Automation

OEE Downtime

347

user input, or script.

The data type (format) of the SQLTag containing the state must be a number.
The SQLTag can be manually typed or pasted in to the Factor SQLTag edit box. Optionally, clicking on
the

icon will display a browser where a SQLTag can be selected.

Downtime Reasons
Adding a Downtime Reason
See the section on Adding a Downtime Reason for details on adding downtime reason entries.
Editing a Downtime Reason
See the section on Editing a Downtime Reason for details on editing downtime reason entries.
Deleting a Downtime Reason
See the section on Deleting a Downtime Reason for details on deleting downtime reason entries.
Line DT Bypass Reason Code
When a cell is in bypass, this is the reason code that will be recorded. It will override the actual code that
is returned in the State SQL Tag. This allows any reports or displays to show the desired state while the
cell is bypassed.
A cell may be placed in bypass at runtime by selecting the "Line DT Bypass" Production OPC tag for this
cell.

3.3.3

Workday Routines

Workday routine activities can be breaks, lunches, safety meetings or anything that is scheduled, nonproduction times that occur every day.
Scheduling
When production runs are scheduled by the production planner, these workday routine items are
scheduled around.
For example if you schedule a run and it would take 4 hours to produce the scheduled quantity, a 30
minute workday routine will extend a schedule end time by 30 minutes if the schedule falls within the
routines start and end times.
Line Running
If no reason code is entered or it does not match a downtime reason code for the line then it will be
ignored.
If a reason code is entered that matches a downtime reason for the line then that reason will be triggered
at the start time and ended at the end time. When the reason code is defined as a planned downtime then
the time will not count against the OEE of the production run.
NOTE: A matched reason code will override any other downtime events that occur on the line during the
defined time.
Adding a Workday Routine
To add a workday routine entry, right-click anywhere on the table containing workday routines and select
the New menu item. A dialog box will appear to allow entry of a name, start time, end time and optional
reason code for the workday routine entry as shown below.

Inductive Automation

OEE Downtime

348

Workday Routine Entry Settings

Editing a Workday Routine

To edit an existing workday routine entry, right-click on the desired entry in the workday routine table and
select the Edit menu item. A dialog box similar to the add dialog box will appear allowing editing of the
entry.
Deleting a Workday Routine
To remove an existing workday routine entry, right-click on the desired entry in the workday routine table
and select the Delete menu item. A window will appear confirming that you want to remove the workday
routine entry.
Import/ Export
To export workday routine entries, right-click anywhere on the table containing workday routines and
select the Export menu item. A dialog box will appear to allow selection of an existing file or the typing in
of a name of the new file to save the workday routine entries to. If a file extension is not entered, then the
default .csv will be used.
To import workday routine entries, right-click anywhere on the workday routine table and select the Import
menu item. A dialog box will appear to allow selection of a comma separated values (csv) formatted file.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing multiple workday routine entries.

Name,Start Time,End Time,Reason Code

"Graveyard shift break 1","1:00 AM","1:15 AM","5200"
"Graveyard shift meal","3:00 AM","3:30 AM","5300"
"Graveyard shift break 2","5:00 AM","5:15 AM","5400"
"Day shift break 1","9:00 AM","9:15 AM","6200"
"Day shift meal","11:00 AM","11:30 AM","6300"
"Day shift break 2","1:00 PM","1:15 PM","6400"
"Swing shift break 1","5:00 PM","5:15 PM","7200"
"Swing shift meal","7:00 PM","7:30 PM","7300"
"Swing shift break 2","9:00 PM","9:15 PM","7400"
Inductive Automation

OEE Downtime

3.3.4

349

Downtime Reasons

Downtime reasons allow the tracking of specific causes preventing a line or cell from running. Some
reasons are considered causes of downtime where others are not. For example, if the production cell
outfeed is backed up and there is no room to discharge product to, then it must shutdown. In this
example, it is simply normal operation for the cell and it is not causing the production line from producing
product. A cell further down the line is the cell preventing the production line from producing product.
Other downtime reasons may be planned. Any time that the production line is scheduled around, such as
breaks, lunches, safety meeting, disable shifts, etc., is planned and will not count against the production
line OEE Availability.
The OEE Downtime and Scheduling module has been designed to accommodate a variety of methods to
determine reasons that a production line is down. This was done because monitoring all downtime
reasons automatically is the ideal solution. But in the real world, this be difficult, costly, or just not practical
to detect downtime reasons automatically. For this reason it is important for downtime tracking software
to support both automatic reason detection and a manual override. For example: if an operator presses
the stop button because they see a bottle laying on its side feeding into a filler, then the only automatic
reason that can be detected is "operator pressed stop button". Now, the operator should be able to
override the reason with more specific information.
In applications where the production cell is not automated and work is performed completely by manual
labor, all downtime information can be entered manually from a predetermined list.
Downtime Reason Detection
For this reason, the OEE Downtime and Scheduling module determines the downtime reason from a
single numeric value. Single numeric values are stable and can only represent one state. Of course one
could use Expressions or script in Ignition to evaluate multiple values from the PLC and calculate a single
numeric value representing the downtime reason, but this degrades the reliability of determining downtime
reasons. Another benefit is that it is typically faster and reduces network traffic to read one value as
opposed to multiple scattered values from a PLC.
The reason code with the numeric value of 0 is reserved for idle and 1 is reserved to mean running. All
other reason codes are available for downtime reasons and is only limited by the maximum numeric value
your PLC can handle. When the OEE Downtime and Scheduling module detects a production line or cell
state that changed from a value of 1 (running), it will lookup the downtime reason from the state value. If
communication to the PLC fails, in the case when a electrical disconnect is shut off, the production line or
cell state is replaced with 0. If this happens during a production run, it will count as downtime.
Important:
Some systems may accommodate boolean logic to determine the downtime cause. However, consider
the various values from a PLC that are going to be used to determine the downtime reason. These
scattered values may come in from the PLC at different times and if the boolean logic resided in the OEE
Downtime and Scheduling module, then it may be determining the reason on partially current values.
Oops, now we have the incorrect reason and when all of the current values do arrive, what do we do? Do
we change the original reason, add a new downtime entry, or maybe put a delay in to allow for all of the
current values to arrive? None of these options are good solutions.
Automatic Detection
When the value of the State SQLTag changes to a value that is other than the numeric value of one, the
system will look for a matching reason code in the entries in downtime reasons table. If it is not found it
Inductive Automation

OEE Downtime

350

will replace then reason code with zero (0).

Manual Override
After an automatic reason has been triggered, the operator can override it will a more specific reason.
Both are logged and can be viewed in analysis and reporting. For details about how to disable manual
override see the Editable property in the Down Time Table section
Manual Only
For production lines that do not support automatic downtime detection, a completely manual
implementation can be setup. This is done by providing a line drop-down list, or other component, on the
operator screen that the user can use to select the current line state.
Line Downtime Versus Cell Downtime
It is important to understand the difference between line downtime and cell downtime. Line downtime,
which is only the downtime reasons that are preventing the production line from producing product, is
typically used to zero in and improve OEE. The cell downtime is used to look at trends and detect
maintenance issues before they cause line downtime. Consider a production line that has 25 cells. If 5 of
the cells are down all at the same time for unrelated reasons and only one of them is preventing product
from being produced on the line, then there will be a lot of noise (extra irrelevant data) to weed through.
Also, if a faster downstream cell stops, restarts and catches up, it may never affect the production of the
line as a whole. The OEE Downtime Module provides the best of both worlds and tracks both line
downtime and cell downtime.
For settings controlling cell downtime, see Cell Configuration under the Cell Downtime Settings section.
Short Downtime versus Long Downtime
Short downtime are events that last a small specified time, 120 seconds for instance. Short events will
not affect the OEE availability calculation. The OEE Downtime module provides this threshold on a per
line basis. If set to 0 then all downtime events are considered long and will always affect the OEE
availability calculation.
Detecting Line Downtime
In the OEE Downtime Module, there are multiple options for detecting line downtime reasons. The options
have been added to accommodate the wide variety of manufacturing processes. Below is a description of
each method along with the situations where it can be used.
As you read through the methods described below, think of the effort required to manually implement
them, whether done in the PLC or in Ignition.
Initial Reason
The concept of this method is the first cell that went down for a unplanned reason is the cause for the line
not being able to produce product.
When a cell first goes down, the date and time is recorded. If multiple cell are down, they will each have
their own date and time that it went down. The data and time for each down cell is looked at to determine
the initial cell that went down and will be assigned as the cell causing the line downtime along with its
reason. If the initial cell restarts, then the other down cells are looked the next cell in chronological order
that went down. If there are two or more cells that went down at the same time, then it will use the order
that they appear in the designer.
If there are no cells down for an unplanned reason, then the line will return to running state.
Inductive Automation

OEE Downtime

351

This method should be used if all cells interact with one another. If any cell is down, then all other cells
have to stop. A continuous liquid mixing process where at each cell, new ingredients are added or mixing
or some other action is being performed fits into this category. If one cell stops, then all other upstream
cells have to stop because there is no where to put the liquid and all downstream cells have to stop
because there is not liquid to process. In this case the first cell that stopped is the cause for all other cells
to stop.
Key Reason
This method uses the flow of the line to determine the cause for the line not being able to produce
product. It also assumes there is a primary cell that, if down, will cause the line to stop producing product.
This method also uses the order of the cells as they are configured in the designer. If the first cell is down
for a reason that is not configured as Record Downtime, the next cell will be checked. If it is down for a
reason that is configured as Record Downtime, then it will be assigned as line downtime cell and reason.
When the second cell that caused the line downtime restarts but the first cell has not started yet because
its discharge is still backed up, then the original cell and reason will still be the cause of downtime until the
first cell restarts.
The concept behind this is that a faster downstream cell can go down, restart and catch up without ever
causing loss of production on the line.
This method should be used for packaging lines. If the first cell on the line keeps accepting raw material,
then the line will be producing product. However, in some situations, it could be the slowest machine
because it cannot catch up for lost production.
Line State
This method is used when the other methods are not appropriate. This method allows implementing
custom methods of line downtime detection. When using this method, all downtime reasons must be
entered into the line downtime reason table and not the cell downtime reasons table. This method will only
read the line downtime reason from the State SQLTag configured for the line to determine the line
downtime reason.
When using this method, detailed cell downtime tracking can still be used but it is isolated from the line
downtime reasons.
3.3.4.1

Adding a Downtime Reasons

To add a Downtime Reason, right-click anywhere in the Downtime Reasons table, and select "New" from
the menu. The following window will appear:

Inductive Automation

OEE Downtime

352

Adding a Dow ntim e Reason

Reason Name
The required reason name is used to reference one reason from another an must be unique within the
production line or cell. The reason name should be meaningful to the end user. This is because the end
user can filter and group analysis and report by the reason name.
Reason Code
The reason code is a required unique number to the cell that identifies the downtime reason. PLCs and
other equipment are more apt to handing numbers versus strings, therefore a reason code is used for
reference within the program.
The reason code 0 is reserved for idle.
The reason code 1 is reserved for running.
Record Downtime
If the Record Downtime option is true, then downtime events with this reason will be treated as
unplanned downtime. This allows for downtime reasons such as outfeed backup to not be counted as
unplanned downtime.
Planned Downtime
This option will make the reason Planned Downtime, meaning it is scheduled and will not be used in
computing the OEE.
Operator Selectable
This option selects if or how this reason may be selected by an operator. The options are:
Never
This reason will not be available to a user to over-ride any other reason. It will display only if it is the original
reason code detected by the state tag.

Always
This reason can be selected by a user to over-ride the original reason code detected.

Cannot Be Overridden
Inductive Automation

OEE Downtime

353

When this is the originally detected reason code it cannot be over-ridden with any other code.

If Parent Reason Detected

This reason will be available for user selection only if the originally detected reason is the parent of this sub-reason
(see Sub Reason of below).

Sub Reason Of
This option allows the user to to enter a new downtime reason as a child of another downtime reason.
The reasons are sorted by the Reason Code in numerical order, but child reasons will always be sorted
under their parent reason.

Exam ple of a Sub Reason

3.3.4.2

Editing a Downtime Reasons

To edit a Downtime Reason, select the existing Downtime Reason you wish to edit, then right-click and
select "Edit" from the menu. The same window used to add downtime reasons will appear, allowing the
information to be edited.
3.3.4.3

Deleting a Downtime Reasons

To delete a Downtime Reason, select the existing Downtime Reason you wish to remove, then right-click
and select "Delete" from the menu. A window will appear confirming that you permanently want to delete
the downtime reason.
3.3.4.4

Import / Export

To import downtime entries, right-click anywhere on the downtime table and select the Import menu item.
A dialog box will appear to allow selection of a comma separated values (csv) formatted file.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing multiple downtime entries.
Reason Name,Reason Code,Record Downtime,Planned Downtime,Operator
Selectable,Sub Reason Of
"Stop","0","true","false","0","-1"
"Machine Fault","3","true","false","0","-1"
"Machine Fault - Electrical","31","true","false","1","3"
"Machine Fault - Mechanical","32","true","false","1","3"
"Outfeed Backup","4","false","false","0","-1"
"Waiting For Product","6","true","false","0","-1"
Inductive Automation

OEE Downtime

354

"Scale Fault","8","true","false","3","-1"
"Over Temperature","9","true","false","0","-1"
"Scale Maintenance","20","true","false","2","-1"
"Container Jam","22","true","false","2","-1"
"Planned Shutdown","99","false","true","2","-1"
"Meal","100","false","true","2","-1"
"Break","101","false","true","2","-1"

To export downtime entries, right-click anywhere on the table containing downtime entries and select the
Export menu item. A dialog box will appear to allow selection of an existing file or the typing in of a name
of the new file to save the downtime entries to. If a file extension is not entered, then the default .csv will
be used.

3.3.5

Product Infeed

Product infeeds are used only to calculate waste or if infeed rate information is desired. This applies to
both production lines and production cells. If a production line or cell is configured for more than one
infeed or outfeed, then accumulation and waste calculations will be performed for each combination. For
example, a production line can be configured to track containers, caps and product as infeeds and a
single outfeed of full containers. The independent waste calculations for containers, caps and production
will be performed. See Production Count Tracking section for more information.
For each infeed, the OEE module will start calculating production rate per minute, or production rate per
hour values. These values can be accessed through the Production OPC Server. See the section on
Production OPC Values for more information.
3.3.5.1

Adding a Product Infeed

To add a product infeed entry, right-click anywhere on the product infeed table of a production line or cell
and select the New menu item. A dialog box will appear to allow entry of a name, count sql tag, maximum
raw count and production units as shown below.

Product Infeed Settings

Name
The required infeed name is used to reference one infeed from another and must be unique.
Count SQLTag
Inductive Automation

OEE Downtime

355

The required SQLTag is the source of the raw production counts. This typically comes from a PLC, but
can come from other sources such as barcode readers, database queries or derived by another means.
The data type (format) of the SQLTag containing the raw production count must be a number.
Max Raw Count
This is the maximum raw count value before it is reset to zero. See note below.
Production Units
This can be anything you want that represents the units. Examples are: gallons, cases, bottles, pounds,
liters, etc.
Note: The term raw count is used because it is a relative production count. It just starts at zero and counts up
to a rollover value, typically 32767, where it becomes zero again. The OEE Downtime and Scheduling module
calculates the actual production count from raw count. This eliminates having to reset the value in the PLC,
or other device, at the beginning of a production run. As a result, the programming that is required in the PLC,
or other device is simplified. It also eliminates problems typically associated with reset handshaking and
production runs that exceed the limits of PLC counters. For an OEE tracking system to be accurate, it must
withstand communication errors power outages, etc. By using raw counts that rollover and let the OEE
Downtime and Scheduling module handle the actual production count, the system is robust. Besides, that is
just less PLC programming that has to be done and tested.
3.3.5.2

Editing a Product Infeed

To edit an existing product infeed entry, right-click on the desired entry in the product infeed table of a
product line or cell and select the Edit menu item. A dialog box similar to the add dialog box will appear,
allowing editing of the entry.
3.3.5.3

Deleting a Product Infeed

To remove an existing product infeed entry, right-click on the desired entry in the product infeed table of a
production line or cell and select the Delete menu item. A window will appear confirming that you want to
remove the product infeed entry.
3.3.5.4

Import / Export

To import product infeed entries, right-click anywhere on the product infeed table and select the Import
menu item. A dialog box will appear to allow selection of a comma separated values (csv) formatted file.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing a single product infeed entry.

To export product infeed entries, right-click anywhere on the table containing product infeeds and select
the Export menu item. A dialog box will appear to allow selection of an existing file or the typing in of a
name of the new file to save the product infeed entries to. If a file extension is not entered, then the default
.csv will be used.

Inductive Automation

OEE Downtime

3.3.6

356

Product Outfeed

Before OEE calculations can be performed, production count information is required. At a minimum, the
outfeed production count for a production line is needed. Additional production count information can be
configured that will result in more OEE calculations. For example, if the infeed production count is
configured for a production, then product accumulation and waste is calculated. See Production Count
Tracking section for more information.
For each outfeed, the OEE module will start calculating production rates, OEE, etc. values. These values
can be accessed through the Production OPC Server. See the section on Production OPC Values for
more information.
3.3.6.1

Adding a Product Outfeed

For each outfeed, the OEE module will start calculating the production rate per minute, or production rate
per hour values. These values can be accessed through the Production OPC Server. See the section on
Production OPC Values for more information. To add a product outfeed entry, right-click anywhere on the
product outfeed table of a production line or cell and select the New menu item. A dialog box will appear
to allow entry of the new information, as shown below.

Product Outfeed Settings

Name
The required outfeed name is used to reference one outfeed from another and must be unique.
Count SQLTag
The required SQLTag is the source of the raw production counts. This typically comes from a PLC, but
can come from other sources such as barcode readers, database queries or derived by another means.
The data type (format) of the SQLTag containing the raw production count must be a number.
Max Raw Count
This is the maximum raw count value before it is reset to zero. See note below.
Inductive Automation

OEE Downtime

357

Default Standard Rate

The OEE calculation requires the designed rate that the production line can produce. Typically, machines
and processes only run at these rates theoretically. This setting is the default value for the standard rate
but can be overridden by product and line in the user screens.
Default Package Count
This is the default number of infeed units which end up in an outfeed unit. If package count does apply,
then enter 1.0. For example, there may be 10 bottle (infeed) in a case (outfeed) or 10 gallons (infeed) in a
bucket (outfeed).
When calculating waste and production count information, the package size is very important. It can
change based on the product being run and the default value, and can be overridden by the product in the
user screens.
Standard Rate Period
This is the time period to use for the default standard rate If the default standard rate is in units per hour,
select Hour otherwise select Minute.
Production Units
This can be anything you want that represents the units. Examples are: gallons, cases, bottles, pounds,
liters, etc.
Waste Transit Time (Seconds)
The waste transit time specifies the amount of time it takes for one unit to travel from the infeed to the
outfeed if the production line is running at standard rate. It is used to calculate the waste count.
Note: The term raw count is used because it is a relative production count. It just starts at zero and counts up
to a rollover value, typically 32767, where it become zero again. The OEE Downtime and Scheduling module
calculates the actual production count from raw count. This eliminates having to reset the value in the PLC,
or other device, at the beginning of a production run. As a result, the programming that is required in the PLC,
or other device is simplified. It also eliminates problems typically associated with reset handshaking and
production runs that exceed the limits of PLC counters. For an OEE tracking system to be accurate, it must
withstand communication errors power outages, etc. By using raw counts that rollover and let the OEE
Downtime and Scheduling module handle the actual production count, the system is robust. Besides, that is
just less PLC programming that has to be done and tested.
3.3.6.2

Editing a Product Outfeed

To edit an existing product outfeed entry, right-click on the desired entry in the product outfeed table of a
product line or cell and select the Edit menu item. A dialog box similar to the add dialog box will appear
allowing editing of the entry.
3.3.6.3

Deleting a Product Outfeed

To remove an existing product outfeed entry, right-click on the desired entry in the product outfeed table of
a production line or cell and select the Delete menu item. A window will appear confirming that you want
to remove the product outfeed entry.
3.3.6.4

Import / Export

To import product outfeed entries, right-click anywhere on the product outfeed table and select the Import
menu item. A dialog box will appear to allow selection of a comma separated values (csv) formatted file.
Inductive Automation

OEE Downtime

358

The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing a single product infeed entry.

To export product outfeed entries, right-click anywhere on the table containing product outfeeds and
select the Export menu item. A dialog box will appear to allow selection of an existing file or the typing in
of a name of the new file to save the product outfeed entries to. If a file extension is not entered, then the
default .csv will be used.

3.3.7

Product Waste

Before OEE Quality calculations can be performed, waste count information is required. Because of the
varied approaches of determining waste on a production line or process, the OEE Downtime Module
allows different methods of collecting waste information.
1. Use the Run Waste Count OPC value for the line. With this method, the OEE Downtime Module will
simply use the current value of the Run Waste Count OPC value when calculating the OEE Quality
values. This provides for custom waste tracking or calculations if the methods built in to the OEE
Downtime Module don't fit your requirements. If OEE Quality is not being used, then this method should
be used and setting the Run Waste Count OPC value to zero.
2. Automatically calculate the waste count using the built-in algorithm based on the infeed count, outfeed
count and transit time defined in the Product Outfeed. This method is an approximation and is less
accurate especially in cases when product accumulation sections are used on the line.
3. Use configured Product Waste counters. This OEE Downtime Module will track waste count using the
same method used for infeed and outfeed counts. The waste counts will be totalized and used in the
OEE Quality calculations.
Waste Calculation Methods
There are several ways to calculate the amount of waste coming from a production line:
None
No waste calculation methods will be used to determine waste counts.
Run Waste Count Tag
Waste will be calculated based on what is entered in the Run Waste Count tag. This may be a unique
formula used to calculate waste or a manual entry of the waste count.
Started vs. Finished
When this method is used, outfeed will be compared to infeed to determine how many units were lost
to waste. If 1000 units enter the production line, and 900 finished products exit the production line, then
it is assumed that 100 units were lost to waste. A Waste Transit time other than 0 must be entered for
the primary outfeed. The Waste Transit time should be the normal amount of time a production unit
takes to travel from infeed (started) to outfeed (finished).
Product Waste Entries
Inductive Automation

OEE Downtime

359

In order to calculate waste by this method, one or more entries must be in the Product Waste table.
The waste from each entry is added together to equal the total amount of waste. For example, there
may be two cells on the line that inspect and discard faulty products. If the first cell discarded 10 units,
and the second cell discarded 5 units, the total waste count would be 15 units.
Sum Product Waste From Each Cell
This method will sum up each of the cell's waste values. Product Waste Entries will be ignored.
3.3.7.1

Adding a Product Waste Counter

To add a product waste entry, right-click anywhere on the product waste table of a production line or cell
and select the New menu item. A dialog box will appear to allow entry of a name, count SQLTag and
maximum as shown below.

Product Waste Settings

Name
The required product waste name is used to reference one waste entry from another and must be unique.
Count SQLTag
The required SQLTag is the source of the raw waste counts. This typically comes from a PLC, but can
come from other sources such as barcode readers, database queries or derived by another means. The
data type (format) of the SQLTag containing the raw waste count must be a number.
Max Raw Count
This is the maximum raw count value before it is reset to zero. See note below.
Note: The term raw count is used because it is a relative waste count. It just starts at zero and counts up to a
rollover value, typically 32767, where it become zero again. The OEE Downtime and Scheduling module
calculates the actual waste count from raw count. This eliminates having to reset the value in the PLC, or
other device, at the beginning of a production run. As a result, the programming that is required in the PLC, or
other device is simplified. It also eliminates problems typically associated with reset handshaking and
production runs that exceed the limits of PLC counters. For an OEE tracking system to be accurate, it must
withstand communication errors power outages, etc. By using raw counts that rollover and let the OEE
Downtime and Scheduling module handle the actual waste count, the system is robust. Besides, that is just
less PLC programming that has to be done and tested.
3.3.7.2

Editing a Product Waste Counter

To edit an existing product waste entry, right-click on the desired entry in the product waste table of a
product line or cell and select the Edit menu item. A dialog box similar to the add dialog box will appear
allowing editing of the entry.
Inductive Automation

OEE Downtime

3.3.7.3

360

Deleting a Product Waste Counter

To remove an existing product waste entry, right-click on the desired entry in the product waste table of a
production line or cell and select the Delete menu item. A window will appear confirming that you want to
remove the product waste entry.
3.3.7.4

Import / Export

To import product waste entries, right-click anywhere on the product waste table and select the Import
menu item. A dialog box will appear to allow selection of a comma separated values (csv) formatted file.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing a single product waste entry.

To export product waste entries, right-click anywhere on the table containing product waste entries and
select the Export menu item. A dialog box will appear to allow selection of an existing file or the typing in
of a name of the new file to save the product waste entries to. If a file extension is not entered, then the
default .csv will be used.

Inductive Automation

OEE Downtime

3.4

361

Component Reference

This section will describe the components that are available with the OEE Downtime and Scheduling
module.
Please note that only the properties, methods and events that are specific to the OEE Downtime and
scheduling module components are described here. For description and usage of other properties see
the Ignition reference manual.

3.4.1

Production Components

When the Production Module, which is part of the OEE Downtime and Scheduling Module, is opened, a
new component tab will appear. On it are a number of components that provide functionality specific to
the production model, product codes, analysis, etc.

Production Com ponents

3.4.1.1

Production Line Selector

Description
A component that provides users to select a production line from a drop-down list. Production lines are
defined in the production model within the designer.

Line Drop-Dow n List

Properties
This component has standard Ignition properties with the addition of the following properties:
Selected Line Path

The currently selected line path. This is the full path name of the line starting
with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripti selectedLinePath
ng name
Data
String
Type

Inductive Automation

OEE Downtime
Selected Line Name

362

The currently selected line name. This is just the line name excluding the rest
of the line path.
For example: "Line 1"
Scripting name
Data Type

selectedLineName
String

The currently selected line ID. This is internal system ID for this line. Useful
for user defined queries into the database.
For example: "event.source.parent.getComponent('Production Line
Selector').selectedLineID" will return the selected line id.
Scripting name
selectedLineID
Data Type
String
Line Filter

A comma separated list of lines to display.

Example: When set to "Line A, Line B" then only Line A and Line B will be
displayed.
Scripting name
Data Type

Production Model Item Filter

lineFilter
String

The production model path to filter upon.

Example: When set to "OEEDemo\Your Enterprise\Site 1\Packaging"
then all lines under Packaging will be displayed.
Scripting name
Data Type

itemPath
String

Events
This component has standard Ignition events.
Methods
(none)
3.4.1.2

Production Cell Selector

Description
A component that provides users to select a production cell from a drop-down list. Production cells are
defined in the production model within the designer.

Inductive Automation

OEE Downtime

363

Cell Drop-Dow n List

Properties
This component has standard Ignition properties with the addition of the following properties:
Line Path

The line path of the production line that this component is associated with.
This is the full path name of the line starting with the project name. Only the
cells for this line path will be shown in this component.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Selected Cell Path

The currently selected cell path. This is the full path name of the cell starting
with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1\Filler"
Scripting name
selectedCellPath
Data Type
String

Selected Cell Name

The currently selected cell name. This is just the cell name excluding the rest
of the cell path.
For example: "Filler"
Scripting name
Data Type

selectedCellName
String

Events
This component has standard Ignition events.
Methods
(none)
3.4.1.3

Product Code Selector

Description
A component that provides users to select a product code from a drop-down list of available product code
Inductive Automation

OEE Downtime

364

for a production line. Product code information is stored in the "ProductCode", "ProductCodeLine",
"ProductCodeLineProperty" database tables. The Product Code Table, Product Code Line Table and
Product Code Properties Table are typically used to manage the information in these database tables
eliminating the need for SQL statements and scripts to do so.

Product Code Drop-Dow n List

Properties
This component has standard Ignition properties with the addition of the following properties:
Line Path

The line path of the production line that this component is associated
with. This is the full path name of the line starting with the project
name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line
1"
Scripting name
linePath
Data Type
String

Selected Product Code

The currently selected product code ID.

Scripting name
Data Type

selectedStringValue
String

Events
This component has standard Ignition events.
Methods
(none)
3.4.1.4

Product Code Table

Description
A component that displays all the available product codes in a table and allows the product code to be
disabled. All product codes are automatically displayed from the "ProductCode" database table without
the need for custom SQL statements or script.

Inductive Automation

OEE Downtime

365

Product Code Table

When a product code is disabled then it cannot be selected during work order creation or product code
selection.
This component usually works in conjunction with the Product Code Line Table and Product Code
Properties Table components. Refer to the OEEDemo project for a complete example.

Inductive Automation

OEE Downtime

366

Properties
This component has standard Ignition properties with the addition of the following properties:
Selected Product Code

The currently selected product code from the table.

Scripting name
Data Type

Selected Product Code ID

selectedProductCode
String

The currently selected product code ID. This is the ID for the
"ProductCode" database table.
Scripting name
selectedProductCodeID
Data Type
String

Hide Disabled Product Codes If set to True then disabled Product Codes will be hidden from the table.

Scripting name
Data Type
Product Code Filter

hideDisabled
Boolean

Filters the results in the table that begin with the given string. If left blank
all product codes are returned.
Scripting name
productCodeFilter
Data Type
String

Events
This component has standard Ignition events.
Methods
(none)
3.4.1.5

Product Code Line Table

Description
This component displays all the available lines and allows the linked product code to be enabled to be run
on production lines. All product code lines are automatically displayed from the "ProductCodeLine"
database table without the need for custom SQL statements or script.

Inductive Automation

OEE Downtime

367

Product Code Line Table

When a line is enabled for a product code, it will show up it the list of available products when scheduling,
etc. for that line.
This component usually works in conjunction with the Product Code Table and Product Code Properties
Table components. Refer to the OEEDemo project for a complete example.
Properties
This component has standard Ignition properties with the addition of the following properties:
Product Code ID

The currently selected product code ID. This is the ID for the
"ProductCode" database table. Normally this is bound to the Product
Code Table "Selected Product Code ID".
Scripting name
productCodeID
Data Type
String

Selected ProductCodeLine ID

Value of the currently selected product code internal ID. This is the ID for
the "ProductCodeLine" database table.
Scripting name
selectedProductCodeLineID
Data Type
String

Selected Line Name

Value of the currently selected line name.

Scripting name
Data Type

selectedLineName
String

Events
This component has standard Ignition events.
Methods
(none)
3.4.1.6

Product Code Properties Table

Description
This component displays, and allows editing of, property values for specific product code and production
line combination. This is where standard rates and scheduling rates are defined by product code and
production line.
The properties that appear depend on the production model configuration done in the designer. There will
be properties for the production line at the top followed by properties for each production cell.

Inductive Automation

OEE Downtime

368

Product Code Properties Table

The Value column will indicate the property setting value and allow editing the of value for the specified
line. The default value is for reference and is not editable. The values are saved in the
"ProductCodeLineProperty" database table.
This component usually works in conjunction with the Product Code Table and Product Code Line Table
components. Refer to the OEEDemo project for a complete example.
Properties
This component has standard Ignition properties with the addition of the following properties:
Product Code Line ID

The product line ID. This is the ID for the "ProductCodeLine" database
table. Normally this is bound to the Product Code Line Table "Selected
Product Code Line ID".
Scripting name
productCodeLineID
Data Type
String

Events
This component has standard Ignition events.
Methods
(none)
3.4.1.7

Production Comments Panel

Description
A component that allows comments/notes to be entered for the current production run. This component is
similar to the Ignition Comments Panel component, but eliminates the need for SQL statements or
scripting. It ties comments to the production run that the production line is currently running.

Inductive Automation

OEE Downtime

369

Production Com m ents Panel

To add a comment select the "+ Add Note" link. A new window panel will appear and allow you to enter
text.
If you select "Sticky?" that will force the note(s) to appear at the top of the list. The color of the background
of a sticky note can be controlled with the "Sticky Note Color" property.
After a sticky note is entered, it can be "un-stuck" by selecting the "[unstick]".
If note deletion is allowed, the link "[delete]" can be selected to delete the note.
Properties
This component has standard Ignition properties with the addition of the following properties:
Line Path

The line path of the production line that this component is associated with.
This is the full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Run Reference ID

The run ID of the production run to display comments for. If its value is set
to -1, then comments for the current production run will be displayed.
Note: Setting of this property is only required when viewing comments for
past production runs.
Scripting name
refID
Data Type
int

Delete Mode

Determines how deleting of comments will be handled.

Scripting name
Data Type
Values

Inductive Automation

deleteMode
int
No Deletes
Owner Deletes
Any Deletes

OEE Downtime
Entered By

370

Allows a custom value to be used to indicate who entered the comment. If

left blank it will use the currently logged in user name.
Scripting name
enteredByName
Data Type
String

Inductive Automation

OEE Downtime

371

Events
This component has standard Ignition events.
Methods
newNote()
New note.
parameters
returns
3.4.1.8

(none)
nothing

Product Code Controller

Description
An invisible component that provides adding product codes. The term invisible component means that the
control appears during design time, but is not visible during runtime. Product codes are stored in the
"ProductCode" database table and this control handles all SQL statements, duplicate checking, etc.
Alternatively, product codes can added directly into the "ProductCode" database table directly, bypassing
the OEE Downtime and Scheduling Module. This method supports integration to ERP or other software
systems.
Product codes can also be added via scripting.
Properties
This component has standard Ignition properties.
Events
This component has standard Ignition events.
Methods
addProductCode(productCode, description)
Add new production code and description to database.
parameters

productCode

The product code to add to the

database
Data Type
String

description

A descriptive label for the product

code
Data Type
String

returns

message
Inductive Automation

contains a description of any error

encountered, usually that the

OEE Downtime

372

product code already exists.

Otherwise it will be empty.
Data Type
String
Example Code
The following script can be entered in a button's actionPerformed event. It will add the product code and
description to the database. The return message will indicate if the there are any issues adding the
product code, such as if the product code already exists.
message = event.source.parent.getComponent('Product Code Controller')
.addProductCode(event.source.parent.getComponent('ProductCode').text,
event.source.parent.getComponent('ProductCodeDescription').text)
if message == '':
system.nav.closeParentWindow(event)
else
system.gui.errorBox(message)
3.4.1.9

Analysis Controller

Description
An invisible component that makes analysis data available for reports and other components. The term
invisible component means that the control appears during design time, but is not visible during runtime.
In cases where the Production Analysis Selector offers too many options to the use, this component can
be used. It has all of the same functionality as the Production Analysis Selector but without the user
interface. This means property bindings or script must be used to make the filter, compare by and data
point selections. It also is used for providing data to canned reports and optionally allowing the user to
make limited filter options.
This component also contains methods for deleting and restoring a run.
Properties
This component has standard Ignition properties with the addition of the following properties:
Automatic
Update

When true, when any property that changes the results will change, the
results will automatically be updated.
Scripting name
automaticUpdate
Data Type
Boolean

Table Data

This property holds data in a format that is optimized for binding to a table
component.
Scripting name
tableData
Data Type
Dataset

Inductive Automation

OEE Downtime
Data Format

373

This property specifies the type of data to return from the server.
Options:
Table - Only data optimized for tables will be included in the results.
Chart - Only data optimized for charts will be included in the results.
Both - Table and chart data will be included in the results.
Scripting name
Data Type
values

dataFormat
AnalysisDataFormat
Table
Chart
Both

Chart Data

This property holds data in a format that is optimized for binding to pie and
bar chart component such as the Production Bar Chart and Production Pie
Chart.
Scripting name
chartData
Data Type
Dataset

Line Chart
Data

This property holds data in a format that is optimized for binding to a line
chart component.
Scripting name
lineChartData
Data Type
Dataset

Drill Down
Options

This property holds the drill down options appropriate for the current filter and
compare by settings.
Scripting name
drillDownOptions
Data Type
Dataset

Previous Drill
Down
Enabled

This property indicates if there are entries in the drill down cache maintained
by this component.
Scripting name
Data Type

previousDrillDownEnabled
Boolean

Provider
Name

This property holds the current provider of analysis data. See Analysis
Providers for available options.
Scripting name
providerName
Data Type
String

Filter

This property holds the current filter item selections to filter the analysis
results by. If more than one item exists, they are separated by commas.
See Analysis Providers for available filters for each provider type.
Scripting name
filter
Data Type
String

Inductive Automation

OEE Downtime

374

Compare By

This property holds the current compare by item selections to group the
analysis results by. If more than one item exists, they are separated by
commas. See Analysis Providers for available compare by values for each
provider type.
Scripting name
compareBy
Data Type
String

Data Points

This property holds the currently selected data points to include in the
results. If more than one item exists, they are separated by commas. See
Analysis Providers for available data points for each provider type.
Scripting name
dataPoints
Data Type
String

Start Date

This property is the starting date for retrieving analysis data and determining
available filter and compare by options.
Scripting name
startDate
Data Type
Date

End Date

This property is the ending date for retrieving analysis data and determining
available filter and compare by options.
Scripting name
endDate
Data Type
Date

Dynamic
Properties

Depending on the setting of the Provider Name property, the dynamic

properties will change. A dynamic property to be created for each filter
category that can be bound to by other components. These dynamic
properties can also be set through script. See Analysis Providers for
available filters for each provider type.
For example:
If the Provider Name property is set to "Downtime", then Shift will be
created for one of the dynamic properties. The Shift dynamic property
can be bound to a Dropdown List Component populated with 1, 2 and 3.
Changing the selection of the drop-down list will change the analysis
results to be filtered by the select shift.

Events
This component has standard Ignition events plus the following events:
progressStart
Event Properties
event.source()
beforeUpdate
Event Properties
afterUpdate
Event Properties
progressEnd
Event Properties

Is fired when this component begins to process property changes. Usefull

for displaying an "in progress" message during processing.
The component source of the event (this component).
Data Type
Component
(none)

Is fired when this component completes property changes. Usefull for

displaying an "in progress" message during processing.
Inductive Automation

OEE Downtime

Inductive Automation

375

OEE Downtime

376

Methods
drillDown(drillDownName, item)
Sets all the analysis selections to new state dictated by the drill down definition.
parameters

drillDownName

A drill down definition name. This is typically supplied by the drill

down event of one of the display components
Data Type
String

item

A drill down category. This is typically supplied by the drill down ev

of one of the display components
Data Type
Object

returns
nothing
---------------------------------------------------------------------------------------------------------------------------------------------------------------

prevDrillDown()
Sets all the analysis selections to the previous state before the last drill down.
parameters
(none)
returns
nothing
---------------------------------------------------------------------------------------------------------------------------------------------------------------

update()
Causes the results to be updated.
parameters
(none)
returns
nothing
---------------------------------------------------------------------------------------------------------------------------------------------------------------

addDatasetColumn()
This method is used for reporting. Because the Ignition Report module does not support master slave
table relationships, this method is used to add new columns containing a Dataset with child rows. For
each row in the analysis controller results, a child Dataset will be created and placed into the new
column named specified by the columnName parameter. The rows in the child Dataset are determined
from the Dataset specified in the dataset parameter and match the column value specified by the
keyColumns parameter.
parameters

dataset

Dataset containing child rows.

Data Type
Dataset

columnName

Name of column to add that will contain the child dataset.

Data Type
String

keyColumns

Name of columns to break the child row up by. Multiple key column
can be specified by separating then with a comma.
Data Type
String

returns
nothing
---------------------------------------------------------------------------------------------------------------------------------------------------------------

deleteRun(runUUID)
Marks the run as deleted for analysis purposes. This run and associated data will not appear in any
analysis datasets.
Inductive Automation

OEE Downtime

377

Must use "Run, Run Identifier" as the "Compare By" for this method to work.
parameters

run The unique

Run
U
Identifier
U
for
the
I run to
delete.
D
Data
Type
String
nothing

returns

---------------------------------------------------------------------------------------------------------------------------------------------------------------

restoreRun(runUUID)
Restores a previously deleted run.
Must use "Run, Run Identifier" as the "Compare By" for this method to work.
Use "Deleted Runs=Show" as the filter to show runs that have been deleted.
parameters

run The unique

Run
U
Identifier
U
for
the
I run to
delete.
D
Data
Type
String
returns

Inductive Automation

nothing

OEE Downtime

378

Example Code
This script would be entered into the "drillDown" event of a Production Bar Chart.
event.source.parent.getComponent('Production Analysis Selector')
.drillDown(event.getDrillDownName(), event.getCategory())

This script would be entered into the "back" event of a Production Bar Chart.
event.source.parent.getComponent('Production Analysis Selector')
.prevDrillDown()
3.4.1.10 Production Analysis Selector

Description
A component that allows ad hoc selection of analysis data. As the user makes selections, this component
will query the server for results. These results can be accessed through the Table Data, Chart Data and
Line Chart Data properties to populate tables and charts.

Production Analysis Selector

A filter can be added by selecting the

link to the right of Filter By. A window panel will open and filter

categories will be displayed. Click the link by the filter category and specific filter items will be displayed.
When selected they will be added to the filters as shown below. To minimize the number of filter options,
only the options for the selected date range defined by the Start Date and End Date properties will be
shown.

Inductive Automation

OEE Downtime

379

Filter By List

Compare By and Data Points work similarly to Filter By except there are no categories for these
selections, just items.

Com pare By and Data Points List

Selections can be removed by selecting the

link to the left of the selection.

Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

OEE Downtime

380

Table Data

This property holds data in a format that is optimized for binding to

a table component.
Scripting name
tableData
Data Type
Dataset

Chart Data

This property holds data in a format that is optimized for binding to

pie and bar chart components such as the Production Bar Chart
and Production Pie Chart.
Scripting name
chartData
Data Type
Dataset

Line Chart Data

This property holds data in a format that is optimized for binding to

a line chart component.
Scripting name
lineChartData
Data Type
Dataset

Drill Down Options

This property holds the drill down options appropriate for the current
filter and compare by settings.
Scripting name
drillDownOptions
Data Type
Dataset

Previous Drill Down Enabled

This property indicates if there are entries in the drill down cache
maintained by this component.
Scripting name
previousDrillDownEnabled
Data Type
Boolean

Provider

This property holds the current provider of analysis data. See

Analysis Providers for available options.
Scripting name
provider
Data Type
String

Start Date

This property is the starting date for retrieving analysis data and
determining available filter and compare by options.
Scripting name
startDate
Data Type
Date

End Date

This property is the ending date for retrieving analysis data and
determining available filter and compare by options.
Scripting name
endDate
Data Type
Date

Filter Selection Summary

This property holds the current filter item selections to filter the
analysis results by. If more than one item exists, they are separated
by commas.
Scripting name
filterSummary
Data Type
String

Inductive Automation

OEE Downtime

381

Comparisons Selection Summary This property holds the current compare by item selections to group

the analysis results by. If more than one item exists, they are
separated by commas.
Scripting name
comparisonsSummary
Data Type
String
Data Points Selection
Summary

This property holds the currently selected data points to include in

the results. If more than one item exists, they are separated by
commas.
Scripting name
dataPointsSummary
Data Type
String

Data Format

This property specifies the type of data to return from the server.
Options:
Table - Only data optimized for tables will be included in the
results.
Chart - Only data optimized for charts will be included in the
results.
Both - Table and chart data will be included in the results.
Scripting name
Data Type
values

dataFormat
AnalysisDataFormat
Table
Chart
Both

Events
This component has standard Ignition events.
Methods
drillDown(drillDownName, item)
Sets all the analysis selections to new state dictated by the drill down definition.
parameters

drillDownName

A drill down definition name. This is typically

supplied by the drill down event of one of
the display components
Data Type

item

A drill down category. This is typically supplied

by the drill down event of one of the
display components
Data Type

returns

nothing

prevDrillDown()
parameters
returns

Inductive Automation

(none)
nothing

String

Object

OEE Downtime

382

Example Code
This script would be entered into the "drillDown" event of a Production Bar Chart.
event.source.parent.getComponent('Production Analysis Selector')
.drillDown(event.getDrillDownName(), event.getCategory())

This script would be entered into the "back" event of a Production Bar Chart.
event.source.parent.getComponent('Production Analysis Selector')
.prevDrillDown()
3.4.1.11 Production Stored Analysis Selector

Description
A component that allows creating, recalling and saving analysis data selections in the Production Analysis
Selector. This component will automatically use the available Production Analysis Selector in the
container.

Stored Analysis Selector

By clicking on the
will popup.

link, a menu with the option to create new, save, delete and rename analysis

To add a new stored analysis, click on New menu item, enter a name, select a type and click OK. This
will create an empty analysis. Now the user can make filter, compare by and data point selections that will
be saved and can easily be selected at a later time.

New Stored Analysis

To rename a new stored analysis, click on Rename menu item, enter a new name and click OK.

Renam e Stored Analysis

To delete a stored analysis, click on Delete menu item, and select Yes to the confirmation message.

Inductive Automation

OEE Downtime

383

If changes to an analysis setting have been made and the user selects a different stored analysis, they
will be prompted to save the changes. Alternatively, the changes can be saved by clicking on the Save
menu item.
Properties
This component has standard Ignition properties.
Events
This component has standard Ignition events.
Methods
(none)
3.4.1.12 Production Bar Chart

Description
A component that displays a pie chart with drill down capabilities. This extends from the Bar Chart
Component

that comes with Ignition.

When the user clicks on a bar of the bar chart, the drill down menu will appear. When an item in the drill
down menu is clicked on, the drillDown event is fired. Script in the drillDown event is responsible for
updating the Data property to change the results shown in the bar chart.The drill down menu information
is set through the Drill Down Options property. The Drill Down Options can populated from the Analysis
Controller, Analysis Selector, SQL Query, scripting or it can be manually defined in the designer.

Production Bar Chart

Inductive Automation

OEE Downtime

384

Properties
This component has the same properties as the Ignition Bar Chart Component with the addition of the
following properties:
Drill Down Options

This is a Dataset that must have at least one column. The first column
must be a data type of string. The values in the first column will be
shown in the drill down options menu.
Typically, this property binds to the drill down options property in a
Production Analysis Selector component.
Scripting name
drillDownOptions
Data Type
Dataset

Previous Drill Down Enabled

This controls the visibility of the "Back" drill down menu option. If it is
set to true, "Back" will appear at the top of the drill down options.
Scripting name
previousDrillDownEnabled
Data Type
Boolean

Events
This component has the same events as the Ignition Pie Chart Component with the addition of the
following events:
drillDown
Is fired when drill down menu item is selected. Excludes the "Back"
menu item.
Event Properties
event.getDrillDownName()
Returns the text of selected drill down option menu item.
Data Type String
event.getCategory()

back
Event Properties

Returns the bar chart category that was clicked on to display the drill
down menu. This is typically the first column of the Data property
dataset.
Data Type Object

(none)

Methods
(none)
3.4.1.13 Production Pie Chart

Description
A component that displays a pie chart with drill down capabilities. This extends from the Pie Chart
Component

that comes with Ignition.

Inductive Automation

OEE Downtime

385

When the user clicks on a segment of the pie chart, the drill down menu will appear. When an item in the
drill down menu is clicked on, the drillDown event is fired. Script in the drillDown event is responsible for
updating the Data property to change the results shown in the pie chart. The drill down menu information
is set through the Drill Down Options property. The Drill Down Options can populated from the Analysis
Controller, Analysis Selector, SQL Query, scripting, or it can be manually defined in the designer.

Production Pie Chart

Properties
This component has the same properties as the Ignition Pie Chart Component with the addition of the
following properties:
Drill Down
Options

This is a Dataset that must have at least one column. The first column must be a data
type of string. The values in the first column will be shown in the drill down options
menu.
Typically, this property binds to the drill down options property in a Production Analysis
Selector component.
Scripting name
drillDownOptions
Data Type
Dataset

Previous Drill
Down
Enabled

This controls the visibility of the "Back" drill down menu option. If it is set to true,
"Back" will appear at the top of the drill down options.
Scripting name
Data Type

Inductive Automation

previousDrillDownEnabled
Boolean

OEE Downtime

386

Events
This component has the same events as the Ignition Pie Chart Component with the addition of the
following events:
drillDown

Is fired when drill down menu item is selected. Excludes the "Back" menu
item.

Event Properties
event.get
DrillDownName()
event.
getCategory()
back
Event Properties

Returns the text of selected drill down option menu item.

Data Type
String
Returns the pie chart category that was clicked on to display the drill down
menu. This is typically the first column of the Data property dataset.
Data Type Object
(none)

Methods
(none)
3.4.1.14 Analysis Table

Description
A component that displays tabular data with drill down capabilities. This extends from the Table
Component

that comes with Ignition.

When the user clicks on a row in the table, the drill down menu will appear. When an item in the drill down
menu is clicked on, the drillDown event is fired. Script in the drillDown event is responsible for updating
the Data property to change the results shown in the table.The drill down menu information is set through
the Drill Down Options property. The Drill Down Options can populated from the Analysis Controller,
Analysis Selector, SQL Query, scripting, or it can be manually defined in the designer.

Analysis Table

Properties
This component has the same properties as the Ignition Table Component with the addition of the
following properties:
Inductive Automation

OEE Downtime

387

Allow Export

This controls the visibility of the "Export" menu option. If it is set to true, "Export" will
appear at the top of the drill down options allowing the user to export the data
appearing the table.
Scripting name
allowExport
Data Type
Boolean

Drill Down
Options

This is a Dataset that must have at least one column. The first column must be a
data type of string. The values in the first column will be shown in the drill down
options menu.
Typically, this property binds to the drill down options property in a Production
Analysis Selector component.
Scripting name
drillDownOptions
Data Type
Dataset

Previous Drill
Down
Enabled

This controls the visibility of the "Back" drill down menu option. If it is set to true,
"Back" will appear at the top of the drill down options.
Scripting name
Data Type

previousDrillDownEnabled
Boolean

Events
This control has the same events as the Ignition Table Component with the addition of the following
events:
drillDown

Is fired when drill down menu item is selected. Excludes the "Back" menu
item.

Event Properties
event.get
DrillDownName()

Returns the text of selected drill down option menu item.

Data Type String

event.get
Category()

Returns the value of first column for the selected row.

Data Type Object

back
Event Properties
(none)
Methods
(none)

Inductive Automation

OEE Downtime

3.4.2

388

Down Time Components

When the OEE Downtime Module, which is part of the OEE Downtime and Scheduling Module, is
opened, a new component tab will appear. On it are components that provide functionality specific to the
downtime and efficiency.

Dow n Tim e Com ponents

3.4.2.1

Down Time Table

Description
A component that displays automatic downtime events for an active production run and allows the
operator to select more specific downtime reasons for the event. It also allows the operator to split
downtime events. This accommodates downtime events that have multiple reasons. For example, if a
production line goes down because of a mechanical failure and when maintenance finishes the repair, it
is time for break. The operator can split the downtime event into two events. One for mechanical failure
and the other for break.

Splitting Dow n Tim e Reason

When the user clicks on the

icon in the right-hand column, the downtime event split panel appears.
The user can drag the time selector to the desired number of hours, minutes and seconds to split the
event at. After the user clicks the Split button, two entries in the Down Time Table will appear with the
exact same downtime reasons. The user can now select different downtime reasons for each entry.
When multiple downtime events occur for the same automatically detected downtime reason, they will be
combined into a single entry. The Count column will indicate the number of events and the Downtime
column will reflect the total downtime of the combined events. The Begin column will be the start of first
occurrence and the End column will be the end of the last occurrence. The user can click on the
icon
to separate the combined downtime events. This allows selecting different downtime reasons for each of
the downtime events.

Inductive Automation

OEE Downtime

389

Com m enting on Dow n Tim e Reason

When the use clicks on the

icon in the right-hand column, the downtime note panel appears. The user
can enter a note that will be associated with the downtime reason entry.
Editing Reasons
If the Editable property is set to true then the user may change the original reason generated to a more
appropriate reason. This is useful if, for instance, the machine can only generate a general fault code and
the user needs to enter in a specific fault after determining the cause.
The reasons that are available for selection are controlled by the configuration of the Downtime Reasons
and the Reason Selection Method property of the table.
The selectable reasons will be displayed in a pop-up panel tree view type control when the reason column
is clicked on the desired row. The reason tree view layout can be controlled by several properties (see
property description below) such as height, width, font and icons for selectable and non-selectable
reasons.
When editing a reason with the Reason Selection Method set to "Original Cell" the user will presented
with a tree view of the appropriate reasons for the original cell.

Inductive Automation

OEE Downtime

390

Editing a reason for Original Cell

When editing a reason with the Reason Selection Method set to "Any Cell" the user will presented with a
tree view of all cells and reasons. This allows the user to select a more appropriate cell and reason than
what was originally detected by the system.

Inductive Automation

OEE Downtime

391

Editing a reason for Any Cell

Original Reason and Cell retention

The original Reason, Cell and Cell Group (if applicable) are never lost when a user edits a reason. The
reason selector pop-up panel allows the user to reset to the original reason by selecting the "Reset"
button on the left of the panel. Also note that the analysis components have datapoints defined for
accessing the original reason.
Using the Table Customizer
A table customizer is available by right clicking the down time table in the designer and selecting
"Customizers" -> "Table Customizer". It is similar to the table customizer in a standard Ignition table but
the fields are pre-defined for the downtime table component.
Field Name

Description

Comments

begintime
When the event started
endtime
When the event ended
cellid
Original Cell ID
cellname
Original Cell Name
operatorcellid Operator selected Cell ID
operatorcellna
Operator Selected Cell Name
me
count

Event Count

Inductive Automation

Indicates the number of times this event has occured

consecutively

OEE Downtime
Field Name

Description

Comments
event duration formatted as a string in hours, minutes and
seconds.

totalseconds Down Time

reasoncode
description
ids
linestate
icon

Operator Selected Reason code

Reason Description
Internal ID's
Original Reason Code
Split and note icons

duration

Duration

hasnote
isshortstop

392

Indicates this row has a note

associated with it.
Indicates if this reason is short or
long.

The selected reason code description.

Used by the system.
Used by the system.
This is the elapsed seconds of this event. Since it is an
integer it can be used for background mapping, etc.

Will indicate 0 for long stops and 1 for short.

Dow ntim e table custom izer fields

Example using Translation List: In the "isshortstop" column configuration if you create a translation list
and set 0=Long and 1=Short and set the field to not be hidden you will see a column with either Long or
Short representing the type of downtime.

Dow ntim e table translation list

Example using Background Mapping: Select the duration column as the mapping column. Set the
translation for the seconds duration. Any value up to 29 seconds will have a white background, any value
from 30 to 44 seconds will have a yellow background and any value greater than or equal to 45 will have a
red background. Make sure to set the "Background Mode" property of the downtime table to "Mapped".
Inductive Automation

OEE Downtime

393

Properties
This component has standard Ignition events with the addition of the following properties:
Line Path

The line path of the production line that this component is associated with.
This is the full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Editable

This controls if users can change reason codes and split downtime events.
Scripting name
Data Type

Enable Notes

If true users can enter notes for each downtime entry in the table.
Scripting name
Data Type

Activity Timeout

Inductive Automation

editable
Boolean

enableNotes
Boolean

Indicates the number of seconds the table will "freeze" after any user activity,
such as scrolling, is performed on the table. Keeps the table from
immediately jumping to a new event until the timeout is reached.
Scripting name
activityTimeout
Data Type
Integer

OEE Downtime
Reason Selection
Method

Controls the ability to select reasons from other than the originating cell.
Scripting name
Data Type
Values

Run ID

394

cellSelectionType
Integer
Original Cell = 0
Any Cell = 1

Enter the run id when the downtime table is used to view previous runs. -1
indicates the current run. Normally is linked to the "Line Run Selector"
component to get a previous run id.
Note: When set to a value other than -1 the table will not be notified of new
events even if the runid is set to the current run id.
Scripting name
runid
Data Type
Integer

Reason Tree Expand sub When true sub reasons will be automatically expanded under the current
reasons reason when displaying the selection panel.

Scripting name
Data Type
Reason Tree Width

The width of the pop-up reason tree panel.

Scripting name
Data Type

Reason Tree Height

autoExpandSubReasons
Boolean

reasonTreeWidth
Integer

The height of the pop-up reason tree panel.

Scripting name
Data Type

reasonTreeHeight
Integer

Reason Tree Row Height Controls the height of each row in the reason tree view. The increased

space is useful when touchscreen mode is being used.

Scripting name
reasonTreeRowHeight
Data Type
Integer
Reason Tree Font

The font of the pop-up reason tree panel.

Scripting name
Data Type

reasonTreeFont
Integer

Reason Tree Scroll Bar The scroll bar width of the tree view. Useful when touchscreen mode is
Width
being used.

Scripting name
Data Type
Reason Tree Button
Size %

reasonTreeScrollBarWidth
Integer

The size of the buttons for the selection in the reason pop-up panel. Useful
when touchscreen mode is being used.
Scripting name
reasonTreeButtonSizePct
Data Type
Integer
Inductive Automation

OEE Downtime

395

Show the Reason

Reset Button

When set to false the reset button will not be available in the reason pop-up
panel.
Scripting name
showResetReasonButton
Data Type
Boolean

Selectable Reason
Icon Path

The icon to use for reasons that are selectable.

Scripting name
Data Type

selectableReasoniconpath
String

Folder Icon Path

The icon to use for items in the reason pop-up panel that are not selectable,
such as a cell.
Scripting name
foldericonpath
Data Type
String

Display Filter Type

For long runs that span shifts and/or days controls how many shifts will be
shown. If there are numerous downtime events settings other than "Current
Shift" can cause delay in the downtime table.
Scripting name
shiftDisplayType
Data Type
Integer
Values
Current Shift = 0
Previous and Current Shift = 1
Selected Shift Sequence = 2
Display Cutoff Duration (Minutes) = 3
All = 4

Selected Shift Sequence This is the shift sequence to start displaying downtime events if the "Number

of shifts to display" property is set to "Selected Shift Sequence". Shift

sequence numbers are the consecutive numbers of shifts of a run.
Scripting name
selectedShiftSequence
Data Type
Integer
Display Cutoff
Duration (Minutes)

Displays downtime events where the end time is within this number of
minutes from the current time. Applicable when Display Filter Type is set to
Display Cutoff Duration (Minutes).
Scripting name
dutoffMinutes
Data Type
Integer

Stop FilterType

Determines if the table will display long, short or both types of downtime
events.
Scripting name
selectedStopType
Data Type
Integer
Values
Both = 0
Short Stops = 1
Long Stops = 2

Rollup Interval
(Seconds)

Inductive Automation

Rolls up events that are consecutive, identical and occured within this many
seconds of each other. If set to less than 1 then no rollup will occur.
Scripting name
rollupInterval
Data Type
Integer

OEE Downtime

396

Events
This component has standard Ignition Table events and the following custom events:
reasonUpdated

Is fired after a user has updated an existing reason.

Methods
(none)

Inductive Automation

OEE Downtime
3.4.2.2

397

Performance Indicator

Description
A component that displays an indication of actual versus target values. It provides a visual indication to
users that is easy to comprehend with a quick glance. These values can be unit count, OEE or any
values residing in SQLTags.

Perform ance Indicator

This is similar to a bar chart except that it only has 2 series or bars. Also, the values reside in SQLTags
instead of having to setup values in an Ignition Dataset.
Properties
This component has the same properties as the Ignition Bar Chart Component with the addition of the
following properties:
Actual Value

The value that is represented by the actual indication bar.

Scripting name
actualValue
Data Type
Double

Actual Label

The text displayed to describe the actual value.

Scripting name
actualLabel
Data Type
String

Actual Series The color to use for the actual indication bar.
Color

Scripting name
Data Type
Chart Type

actualSeriesColor
Color

The type of chart to show.

Scripting name
chartType
Data Type
CategoryItemRenderer
Options:
3D Bars
3D Stacked Bars
Area
Bars
Layered
Stacked Bars
Indicator

Inductive Automation

OEE Downtime
Target Value

The value represented by the target indication bar.

Scripting name
Data Type

Target Label

398

targetValue
Double

The text displayed to describe the target value.

Scripting name
targetLabel
Data Type
String

Target Series The color to use for the target indication bar.
Color

Scripting name
Data Type
Editable

targetSeriesColor
Color

This controls if users can change reason codes and split downtime events.
Scripting name
editable
Data Type
Boolean

Events
This component has standard Ignition events
Methods
(none)
3.4.2.3

Line Run Selector

Description
A component that provides users to select a production run from a drop-down list of available runs on a
production line. The user can also select the current run by selecting <Current Run>.

Line Run Selector

Inductive Automation

OEE Downtime

399

Properties
This component has standard Ignition properties with the addition of the following properties:
Line Path

The line path of the production line that this component is associated with. This is
the full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Include Work Order When true displays the work order description in the drop down list (if available).
Des
cri
pti
on

Scripting name
Data Type

includeDescription
Boolean

Run ID

The currently selected production run ID. This is the ID for the "Run" database
table.
Scripting name
runID
Data Type
Integer

From Date

The beginning date to select runs from.

Scripting name
Data Type

To Date

The ending date to select runs from.

Scripting name
Data Type

Events
This component has standard Ignition events.
Methods
(none)

Inductive Automation

fromDate
Date

toDate
Date

OEE Downtime
3.4.2.4

400

Analysis Time Chart

Description
A component that displays the line and cell downtime events of a run in a visual time chart.

Analysis Tim e Chart

Properties
This component has standard Ignition properties with the addition of the following properties:
Series Data

Controls the data that is displayed in the analysis time chart and needs to be set to
the Schedule vs. Actual binding function.

See Scheduled vs. Actual in the Binding Function Reference section.

Scripting name
Data Type

data
Dataset

Inductive Automation

OEE Downtime
Duration Text

The text to show for the duration values in the info popup panel.
Scripting name
Data Type

Enable Info Popup

durationText
String

Show an info popup when you right click on the chart.

Scripting name
Data Type

Run Bar Color

401

enableInfoPopup
Boolean

Selects the color of the running section of the chart.

Scripting name
Data Type

runColor
Color

Run Legend Text

Set the text that will appear in the legend that represents the running
section of the chart.
Scripting name
runLegend
Data Type
String

Changeover Bar Color

Selects the color of the changeover section of the chart.

Scripting name
Data Type

changeoverColor
Color

Changeover Legend Text

Set the text that will appear in the legend that represents the
changeover section of the chart.
Scripting name
changeoverLegend
Data Type
String

Planned Downtime Bar Color

Selects the color of the planned downtime section of the chart.

Scripting name
Data Type

Planned Downtime Legend

Text

plannedDowntimeColor
Color

Set the text that will appear in the legend that represents the planned
downtime section of the chart.
Scripting name
plannedLegend
Data Type
String

Unplanned Downtime Bar Color Selects the color of the unplanned downtime section of the chart.

Scripting name
Data Type
Unplanned Downtime Legend
Text

Inductive Automation

unplannedDowntimeColor
Color

Set the text that will appear in the legend that represents the
unplanned downtime section of the chart.
Scripting name
unplannedLegend
Data Type
String

OEE Downtime

402

Unplanned Short Downtime Bar Selects the color of the unplanned short downtime section of the
Color
chart.

Scripting name
Data Type
Unplanned Short Downtime
Legend Text

unplannedShortDowntimeColor
Color

Set the text that will appear in the legend that represents the
unplanned short downtime section of the chart.
Scripting name
unplannedShortLegend
Data Type
String

Events
This component has standard Ignition events.
Methods
(none)

Inductive Automation

OEE Downtime

3.4.3

403

Schedule Components

When the Schedule Module, which is part of the OEE Downtime and Scheduling Module, a new
component tab will appear. On it are components that provide functionality specific to the work orders,
product codes and scheduling.

Schedule Com ponents

3.4.3.1

Work Order Selector

Description
A component that provides users to select a work order from a drop-down list of available work orders for
a production line. The available options include only work orders for product codes that are enabled to run
on the specified production line. All work orders are automatically displayed from the "WorkOrder"
database table without the need for custom SQL statements or script.

Work Order Selector

Inductive Automation

OEE Downtime

404

Properties
This component has standard Ignition properties with the addition of the following properties:
Line Path

The line path of the production line that this component is associated with. This is
the full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Selected Work
Order ID

The currently selected work order ID. This is the ID for the "WorkOrder" database
table.
Scripting name
selectedWorkOrderID
Data Type
Integer

Events
This component has standard Ignition events.
Methods
(none)
3.4.3.2

Work Order Table

Description
A component that displays all the available work orders in a table and calculates the units produced,
scheduled and remaining for each work order. All work orders are automatically displayed from the
"WorkOrder" database table within the date range of From Date and To Date properties without the need
for custom SQL statements or script.

Work Order Table

The users can click on a checkbox in the Closed column to close out a work order. After it is closed out,
it will no longer show in the Work Order Table component and it will not be available in any other work
order selector components. This feature is provided because some production runs may finish before the
target number of units are produced due to lack of raw materials, change in production priorities, etc.

Inductive Automation

OEE Downtime

405

The user can also click on a checkbox in the Hide column to hide the work order from being shown in the
Work Order Component. Implementations that integrate with other software systems, such as an ERP
system, may show work orders that are not relevant to this system. By hiding them, this list can be kept
clean of unrelated work orders.
Properties
This component has standard Ignition properties with the addition of the following properties:
To Date

This property is the starting date of when work orders were created.
Scripting name
startDate
Data Type
Date

From Date

This property is the ending date of when work orders were created.
Scripting name
endDate
Data Type
Date

Show Closed

If set to true, will show the closed work orders.

Scripting name
Data Type

Show Hidden

showClosed
Boolean

If set to true, will show the hidden work orders.

Scripting name
Data Type

showHidden
Boolean

Events
This component has standard Ignition events.
Methods
(none)
3.4.3.3

Work Order Controller

Description
An invisible component that provides adding, editing and deleting work orders. The term invisible
component means that the control appears during design time, but is not visible during runtime. Work
orders are stored in the "WorkOrder" database table and this control handles all SQL statements,
duplicate checking, etc.
Alternatively, work orders can added directly into the "WorkOrder" database table directly, bypassing the
OEE Downtime and Scheduling Module. This method supports integration to ERP or other software
systems.
Properties
This component has standard Ignition properties.

Inductive Automation

OEE Downtime

406

Events
This component has standard Ignition events.
Methods
addWorkOrderEntry(workOrder, productCode, quantity)
Add new work order.
parameters

workOrder

The work order number to add to the database.

Data Type
String

productCode

The product code to produce for work order

being added.
Data Type
String

quantity

The quantity of units to produce for work order

being added.
Data Type
Integer

returns

message

Contains a description of any error encountered,

otherwise it will be empty
Data Type
String
-----------------------------------------------------------------------------------------------------------------------------editWorkOrderEntry(workOrder, productCode, quantity, workOrderID)
Edit an existing work order.
parameters

workOrder

The work order number to add to the database.

Data Type
String

productCode

The product code to produce for work order

being added.
Data Type
String

quantity

The quantity of units to produce for work order

being added.
Data Type
Integer

workOrderID

The ID of the work order to modify. This is

the ID for the "WorkOrder" database table.
Data Type
Integer

message

Contains a description of any error encountered,

otherwise it will be empty.
Data Type
String

returns

Inductive Automation

OEE Downtime

407

deleteWorkOrderEntry(workOrderID)
Delete an existing work order.
parameters

workOrderID

The ID of the work order to modify. This is

the ID for the "WorkOrder" database table.
Data Type
Integer

message

Contains a description of any error encountered,

otherwise it will be empty.
Data Type
String

returns

Example Code
The following script can be entered in a button's actionPerformed event. It will add the work order to the
database. The return message will indicate if the there are any issues adding the product code, such as if
the work order already exists.
esp = event.source.parent # shorthand
workOrder = esp.getComponent('WorkOrderField').text
prodCode = esp.getComponent('ProductCodeDropdown').selectedStringValue
quantity = esp.getComponent('QuantityField').intValue
ctrl = esp.getComponent('Work Order Controller')
result = ctrl.addWorkOrderEntry(workOrder, prodCode, quantity)
if len(result) == 0:
system.nav.closeParentWindow(event)
3.4.3.4

Line Schedule Selector

Description
A component that provides users to select a scheduled entry from a drop-down list of available schedule
entries for a production line. The available options include only schedule entries that were scheduled for
the production line and have not already been selected. All schedule entries are automatically displayed
from the "Schedule" database table without the need for custom SQL statements or script.

Line Schedule Selector

Properties
This component has standard Ignition properties with the addition of the following properties:
Inductive Automation

OEE Downtime

408

Line Path

The line path of the production line that this component is associated with. This is
the full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Schedule ID

The currently selected ID of the schedule entry. This is the ID for the "Schedule"
database table.
Scripting name
scheduleID
Data Type
Integer

Include Closed

If true will allow selection of schedules that have not been run and are scheduled
Wo against a closed work order. Default is true.
rk
Ord
ers

Scripting name
Data Type

includeClosedWorkOrders
Boolean

Include Disabled
If true will allow selection of schedules that have not been run and are scheduled
Prod against a disabled product code. Default is true.
uct
Cod
es

Scripting name
Data Type

includeDisabledProductCodes
Boolean

Events
This component has standard Ignition events.
Methods
selectNextRun()
Select next available schedule run.
parameters
(none)
returns
nothing
-----------------------------------------------------------------------------------------------------------------------------selectRun(newScheduleID)
Set new schedule ID.
parameters

newScheduleID The ID of the schedule item to modify. This is the ID for the
"Schedule" database table.
Data Type
Integer
returns

message

Contains a description of any error encountered, otherwise it will be

empty
Data Type
String

Inductive Automation

OEE Downtime
3.4.3.5

409

Schedule Day View

Description
A component that displays scheduled entries for a selected day. This extends from the Day View
Component that comes with Ignition to support adding, editing and deleting schedule entries. All schedule
entries are automatically displayed from the "Schedule" and other database tables without the need for
custom SQL statements or script.
When the user right clicks on a time, a popup menu will appear with options to add, edit or delete a
schedule entry.

Schedule Day View

Properties
This component has the same properties as the Ignition Day View Component with the addition of the
following properties:
Line Path

The line path of the production line that this component is associated with. This is the
full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Current Date

The date to show schedule entries for.

Scripting name
Data Type

Inductive Automation

currentDate
Date

OEE Downtime
Event Display Format

410

Allows a custom string with replaceable parameters to be used. Leave blank to

get the default event display string.
Scripting
eventDisplayFormat
name
Data Type
String
parameters
{wo} = Work Order
{co} = Scheduled Change Over Start Date
{st} = Scheduled Production Start Date
{fn} = Scheduled Finish Time Date
{pc} = Product Code
{pcd} = Product Code description
{qty} = Scheduled Quantity
{nt} = Note
{eb} = Entered By
|
= line feed (the pipe character)
Example:
If you set Event Display Format property to:
Product Code = {pc} - {pcd}|Note: {nt}

The display string would look like:

Product Code = PC243 - 24oz, 3 pack
Note: Short run requested by customer

Events
This control has the same events as the Ignition Table Component with the addition of the following
events:
newEvent

Is fired when the New Entry menu item is selected.

editEvent

Is fired when the Edit Entry menu item is selected.

deldeleteEvent

Is fired when the Delete Entry menu item is selected.

Methods
(none)

Inductive Automation

OEE Downtime

411

Example Code
The following script can be entered into the newEvent event of this component. It collects the selected
time when the right-click occurred and opens a new window with the collected values as parameters.
param1 = event.source.parent.getComponent('Production Line Selector').selectedLinePath
param2 = event.source.parent.getComponent('Schedule Day View').hoveredTimeLatched
system.nav.openWindow('ScheduleNew', {'LinePath' : param1, 'CurrentDate' : param2})
system.nav.centerWindow('ScheduleNew')
3.4.3.6

Schedule Week View

Description
A component that displays scheduled entries for a selected week. This extends from the Week View
Component that comes with Ignition to support adding, editing and deleting schedule entries. All schedule
entries are automatically displayed from the "Schedule" and other database tables without the need for
custom SQL statements or script.
When the user right clicks on a time, a popup menu will appear with options to add, edit or delete a
schedule entry.

Schedule Week View

Properties
This component has the same properties as the Ignition Week Component with the addition of the
following properties:
Line Path

The line path of the production line that this component is associated with. This is the
full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Inductive Automation

OEE Downtime
Current Date

412

The date to show schedule entries for. The date can be any day from Sunday to
Saturday.
Scripting name
currentDate
Data Type
Date

Event Display Format

Allows a custom string with replaceable parameters to be used. Leave blank to

get the default event display string.
Scripting
eventDisplayFormat
name
Data Type
String
parameters
{wo} = Work Order
{co} = Scheduled Change Over Start Date
{st} = Scheduled Production Start Date
{fn} = Scheduled Finish Time Date
{pc} = Product Code
{pcd} = Product Code description
{qty} = Scheduled Quantity
{nt} = Note
{eb} = Entered By
|
= line feed (the pipe character)
Example:
If you set Event Display Format property to:
Product Code = {pc} - {pcd}|Note: {nt}

The display string would look like:

Product Code = PC243 - 24oz, 3 pack
Note: Short run requested by customer

Events
This control has the same events as the Ignition Table Component with the addition of the following
events:
newEvent

Is fired when the New Entry menu item is selected.

editEvent

Is fired when the Edit Entry menu item is selected.

deldeleteEvent

Is fired when the Delete Entry menu item is selected.

Methods
(none)
Example Code
The following script can be entered into the newEvent event of this component. It collects the selected
time when the right-click occurred and opens a new window with the collected values as parameters.
param1 = event.source.parent.getComponent('Production Line Selector').selectedLinePath
param2 = event.source.parent.getComponent('Schedule Week View').hoveredTimeLatched
system.nav.openWindow('ScheduleNew', {'LinePath' : param1, 'CurrentDate' : param2})
system.nav.centerWindow('ScheduleNew')

Inductive Automation

OEE Downtime
3.4.3.7

413

Schedule Month View

Description
A component that displays scheduled entries for a selected month. This extends from the Month View
Component that comes with Ignition to support adding, editing and deleting schedule entries. All schedule
entries are automatically displayed from the "Schedule" and other database tables without the need for
custom SQL statements or script.
When the user right clicks on a time, a popup menu will appear with options to add, edit or delete a
schedule entry.

Schedule Month View

Properties
This component has the same properties as the Ignition Month View Component with the addition of the
following properties:
Line Path

The line path of the production line that this component is associated with. This is the
full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Current Date

The date to show schedule entries for. The date can be any day within the month.
Scripting name
Data Type

Schedule ID

currentDate
Date

The database ID of the selected schedule event. -1 if no event is selected.

Scripting name
Data Type

Inductive Automation

scheduleID
Integer

OEE Downtime

Event Display Format

414

Allows a custom string with replaceable parameters to be used. Leave blank to

get the default event display string.
Scripting
eventDisplayFormat
name
Data Type
String
parameters
{wo} = Work Order
{co} = Scheduled Change Over Start Date
{st} = Scheduled Production Start Date
{fn} = Scheduled Finish Time Date
{pc} = Product Code
{pcd} = Product Code description
{qty} = Scheduled Quantity
{nt} = Note
{eb} = Entered By
|
= line feed (the pipe character)
Example:
If you set Event Display Format property to:
Product Code = {pc} - {pcd}|Note: {nt}

The display string would look like:

Product Code = PC243 - 24oz, 3 pack
Note: Short run requested by customer

Events
This control has the same events as the Ignition Table Component with the addition of the following
events:
newEvent

Is fired when the New Entry menu item is selected.

editEvent

Is fired when the Edit Entry menu item is selected.

deldeleteEvent

Is fired when the Delete Entry menu item is selected.

Methods
(none)

Inductive Automation

OEE Downtime

415

Example Code
The following script can be entered into the newEvent event of this component. It collects the selected
time when the right-click occurred and opens a new window with the collected values as parameters.
param1 = event.source.parent.getComponent('Production Line Selector').selectedLinePath
param2 = event.source.parent.getComponent('Schedule Week View').hoveredTimeLatched
system.nav.openWindow('ScheduleNew', {'LinePath' : param1, 'CurrentDate' : param2})
system.nav.centerWindow('ScheduleNew')
3.4.3.8

Schedule Date Selector

Description
A component that provides an easy method for users to select a day. It synchronizes the Schedule Day
View, Schedule Week View and Schedule Month View components to all be selected to the same date.

Schedule Date Selector

Properties
This component has the same properties as the Ignition Month View Component with the addition of the
following properties:
Current Date

The currently selected date.

Scripting name
currentDate
Data Type
Date

Selected Day

The currently selected date.

Scripting name
currentDate
Data Type
Strin

Add Day

Used to adjust the currently selected day by a specified number of days forward or
backwards. If the specified number of days is positive, then the current date will be
adjust forward by the number of days specified. If the specified number of days is
negative, then the current date will be adjust back by the number of days specified.
Scripting name
addDay
Data Type
Integer

Inductive Automation

OEE Downtime
Add Month

Add Year

416

Used to adjust the currently selected day by a specified number of months

forward or backwards. If the specified number of months is positive, then the
current date will be adjust forward by the number of months specified. If the
specified number of months is negative, then the current date will be adjust
back by the number of months specified.
Scripting name
addMonth
Data Type
Integer
Used to adjust the currently selected day by a specified number of years forward or
backwards. If the specified number of years is positive, then the current date will be
adjust forward by the number of years specified. If the specified number of years is
negative, then the current date will be adjust back by the number of years specified.
Scripting name
addYear
Data Type
Integer

Events
This component has standard Ignition events.
Methods
(none)
Example Code
The following script can be entered into a button's actionPerformed to change the Schedule Date
Selector's Current Date back 1 day.
event.source.parent.getComponent('Schedule Date Selector').addDay = -1
3.4.3.9

Schedule Entry Controller

Description
An invisible component that provides adding, editing and deleting schedule entries. The term invisible
component means that the control appears during design time, but is not visible during runtime.
Scheduled entries are stored in the "Schedule" database table and this control handles all SQL
statements, duplicate checking, etc.
This component has built-in functionality to calculate finish date and time of work order type schedule
entries based on the start date and time, product code, change over time, quantity and configured
workday routine breaks.
Alternatively, schedule entries can added directly into the "Schedule" database table directly, bypassing
the OEE Downtime and Scheduling Module. This method supports integration to ERP or other software
systems.
The properties are provided so that after the Schedule ID property is set, selection components can be
bound to them to display their current values. The methods are provided to perform adding, editing and
deleting of schedule entries.
Properties
This component has standard Ignition properties with the addition of the following properties:
Inductive Automation

OEE Downtime

417

Schedule ID

The currently selected ID of the schedule entry being edited. This is the ID for the
"Schedule" database table.
Scripting name
scheduleID
Data Type
Integer

Line Path

The line path of the production line that this component is associated with. This is the
full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Work Order
ID

The current ID of the work order being scheduled. This is the ID for the "WorkOrder"
database table.
Scripting name
workOrderID
Data Type
Integer

Work Order

The work order number being scheduled.

Scripting name
workOrder
Data Type
String

Product Code

The product code number associated with the work order being scheduled.
Scripting name
productCode
Data Type
String

Product Code
Description

The product code description associated with the work order being scheduled.
Scripting name
Data Type

Schedule
Type

productCodeDescription
String

The type of schedule entry.

Scripting name
Data Type
Options:

scheduleType
Integer
0 = Work Order Run
1 = Maintenance
2 = Other

Start Date
Time

The start date and time of the schedule entry.

Scripting name
Data Type

Run Start
Date Time

startDateTime
Date

The run start date and time of the schedule entry. The Run Start Date Time is the
Start Date Time adjusted by the Change Over Duration. This is the date and time
after change over is complete and the actual production begins.
Scripting name
runStartDateTime
Data Type
Date

Inductive Automation

OEE Downtime
Change Over
Duration

The duration in minutes allowed for changeover.

Scripting name
Data Type

Finish Date
Time

changeOverDuration
Integer

The finish date and time for the schedule entry.

Scripting name
Data Type

Override the
Finish Date
Time

418

finishDateTime
Date

If true, a manual finish date and time will be used instead of the automatic calculation
to forecast the finish time.
Scripting name
Data Type

finishDateTimeOverriden
Boolean

Quantity

The quantity of units to produce for this schedule entry.

Scripting name
quantity
Data Type
Integer

Note

An optional note to associate with the schedule entry.

Scripting name
Data Type

note
String

Events
This component has standard Ignition events.
Methods
addScheduleEntry(linePath, workOrderID, scheduleType, start, coDuration,
finish, quantity, userName, note)
Add a new schedule entry.
parameters

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line starting with
the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

workOrderID

The ID of the work order to modify. This is the ID for the "WorkOrder"
database table.
Data Type
Integer

scheduleType

The type of schedule entry.

Data Type
Integer
Options:
0 = Work Order Run
1 = Maintenance
2 = Other
Inductive Automation

OEE Downtime

419

start

The starting date and time of the schedule entry.

Data Type
Date

coDuration

The duration of the changeover in minutes.

Data Type
Integer

finish

The ending date and time of the scheduled entry.

Data Type
Date

quantity

The quantity of units to produce for this schedule entry.

Data Type
Integer

userName

The name of the user who is adding this scheduled entry.

Data Type
String

note

An optional note to be tied to this scheduled entry.

Data Type
String

message

Contains a description of any error encountered, otherwise it will be

empty
Data Type
String

returns

-----------------------------------------------------------------------------------------------------------------------------editScheduleEntry(linePath, workOrderID, scheduleType, start, coDuration,

finish, quantity, userName, note, scheduleID)
Edit an existing schedule entry.
parameters

Inductive Automation

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line starting with
the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

workOrderID

The ID of the work order to modify. This is the ID for the "WorkOrder"
database table.
Data Type
Integer

scheduleType

The type of schedule entry.

Data Type
Integer
Options:
0 = Work Order Run
1 = Maintenance
2 = Other

start

The starting date and time of the schedule entry.

Data Type
Date

coDuration

The duration of the changeover in minutes.

Data Type
Integer

OEE Downtime

420

finish

The ending date and time of the scheduled entry.

Data Type
Date

quantity

The quantity of units to produce for this schedule entry.

Data Type
Integer

userName

The name of the user who is adding this scheduled entry.

Data Type
String

note

An optional note to be tied to this scheduled entry.

Data Type
String

scheduleID

The ID of the schedule entry to modify. This is the ID for the

"Schedule" database table.
Data Type
Integer

message

Contains a description of any error encountered, otherwise it will be

empty
Data Type
String

returns

-----------------------------------------------------------------------------------------------------------------------------deleteScheduleEntry(workOrderID)
Delete an existing schedule entry.
parameters

scheduleID

The ID of the schedule entry to modify. This is the ID for the

"Schedule" database table.
Data Type
Integer

message

Contains a description of any error encountered, otherwise it wil

empty
Data Type
String

returns

Inductive Automation

OEE Downtime

421

Example Code
The following script can be entered in a button's actionPerformed event. It will add the schedule entry to
the database. The return message will indicate if the there are any issues adding the schedule entry. See
the OEEDemo project's ScheduleNew window for a full implementation example.

esp = event.source.parent
# gather parameters required to add a schedule entry
linePath = esp.LinePath
workOrderID = esp.getComponent('WorkOrderContainer').getComponent('Work Order Selector').sel
scheduleType = esp.getComponent('ScheduleType').selectedValue
startDate = esp.getComponent('StartDateTime').selectedDateTime
coDuration = esp.getComponent('WorkOrderContainer').getComponent('CODuration').selectedValue
finishDate = esp.getComponent('FinishDateTime').selectedDateTime
quantity = esp.getComponent('WorkOrderContainer').getComponent('Quantity').intValue
userName = esp.getComponent('HiddenContainer').getComponent('UserName').text
note = esp.getComponent('note').text
# call the add schedule entry method of the schedule entry controller
result = esp.getComponent('Schedule Entry Controller').addScheduleEntry(linePath, workOrderI
# handle result
if (result == ''):
esp.getComponent('WorkOrderContainer').getComponent('Work Order Selector').selectedIndex =
system.nav.closeParentWindow(event)
3.4.3.10 Schedule Controller

Description
An invisible component that provides selection of scheduled entries for a specified production line. It also
provides start, end and resume control of production runs. The term invisible component means that the
control appears during design time, but is not visible during runtime. Scheduled entries are stored in the
"Schedule" database table and this control handles all SQL statements, duplicate checking, etc.
This component has built-in functionality to calculate finish date and time of work order type of schedule
entries based on the start date and time, product code, change over time, quantity and configured
workday routine breaks.
Alternatively, schedule entries can added directly into the "Schedule" database table directly, bypassing
the OEE Downtime and Scheduling Module. This method supports integration to ERP or other software
systems.
The properties are provided so that after the Schedule ID property is set, selection components can be
bound to them to display their current values. The methods are provided to perform adding, editing and
deleting of schedule entries.

Inductive Automation

OEE Downtime

422

Properties
This component has standard Ignition properties with the addition of the following properties:
Line Path

The line path of the production line that this component is associated with. This is the
full path name of the line starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line 1"
Scripting name
linePath
Data Type
String

Running

The current running read only state of the production line. The production line is
considered running if a production run is started and the line state is running.
Scripting name
running
Data Type
Boolean

Production
Enabled

The current production enabled read only state of the production run. This will be true
after the changeover time has expired or the operator initiated the production run start
depending on the setting of the Auto Start property that configured in the designer.
Scripting name
productionEnabled
Data Type
Boolean

Can Start

This will be true if a production run can start. It is typically used to control the enable
state of a "Start" button on the operator screen.
Scripting name
canStart
Data Type
Boolean

Started

This will be true if the production run is started.

Scripting name
Data Type

Can End

started
Boolean

This will be true if a production run can be ended. It is typically used to control the
enable state of a "End" button on the operator screen.
Scripting name
Data Type

canEnd
Boolean

Can Resume

This will be true if a production run has been ended and a new schedule entry has not
been selected. It is typically used to control the enable state of a "Resume" button on
the operator screen.
Scripting name
canResume
Data Type
Boolean

Can Change
Schedule

This will be true if the current schedule entry can be changed. It is typically used to
control the enable state of a Line Schedule Selector component.
Scripting name
canChangeSchedule
Data Type
Boolean

Is Work Order This will be true if the currently selected schedule entry is a work order type.

Scripting name
Data Type

isWorkOrder
Boolean
Inductive Automation

OEE Downtime
Inhibit Start

423

Can be set to true to prevent a production run from being started.

Scripting name
Data Type

inhibitStart
Boolean

Set to true to start the production run for the current Schedule ID.

Start

Scripting name
Data Type

start
Boolean

Set to true to stop the current production run.

End

Scripting name
Data Type
Resume

end
Boolean

Set to true to resume the current production run.

Scripting name
Data Type

resume
Boolean

Events
This component has standard Ignition events.
Methods
startRun()
Start production run.
parameters
returns

(none)
message

If successful, returns true.

Data Type
String
-----------------------------------------------------------------------------------------------------------------------------endRun()
End production run.
parameters
returns

(none)
message

Inductive Automation

If successful, returns true.

Data Type

String

OEE Downtime

424

-----------------------------------------------------------------------------------------------------------------------------cancelRun()
Cancel production run.
parameters
returns

(none)
message

If successful, returns true.

Data Type
String
-----------------------------------------------------------------------------------------------------------------------------resumeRun()
Resume production run.
parameters
returns

(none)
message

If successful, returns true.

Data Type

String

Example Code
The following script can be entered in a button's actionPerformed event. It will end the current production
run. See the OEEDemo project's Operator_Control window for a full implementation example.
value = 1
event.source.parent.getComponent('Schedule Controller').end = value
3.4.3.11 Time Selector

Description
A component that provides users he option to select a time from a drop-down list. The interval of time
between each option is defined by the Time Interval property.

Tim e Selector

Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

OEE Downtime
Time Interval

425

The time interval between each option in the drop-down list.

Scripting
name
Data Type
Options:

linePath
String
Hour
30 minutes
15 minutes
10 minutes
1 minute

Selected
Date Time

The currently selected date and time.

Scripting name
Data Type

Date Part

The currently selected date.

Scripting name
Data Type

Selected
Time

selectedDateTime
Date

datePart
Date

The currently selected time.

Scripting name
Data Type

selectedTime
String

Events
This component has standard Ignition events.
Methods
(none)

3.4.3.12 Line Schedule View

Description
A component that displays scheduled entries and status for a line, adding, editing and deleting of
schedules and allows drag and drop rescheduling.

Inductive Automation

OEE Downtime

426

Line Schedule View

Events
This control has the common ignition events with the addition of the following events:
userMenuItemClicked

Fired when a user menu item is selected by a right mouse click.

User menu items are added with calls to the method "addUserMenuItem
(<menuName>)".
The are many event properties returned that can be used to drive analysis
data or other type of funtions.
Example:
menuItemName = event.menuItemName
if menuItemName == "Display Click Data":
Date = event.date
LinePath = event.linePath
SchedId = event.scheduleID
RunID = event.runID
RunName = event.runName
StartDate = event.startDate
EndDate = event.endDate
message = "menuItemName=%s\n Date=%s\n LinePath=%s\n
SchedId=%s\n RunID=%s\n RunName=%s\n StartDate=%s\n
EndDate=%s" %(menuItemName, Date, LinePath, SchedId, RunID,
RunName, StartDate, EndDate)
system.gui.messageBox(message, "User Menu Item Clicked")
if menuItemName == "Show Run Actual vs. Scheduled":
Inductive Automation

OEE Downtime

427

RunName = event.runName
system.gui.messageBox(RunName, "User Menu Item
Clicked")
Event Properties
event.menuItemName

Returns the menu name of selected user menu item.

Data Type String

event.linePath

Returns the line path corresponding to where the user menu item was
clicked.
Data Type String

event.date

Returns the date corresponding to where the user menu item was clicked.
Data Type Date

event.scheduleID

Returns the schedule ID of the event where the user menu item was
clicked. If no event exists then it will return -1.
Data Type Integer

event.runID

Returns the run ID of the event where the user menu item was clicked. If
no event exists then it will return -1.
Data Type Integer

event.runName

Returns the run name of the event where the user menu item was clicked.
If no event exists then it will return blank.
Data Type String

event.startDate

Returns the start date of the event where the user menu item was clicked.
If no event exists then it will return None.
Data Type Date

event.endDate

Returns the end date of the event where the user menu item was clicked. If
no event exists then it will return None.
Data Type Date

newEvent

Fired when the new event menu item is selected by a right mouse click.
Use selected component properties to create and add a new schedule.
Example:
This will open the OEE Demo applications schedule new window to add
a new schedule entry. The new schedule window requires the line path
and selected date.

Inductive Automation

OEE Downtime

428

Im plem ent the new Event w ith OEE Dem o existing w indow

Event Properties
(none)

editEvent

Fired when the edit event menu item is selected by a right mouse click.
Use "selectedEvent" from the component to get the scheduleID of the
schedule item to edit.

Event Properties
(none)

deleteEvent

Fired when the delete event menu item is selected by a right mouse click.
Use "selectedEvent" from the component to get the scheduleID of the
schedule item to delete.

Event Properties
(none)

Methods
addUserMenuItem(menuName)
Adds user menu items to the component that will display on a right click of the mouse. Use the
"userMenuItemClicked" event handler to provide any functionality you define for each menu item.
Example (This script is added to the "internalFrameOpened" event for a window and will add the three
user menu items.):
def initMenuItems(event=event):
import system
lineSchedView = system.gui.getParentWindow(event).getComponentForPath('Root Container.Line
Schedule View')
lineSchedView.addUserMenuItem("Display Click Data")
lineSchedView.addUserMenuItem("Show Run Actual vs. Scheduled")
lineSchedView.addUserMenuItem("Show Run Actual vs. Target")
Inductive Automation

OEE Downtime

429

system.util.invokeLater(initMenuItems) # allows all bindings to complete before execution

parameters

menuName

The name of the menu item. It will be returned in the

userMenuItemClicked event as event.menuItemName
Data Type

String

returns
nothing
---------------------------------------------------------------------------------------------------------------------------------------------------------------

Properties
This component has standard Ignition properties with the addition of the following properties:
Drag Enabled

When true schedules can be re-scheduled with drag and drop via the mouse.
Scripting name
dragEnabled
Data Type
Boolean

Time

Controls the time resolution (in minutes) when performing time operations in the
R
component.
e
s
Example:
When set to 5 (minutes) then any right click on the component will be
o
aligned
with the closest 5 minute mark or if dragging a schedule to re-schedule, it will
l into the closest 5 minute mark.
fall
u
t
i
o
n

Scripting name
Data Type

timeResolution
Integer

Start Date

The starting date for display.

Scripting name
startDate
Data Type
Date

End Date

The ending date for display.

Scripting name
endDate
Data Type
Date

Line Filter

A comma separated list of lines to display.

Example: When set to "Line A, Line B" then only Line A and Line B will be displayed.
Scripting name
Data Type

Inductive Automation

lineFilter
String

OEE Downtime
Production Model Item Filter

430

The production model path to filter upon.

Example: When set to "OEEDemo\Your Enterprise\Site 1\Packaging"
then all lines under Packaging will be displayed.
Scripting name
Data Type

Selected Event ID

The selected schedule ID of any mouse click or -1 if no event item exists at

the location.
Scripting name
Data Type

Selected Event Date

Selected Event Line Path

Selected Event Run Name

selectedRunID
Integer

The selected Run Name of any mouse click or blank if no event item
exists at the location.
Scripting name
Data Type

selectedRunName
String

Returns the start date of any mouse click or blank if no event item exists at
the location.
Scripting name
Data Type

selectedEventStart
Date

Returns the end date of any mouse click or blank if no event item exists at
the location.
Scripting name
Data Type

Event Border

selectedLinePath
String

The selected Run ID of any mouse click or -1 if no event item exists at the
location.
Scripting name
Data Type

Selected Event End

selectedDate
Date

The selected line path of any mouse click on an event.

Scripting name
Data Type

Selected Event Start

selectedEvent
Integer

Returns the date in the view where the mouse was right clicked last.
Scripting name
Data Type

Selected Event Run ID

itemPath
String

selectedEventEnd
Date

Sets the border type for non-selected event items displayed.

Scripting name
Data Type

eventBorder
Border
Inductive Automation

OEE Downtime

Selected Event Border

431

Sets the border type for the selected event item.

Scripting name
Data Type

selectedEventBorder
Border

Line Height

Height, in pixels, of each line row.

Scripting name
selectedEventBorder
Data Type
Integer

Event Margin

The margin, in pixels, from the top and bottom of a line row and the event
item displayed.
Scripting name
Data Type

scheduledEventMargin
Integer

Schedule Background

The color of the background of the line rows.

Scripting name
scheduleBackground
Data Type
Color

Current Time Color

The color of the vertical line that indicates the current time.
Scripting name
nowColor
Data Type
Color

Line Color

The color of the general dividing lines in the component.

Scripting name
lineColor
Data Type
Color

Header Font

The font of the header text.

Scripting name
Data Type

headerFont
Font

Header Text Color

The color of the header text.

Scripting name
headerTextColor
Data Type
Color

Header Background

The color of the header background.

Scripting name
headerBackground
Data Type
Color

Progress Bar Background

The color of the progress bar background. The progress bar shows the
the quantity produced versus the quantity scheduled.
Scripting name
progressBackground
Data Type
Color

Progress Bar Fill

The color of the progress bar fill. The progress bar shows the the
quantity produced versus the quantity scheduled.
Scripting name
progressFill
Data Type
Color

Inductive Automation

OEE Downtime
Progress Bar Border

Header Item Font

The color of the progress bar border. The progress bar shows the the
quantity produced versus the quantity scheduled.
Scripting name
progressBorder
Data Type
Color
The font of the line row name header text.
Scripting name
Data Type

Event Font

runCompletedColor
Color

The color of a running event item.

Scripting name
Data Type

Run Scheduled Color

lineStoppedIconPath
String

The color of a completed event item.

Scripting name
Data Type

Run Running Color

lineStoppedColor
Color

The path of the icon to display in the line row header when the line is
stopped.
Scripting name
Data Type

Run Completed Color

lineRunningIconPath
String

The color of the line row header when the line is stopped.
Scripting name
Data Type

Line Item stopped Icon

lineRunningColor
Color

The path of the icon to display in the line row header when the line is
running.
Scripting name
Data Type

Line Item stopped Color

eventFont
Font

The color of the line row header when the line is running.
Scripting name
Data Type

Line Item Running Icon

itemFont
Font

The font of the text displayed in an event item.

Scripting name
Data Type

Line Item Running Color

432

runRunningColor
Color

The color of a scheduled event item.

Scripting name
Data Type

runScheduledColor
Color

Inductive Automation

OEE Downtime
Run Changeover Color

The color of the changeover portion of an event item.

Scripting name
Data Type

Maintenance Completed Color

The color of a completed maintenance item.

Scripting name
Data Type

Scripting name
Data Type
Maintenance Scheduled Color

otherScheduledColor
Color

The color of a break time span background.

Scripting name
Data Type

breakColor
Color

The color of a disabled shift time span background.

Scripting name
Data Type

Inductive Automation

otherRunningColor
Color

The color of other scheduled items.

Scripting name
Data Type

Disabled Shift Color

otherCompletedColor
Color

The color of other running items.

Scripting name
Data Type

Break Color

maintenanceScheduledColor
Color

The color of other completed items.

Scripting name
Data Type

Other Scheduled Color

maintenanceRunningColor
Color

The color of a scheduled maintenance item.

Scripting name
Data Type

Other Running Color

maintenanceCompletedColor
Color

The color of a running maintenance item.

Maintenance Running Color

Other Completed Color

runChangeOverColor
Color

disabledShiftColor
Color

433

OEE Downtime
Event Display Format

434

Allows a custom string with replaceable parameters to be used. Leave blank to

get the default event display string.
Scripting
eventDisplayFormat
name
Data Type
String
parameters
{wo} = Work Order
{co} = Scheduled Change Over Start Date
{st} = Scheduled Production Start Date
{fn} = Scheduled Finish Time Date
{pc} = Product Code
{pcd} = Product Code description
{qty} = Scheduled Quantity
{nt} = Note
{eb} = Entered By
|
= line feed (the pipe character)
Example:
If you set Event Display Format property to:
Product Code = {pc} - {pcd}|Note: {nt}

The display string would look like:

Product Code = PC243 - 24oz, 3 pack
Note: Short run requested by customer

Inductive Automation

OEE Downtime

3.5

435

Production OPC Values

The production model is defined in the Ignition designer and contains your production areas, lines and c
ells. A runtime access into configuration and current state of the production model is available through the
Production OPC Server. It is added automatically when the OEE Downtime and Schedule Module is
installed. When the production items are added, removed or modified, the changes will be reflected in the
Production OPC Server when the project is saved in the designer.
Below is a part of the values available to read, and in some cases write to, for the demo project.

Dem o OPC Values

3.5.1

Using OPC Values

The OEE downtime and scheduling configuration settings and runtime values are available for use in
Ignition windows, transaction groups, scripting, etc. Before values from the Production OPC Server can
be used, they must be added to the Ignition SQLTags. This is done in the designer by selecting the
SQLTags Browser and clicking on the
icon. This will cause the OPC Browser to appear. Next, drill
down in the Production node within the OPC Browser. Drag the desired Production OPC Values over to
the SQLTags Browser as depicted below.

Inductive Automation

OEE Downtime

436

Add Production OPC Server Values to SQLTags

Important:
When writing to OPC values that are related to production model settings, the new value is not retained
upon restarting. This is because production model settings are saved in the Ignition project and is only
saved when done so in the designer.

3.5.2

OPC Value Reference

This references details the OPC values and child folders for node types that appear when browsing the
Production OPC Server. For each property, the Ignition data type is listed and if it is read only. The Ignition
data types correspond to the data types that are available for SQLTags.
Within this reference, the "Read Only" means that the OPC value cannot be written to through the OPC
Production Server. It can only be set in the designer or it is a calculated value. Trying to write to a read
only property will result in an error message being shown.
3.5.2.1

Project

Description
Each project within Ignition has its own production model. The first node(s) under the main Production
node represent the Ignition project(s). Their names are the same as the project name. The image below
represents the OEEDemo project.

Project

Inductive Automation

OEE Downtime

437

Child Folders
Enterprise

3.5.2.2

One folder will exist for each Enterprise that has been configured in the Ignition
Designer. The folder can be opened to view all values within the enterprise.

Enterprise

Description
The enterprise folder contains some properties associated with the enterprise and a folder for each
production Site within it. The name is the same as the enterprise name that is configured in the designer.
The image below represents the "Your Enterprise" of the OEEDemo project.

Enterprise

Child Folders
Site

One folder will exist for each Site that has been configured in the Ignition Designer.
The folder can be opened to view all values within the site.

Properties

Inductive Automation

OEE Downtime

The name of the auxiliary

(mirror) analysis database
connection. Can be blank if no
auxiliary DB connection is
configured.
The name of the analysis
database connection.

String
Read Only

Optionally, this property can be

set to a description for the
enterprise. It is not used by the
OEE Downtime and Scheduling
Module other than for reference.
This reflects the enterprise
Enabled property in the
Designer. If the enterprise
Enabled is set to true, then the
OEE Downtime and Scheduling
module will perform calculations
for the enterprise and all sites,
areas, lines and cells within it. If
this property is set to false, then
none of the sites, areas, lines or
cells will have calculations
performed.
This reflects the name of the
enterprise that is set in the
designer.

String

Runtime DB Connection Name

The name of the runtime

database connection.

String
Read Only

Save Control Limit by Product Code

Indicates if control limits are

saved by product code. Exists
only if the SPC module is also
installed.

Boolean
Read Only

Analysis Auxiliary DB Connection Name

Analysis DB Connection Name

Description

Enabled

Name

3.5.2.3

438

String
Read Only

Boolean

String
Read Only

Site

Description
The site folder contains some properties associated with the production site and a folder for each
production area within it. The name is the same as the site name that is configured in the designer. The
image below represents the "Your Site" of the OEEDemo project.

Inductive Automation

OEE Downtime

439

Site

Child Folders
Workday
Routine

Contains all of the workday routine entries that are active for the production site.

Area

One folder will exist for each area that has been configured in the Ignition Designer.
The folder can be opened to view all values within the area.

Properties
Description

Optionally, this property can be set to a description for the

site. It is not used by the OEE Downtime and Scheduling
Module other than for reference.

String

Enabled

This reflects the site Enabled property in the Designer. If the

site Enabled is set to true, then the OEE Downtime and
Scheduling module will perform calculations for the site and
all areas, lines and cells within it. If this property is set to
false, then none of the areas, lines or cells will have
calculations performed.

Boolean

Name

This reflects the name of the site that is set in the designer.

Default Shift 1
Start Time

This reflects the site Default Shift 1 Start Time property in

the Designer. See Site Configuration for more details.

String
Read Only
DateTime
Read Only

Default Shift 2
Start Time

This reflects the site Default Shift 2 Start Time property in

the Designer. See Site Configuration for more details.

DateTime
Read Only

Default Shift 3
Start Time

This reflects the site Default Shift 3 Start Time property in

the Designer. See Site Configuration for more details.

DateTime
Read Only

3.5.2.4

Area

Description
The area folder contains some properties associated with the production area and a folder for each
production line within it. The name is the same as the area name that is configured in the designer. The
image below represents the "Your Area" of the OEEDemo project.

Inductive Automation

OEE Downtime

440

Area

Child Folders
Workday
Routine

Contains all of the workday routine entries that are active for the production area.

Line

One folder will exist for each Line that has been configured in the Ignition Designer. The
folder can be opened to view all values within the line.

Properties
Description

Optionally, this property can be set to a description for the area. It is

not used by the OEE Downtime and Scheduling Module other than for
reference.

String

Enabled

This reflects the site Enabled property in the Designer. If the area
Enabled is set to true, then the OEE Downtime and Scheduling
module will perform calculations for the area and all lines and cell
within it. If this property is set to false, then none of the lines or cells
will have calculations performed.

Boolean

Name

This reflects the name of the area that is set in the designer.

Shift 1
Start Time

The current Shift 1 Start Time time for the production area. If the
associated Shift 1 Start Time property for the area in the designer is
set to Inherit From Parent, this will be the time defined for the parent
production site. See Area Configuration for more details.

String
Read Only
DateTime
Read Only

Shift 2
Start Time

The current Shift 2 Start Time time for the production area. If the
associated Shift 2 Start Time property for the area in the designer is
set to Inherit From Parent, this will be the time defined for the parent
production site. See Area Configuration for more details.

DateTime
Read Only

Shift 3
Start Time

The current Shift 3 Start Time time for the production area. If the
associated Shift 3 Start Time property for the area in the designer is
set to Inherit From Parent, this will be the time defined for the parent
production site. See Area Configuration for more details.

DateTime
Read Only

Inductive Automation

OEE Downtime
3.5.2.5

441

Line

Description
The line folder contains some properties associated with the production line and a folder for each
production cell within it. The name is the same as the line name that is configured in the designer. The
image below represents the "Line 1" of the OEEDemo project.

Line

Child Folders
Additional
Factors

Contains all of the additional factor entries that have been configured for the
production line. See Additional Factors for more details.

Downtime
Reasons

Contains all of the downtime reasons entries that have been configured for the
production line. See Downtime Reasons for more details.

Workday
Routine

Contains all of the workday routine entries that are active for the production line. See
Workday Routine for more details.

Cell

One folder will exist for each Cell that has been configured in the Ignition Designer.
The folder can be opened to view all values within the cell.

Inductive Automation

OEE Downtime

442

Properties
Int4
Read Only

Active Downtime
Is a Short Stop

Accumulation Count = Infeed Count - Run

Production Count. This represents the
amount of product accumulated on the
production line and is adjusted for package
count. It will be the same units as the
infeed.
Indicates the time, in a formatted string,
that the current line downtime event has
been active.
Indicates if the current active line
downtime event is a short stop.

Active Downtime
Starttime

Indicates the start time that the current line

downtime event started.

DateTime
Read Only

Actual Changeover
End Time

Indicates the time that the current run

ended changeover status and began
running.
The date and time that Enable Run
property was set to false. This typically
happens when the operator clicks the End
button.
The date and time that Enable Run
property was set to true. This typically
happens when the operator clicks the
Start button or a production run auto start
occurred (See Line Configuration
Schedule Settings for more details).
The date and time that new product was
selected to run on the line. Typically, this
happens when the operator selects a new
production run.
Indicates if the line is set to automatically
start schedule entries and begin the run
after any changeover. Overrides "Auto
Start Run" setting.
Indicates if the production run should start
automatically after change over. This will
allow the line to record a downtime event if
it is not running after the allotted
changeover time from the schedule entry.
This value will increment every time OEE,
downtime and scheduling values are
calculated for the project production
model.
Indicates if this run can be cancelled.
Runs can only be cancelled while in
changeover
If true, all conditions are good to resume a
production run.

DateTime
Read Only

Accumulation
Count

Active Downtime
Duration

Actual Finish
Time

Actual Run
Start Time

Actual Start
Time

Auto Run Schedule

Auto Start Run

Calculate
Count

Can Cancel Run

Can Resume
Run

String
Read Only
Boolean
Read Only

DateTime
Read Only
DateTime
Read Only

DateTime
Read Only
Boolean
Read Only
Boolean
Read Only

Int4
Read Only
Boolean
Read Only
Boolean
Read Only

Inductive Automation

OEE Downtime

If true, all conditions are good to start a

production run.
Reference of the downtime reason code
that will be triggered on a changeover
overrun.
Optionally, this property can be set to a
description for the line. It is not used by the
OEE Downtime and Scheduling Module
other than for reference.
This reflects the current value of the
"Downtime Detection Method" setting in
the designer.
Indicates the reason description of the
current line downtime active event.

Boolean
Read Only
Int4
Read Only

Setting Enable Run to true will enable the

production run for the line. Setting it to
false will end the production run. Typically,
this is controlled by the functionality of the
operator screen, but it can also be handled
programmatically.
This reflects the line Enabled property in
the Designer. If the line Enabled is set to
true, then the OEE Downtime and
Scheduling module will perform
calculations for the all cells within it. If this
property is set to false, then none of the
cells will have calculations performed.
The true unit count at the primary product
infeed for the production run. The true unit
count reflects the start of production run
count and raw count rollovers.
This reflects the name of the line that is
set in the designer.

Boolean

OEE

The current OEE value for the current

shift. See OEE for more details.

Float8
Read Only

OEE
Availability

The current OEE Availability value for the

current shift. See OEE for more details.

Float8
Read Only

OEE
Performance

The current OEE Performance value for

the current shift. See OEE for more
details.
The current OEE Quality value for the
current shift. See OEE for more details.

Float8
Read Only

This is the amount of change over time, in

minutes, remaining before the scheduled
run start time .

String
Read Only

Can Start
Run
Changeover Overrun
Reason Code
Description

Downtime
Detection
Method
Downtime Reason
Description
Enable Run

Enabled

Infeed Count

Name

OEE Quality

Prerun
Remaining
Time

Inductive Automation

String

String
Read Only
String
Read Only

Boolean

Int4
Read Only
String
Read Only

Float8
Read Only

443

OEE Downtime
Prerun
Remaining
Time (Seconds)

This is the amount of change over time, in

seconds, remaining before the scheduled
run start time .

Int4
Read Only

Product Code

String

Product Code
Description

The current product code being run on the

line. Typically, this is controlled by the
functionality of the operator screen, but it
can also be handled programmatically. It
should only be changed when Enable Run
is false.
The description for the current Product
Code.

Production
Package Count

The current package count of the primary

outfeed.

Int4
Read Only

Production
Rate (Hour)

Float8
Read Only

Run Down
Time (Minutes)

The current hourly production rate of the

primary product outfeed. See Production
Rate Calculation for more details.
The current production rate per minute of
the primary product outfeed. See
Production Rate Calculation for more
details.
The units of the production rate. This
reflects the units defined in the primary
product outfeed. See Product Outfeed for
more details.
This reflects the value of the "Run
Disabled Reason Code" setting in the
designer.
The total amount of unplanned downtime,
in minutes, for the current production run.

Run Elapsed
Time (Minutes)

The total minutes that have elapsed from

the start of the production run.

Float8
Read Only

Run ID

This is the unique identification number

that was generated by the database when
a row is inserted into the Run table. It can
be used to associate external data to a
production run.
The ideal production count, to the minute,
for the current production run based on the
standard rate. This is based on the time
the line is scheduled to run.
The total amount of planned downtime, in
minutes, for the current production run.

Int4
Read Only

The total production count that has been

produced for the current production run. It
is in the primary product outfeed units.

Int4
Read Only

Production
Rate (Minute)

Production
Units

Run Disabled
Reason Code

Run Ideal
Standard Count

Run Planned
Down Time
(Minutes)
Run
Production
Count

444

String
Read Only

Float8
Read Only
String
Read Only
Int4
Read Only
Float8
Read Only

Int4
Read Only
Float8
Read Only

Inductive Automation

OEE Downtime

The ideal production count, to the minute,

for the current production run based on the
standard rate. This is based on the time
the line has been running, not counting any
downtime.
The variance between the Run Standard
Count and the Run Production Count.

Int4
Read Only

This will equal the time that the production

run started or the beginning of the current
shift, whichever occurred last.
The value will be true if a production run
has started. Even if the production run has
been ended but a new production run has
not been selected, this value will be true.
The ideal production count, to the minute,
for the current production run based on the
scheduling rate.
The variance between the Run Target
Count and the Run Production Count.

DateTime
Read Only

The total minutes that the production line

has run for the current production run. This
value excludes planned and unplanned
downtime.
See Product Waste for more details on
how this value is calculated.

Float8
Read Only

Running

This value will be true if a production run is

started and production line is running.

Boolean
Read Only

Schedule
Rate

The current schedule rate based on the

selected product code and line.

Float8
Read Only

Schedule
Rate Period

The period of time used for the scheduling

rate. The options are Hour and Minute.

String
Read Only

Scheduled
Finish Time

The production run finish date and time as

it appears on the schedule.

DateTime
Read Only

Scheduled
Quantity

The total quantity to produce as it appears

on the schedule.

Int4
Read Only

Scheduled Run
Start Time

The start date and time of the production

run as it appears on the schedule.

DateTime
Read Only

Scheduled
Start Time

The start date and time of the change over

as it appears on the schedule.

DateTime
Read Only

Sequence No

A number that is 0 at the beginning of a

production run and increments at the
beginning of every shift.

Int4
Read Only

Run Standard
Count

Run Standard
Variance
Run Start
Date Time
Run Started

Run Target
Count
Run Target
Variance
Run Time
(Minutes)

Run Waste
Count

Inductive Automation

Int4
Read Only

Boolean
Read Only
Int4
Read Only
Int4
Read Only

Int4

445

OEE Downtime
Shift

The current shift based on the shift start

times configured for the production line.

Int4
Read Only

Shift 1
Enabled

The current Shift 1 enabled state for the

production line. It reflects the Shift 1
Enabled property for the line in the
designer. The initial value of this property
is determined by the Shift 1 Initial Enabled
State property for the production line in the
designer. See Line Configuration for more
details. It can be changed from the initial
value.
The current Shift 1 Start Time time for the
production line. If the associated Shift 1
Start Time property for the line in the
designer is set to Inherit From Parent, this
be the time defined for the parent
production area. See Line Configuration
for more details.
The current Shift 2 enabled state for the
production line. It reflects the Shift 2
Enabled property for the line in the
designer. The initial value of this property
is determined by the Shift 2 Initial Enabled
State property for the production line in the
designer. See Line Configuration for more
details. It can be changed from the initial
value.
The current Shift 2 Start Time time for the
production line. If the associated Shift 2
Start Time property for the line in the
designer is set to Inherit From Parent, this
be the time defined for the parent
production area. See Line Configuration
for more details.
The current Shift 3 enabled state for the
production line. It reflects the Shift 3
Enabled property for the line in the
designer. The initial value of this property
is determined by the Shift 3 Initial Enabled
State property for the production line in the
designer. See Line Configuration for more
details. It can be changed from the initial
value.
The current Shift 3 Start Time time for the
production line. If the associated Shift 3
Start Time property for the line in the
designer is set to Inherit From Parent, this
be the time defined for the parent
production area. See Line Configuration
for more details.

Boolean

Shift 1
Start Time

Shift 2
Enabled

Shift 2
Start Time

Shift 3
Enabled

Shift 3
Start Time

446

DateTime
Read Only

Boolean

DateTime
Read Only

Boolean

DateTime
Read Only

Inductive Automation

OEE Downtime
Shift Down
Time (Minutes)

The total minutes of unplanned downtime

for the current shift.

Float8
Read Only

Shift Elapsed
Time (Minutes)

The total minutes that have elapsed from

the start of the shift.

Float8
Read Only

Shift Infeed
Count

The true unit count at the primary product

infeed for the current shift. The true unit
count reflects the start of shift count and
raw count rollovers.
The total production count that has been
produced for the current shift. It is in the
primary product outfeed units.

Int4
Read Only

The total minutes that the production line

has run for the current shift. This value
excludes planned and unplanned
downtime.
The total number of units that should be
produced for the current shift. If a
production run extends over multiple shifts,
this value is calculated for the current shift.
This value is adjusted for previous shift
true production whether it did not achieve
or exceeded its target.
This value will equal whichever is less of
the forecasted production run completion
time and the end of the current shift.

Float8
Read Only

The ideal production count, to the minute,

for the current shift based on the standard
rate.
The variance between the Shift Standard
Count and the Shift Production Count.

Int4
Read Only

Int4
Read Only

Shift Target
Variance

The ideal production count, to the minute,

for the current shift based on the
scheduling rate.
The variance between the Shift Target
Count and the Shift Production Count.

Shift Waste
Count

The amount that the Run Waste Count

increased for the current shift.

Int4
Read Only

Standard
Rate

The current standard rate based on the

selected product code and line.

Float8
Read Only

Standard
Rate Period

The period of time used for the standard rate. String

The options are Hour and Minute.
Read Only

State SQL
Tag

This reflects the State SQLTag setting that

the production line is configured for in the
designer. It is the name of the SQLTag to
read the current production line state from.

Shift
Production
Count
Shift Run
Time (Minutes)

Shift
Scheduled
Count

Shift
Scheduled
Finish Time
Shift Standard
Count
Shift Standard
Variance
Shift Target
Count

Inductive Automation

Int4
Read Only

Int4
Read Only

DateTime
Read Only

Int4
Read Only

Int4
Read Only

String
Read Only

447

OEE Downtime
Work Order

3.5.2.6

The current work order number for the

current production run.

448

String
Read Only

Cell

Description
The cell folder contains some properties associated with the production cell. The name is the same as
the cell name that is configured in the designer. The image below represents the Filler of the OEEDemo
project.

Cell

Inductive Automation

OEE Downtime

449

Child Folders
Contains all of the downtime reasons entries that have been configured for
the production cell. See Downtime Reasons for more details.

Downtime
Reasons

Properties
Accumulation
Count

Accumulation Count = Infeed Count - Run Production Count. This

represents the amount of product accumulated on the production
line and is adjusted for package count. It will be the same units as
the infeed.

Int4
Read Only

Active

Indicates the time, in a formatted string, that the current line

D
downtime
event has been active.

String
Read Only

o
w
n
t
i
m
e
Duration
Active

Indicates if the current active line downtime event is a short stop.

D
o
w
n
t
i
m
e

Is a Short Stop
Active
Indicates the start time that the current line downtime event started.
D
o
w
n
t
i
m
e
Starttime
Cell Enabled
If Cell Enabled is set to true, then the OEE Downtime and

Scheduling module will perform calculations for the cell. This value
is determined by the product code and production line. It can also be
programmatically changed.

Boolean
Read Only

DateTime
Read Only

Boolean
Read Only

Default Cell
Enabled

This reflects the site Default Cell Enabled property in the Designer.

Boolean
Read Only

Description

Optionally, this property can be set to a description for the cell. It is

not used by the OEE Downtime and Scheduling Module other than
for reference.

String

Downtime

The description of the currently active downtime for the cell.

String
Read Only

R
e
Inductive Automation

OEE Downtime

450

a
s
o
n
Description
Infeed Count

The true unit count at the primary product infeed for the production
run. The true unit count reflects the start of production run count and
raw count rollovers.

Line DT Bypass When true (checked) indicates the cell will not be considered during

Int4
Read Only
Boolean

line downtime determination. This tag can be set at runtime.

Line DT Bypass Displays the selected reason code that will be used when the cell is
Reason Code bypassed.

Int4
Read Only
Boolean
Read Only

Log Downtime Indicates if the cell will log all downtime events. If false then you will
D be able to see any non-line affecting events.
not
e
t
a
i
l
s
Name
This reflects the name of the cell that is set in the designer.

OEE
Availability

The current OEE value for the current shift. See OEE for more
details.
The current OEE Availability value for the current shift. See OEE for
more details.

String
Read Only
Float8
Read Only
Float8
Read Only

OEE
Performance

The current OEE Performance value for the current shift. See OEE
for more details.

Float8
Read Only

OEE
Quality

The current OEE Quality value for the current shift. See OEE for
more details.

Float8
Read Only

Production
Package
Count

The current package count of the primary outfeed.

Int4
Read Only

Production
Rate (Hour)

The current hourly production rate of the primary product outfeed.

See Production Rate Calculation for more details.

Float8
Read Only

Production
Rate (Minute)

The current production rate per minute of the primary product

outfeed. See Production Rate Calculation for more details.

Float8
Read Only

Production
Units

The units of the production rate. This reflects the units defined in the
primary product outfeed. See Product Outfeed for more details.

String
Read Only

Run Down
The total amount of unplanned downtime, in minutes, for the current
Time (Minutes) production run.

Float8
Read Only

OEE

Inductive Automation

OEE Downtime

451

Run ID

This is the unique identification number that was generated by the

database when a row is inserted into the Run table. It can be used
to associate external data to a production run.

Int4
Read Only

Run Ideal
Standard
Count

The ideal production count, to the minute, for the current production
run based on the standard rate. This is based on the time the line is
scheduled to run.

Int4
Read Only

Run Planned
Down Time
(Minutes)

The total amount of planned downtime, in minutes, for the current

production run.

Float8
Read Only

Run
Production
Count

The total production count that has been produced for the current
production run. It is in the primary product outfeed units.

Int4
Read Only

Run Standard
Count

The ideal production count, to the minute, for the current production
run based on the standard rate.

Int4
Read Only

Run Standard
Variance

The variance between the Run Standard Count and the Run
Production Count.

Int4
Read Only

Run Target
Count

The ideal production count, to the minute, for the current production
run based on the scheduling rate.

Int4
Read Only

Run Target
Variance

The variance between the Run Target Count and the Run
Production Count.

Int4
Read Only

Run Time
(Minutes)

The total minutes that the production line has run for the current
production run. This value excludes planned and unplanned
downtime.

Float8
Read Only

Run Waste
Count

See Product Waste for more details on how this value is

calculated.

Int4

Running

This value will be true if a production run is started and production

line is running.

Boolean
Read Only

Sequence No

A number that is 0 at the beginning of a production run and

increments at the beginning of every shift.

Int4
Read Only

Shift Down
The total minutes of unplanned downtime for the current shift.
Time (Minutes)

Float8
Read Only

Shift Elapsed The total minutes that have elapsed from the start of the shift.
Time (Minutes)

Float8
Read Only

Shift Infeed
Count

The true unit count at the primary product infeed for the current shift.
The true unit count reflects the start of shift count and raw count
rollovers.

Int4
Read Only

Shift
Production
Count

The total production count that has been produced for the current
shift. It is in the primary product outfeed units.

Int4
Read Only

Shift Run
The total minutes that the production line has run for the current
Time (Minutes) shift. This value excludes planned and unplanned downtime.

Inductive Automation

Float8
Read Only

OEE Downtime

452

Shift
Scheduled
Count

The total number of units that should be produced for the current
shift. If a production run extends over multiple shifts, this value is
calculated for the current shift. This value is adjusted for previous
shift true production whether it did not achieve or exceeded its
target.

Int4
Read Only

Shift
Scheduled
Finish Time

This value will equal whichever is less of the forecasted production

run completion time and the end of the current shift.

DateTime
Read Only

Shift
Standard
Count

The ideal production count, to the minute, for the current shift based
on the standard rate.

Int4
Read Only

Shift
Standard
Variance

The variance between the Shift Standard Count and the Shift
Production Count.

Int4
Read Only

Shift
Target
Count

The ideal production count, to the minute, for the current shift based
on the scheduling rate.

Int4
Read Only

Shift
Target
Variance

The variance between the Shift Target Count and the Shift
Production Count.

Int4
Read Only

Shift Waste
Count

The amount that the Run Waste Count increased for the current
shift.

Int4
Read Only

Standard Rate The current standard rate based on the selected product code and

Float8
line.
Read Only
Standard Rate The period of time used for the standard rate. The options are Hour and String
Period
Minute.
Read Only
State

The current state for the production line. The value of 0 is reserved
for idle or line powered off and 1 is reserved for running. All other
values are defined in the downtime reasons for the production line.
See Line Configuration for more details.

Int4

State SQL
Tag

This reflects the State SQLTag setting that the production line is
configured for in the designer. It is the name of the SQLTag to read
the current production line state from.

String
Read Only

3.5.2.7

Additional Factors

Description
The additional factors folder contains a folder for each additional factor within it. The name of each folder
is the same as the additional factor name that is configured in the designer. The image below represents
the "Line 1" additional factors of the OEEDemo project. In the OEEDemo there is one additional factor to
track the operator during a production run. See Line Configuration and Additional Factors for more details.

Inductive Automation

OEE Downtime

453

Additional Factors

Properties
Factor
Optionally, this property can be set to a description for the additional
Description factor. It is not used by the OEE Downtime and Scheduling Module

String

other than for reference.

Factor
Name
Factor
SQLTag

3.5.2.8

This reflects the name of the additional factor that is configured in the
designer.
This reflects the Factor SQLTag setting that the additional factor is
configured for in the designer. It is the name of the SQLTag to read the
factor value from.

String
Read Only
String
Read Only

Workday Routine

Description
The workday routine folder contains a folder for each workday routine entry within it. The name of each
folder is the same as the workday routine entry name that is configured in the designer. The image below
represents the Site workday routine entries of the OEEDemo project. See Workday Routines for more
details.

Workday Routine

Properties

Inductive Automation

OEE Downtime
Name
Start
Time

End
Time

3.5.2.9

454

This reflects the name of the workday routine entry that is configured
in the designer.
This reflects the Start Time setting that the workday routine entry is
configured for in the designer. It is the time that the workday routine
starts.

String
Read Only
DateTime
Read Only

This reflects the End Time setting that the workday routine entry is
configured for in the designer. It is the time that the workday routine
ends.

DateTime
Read Only

Downtime Reasons

Description
The downtime reason folder contains a folder for each downtime reason entry within it. The name of each
folder is the same as the downtime reason entry name that is configured in the designer. The image
below represents the Filler cell downtime reason entries of the OEEDemo project. See Downtime
Reasons for more details.

Dow ntim e Reasons

Properties

Inductive Automation

OEE Downtime

455

Reason
Name

This reflects the Reason Name property of the downtime reason

entry that is configured in the designer.

String
Read Only

Reason
Code

This reflects the Reason Code property of the downtime reason

entry that is configured in the designer.

Int4
Read Only

Record
Downtime

This reflects the Record Downtime property of the downtime reason

entry that is configured in the designer. If true, downtime events with
this reason code will count as unplanned downtime during the OEE
calculation.

Boolean
Read Only

Planned
Downtime

This reflects the Planned Downtime property of the downtime

reason entry that is configured in the designer. If true, downtime
events with this reason code will count as planned downtime during
the OEE calculation.

Boolean
Read Only

Operator
Selectable

This reflects the Operator Selectable property of the downtime

reason entry that is configured in the designer. If true, the downtime
reason will be shown in the Down Time Table. See Down Time
Table for more details.

Boolean
Read Only

Inductive Automation

OEE Downtime

3.6

456

Binding Function Reference

The OEE Downtime and Scheduling Module takes advantage of Ignition's built-in binding functions in order
to provide data to the standard components within Ignition.
To access the binding functions, click on the

icon of a component property as shown below.

Drop-Dow n List Com ponent

The binding options window will appear. Next click on the Functions option and select one of the binding
functions from the drop-down list.

Binding Options List

The parameters that are associated with the selected binding function will appear. Each of these
parameters can accept a constant value, bound to a property of another component, or bound to a
SQLTag.

Inductive Automation

OEE Downtime

457

Property Binding Window

Once the parameters have been set and the polling mode selected, the server will return the results
based on the provided parameter values.

3.6.1

Analysis

The following binding functions are provided by the Production Module, which comes with the OEE
Downtime and Scheduling Module.
3.6.1.1

Analysis Filter

Description
The Analysis Filter binding function is used to return available filter values for the Analysis Controller
Component
. Normally this is automatically handled by the Analysis Selector Component
, but for
the Analysis Controller, these filter values are not known. This binding function can provide filter option data to
a drop-down list or other types of components.

Inductive Automation

OEE Downtime

458

Function Name
Filter Options
Parameters
Analysis
Type

This parameter is the provider name that will be used. See Analysis
Providers for available options.

String

Filter Name

This parameter is the name of the filter for which available options
will be returned. See Analysis Providers for available options.

String

Start Date

The starting date range. To reduce the number of options, only the
options for the selected date range will be returned.
The ending date range. To reduce the number of options, only the
options for the selected date range will be returned.

Date

This binding function returns a Dataset with one string column with
the available filter options.

Dataset

End Date

Date

Return
Filter
Options

3.6.2

History

The following binding functions are provided by the OEE Downtime Module, which comes with the OEE
Downtime and Scheduling Module.
3.6.2.1

Downtime History

Description
The Down Time History binding function is used to return historical downtime data for a production run.
This data is gathered from the runtime database tables. This binding function can provide downtime data
to tables, charts or other types of components.
If the current run is selected, downtime data from the current production run will be returned.
Function Name
Down Time History
Parameters
Production
Line or
Cell Path

The line or cell path of the production item that this component is
associated with. This is the full path name of the line or cell starting
with the project name. If the path ends with a line, the line downtime
will be returned. If the path includes a cell, then downtime for the
specified cell will be returned.
For example: "OEEDemo\Your Enterprise\Your Site\Your Area\Line
1".

String

Include Total
Downtime

If this parameter value is true, then total downtime for the production
line will be included in the results

Boolean

Inductive Automation

OEE Downtime

459

Run ID

The production run ID for which data will be returned. This is the ID
for the "Run" database table. If this parameter is set to -1 or left
blank, data for the current production run for the specified production
line will be returned.

Integer

Run
Sequence
No
Include
Entire
Run

The sequence number starts at 0 when a production run starts. It is

Integer
incremented by one at the start of a new shift. This provides a method to
limit results for a single shift or production runs that span over multiple
days.
If this parameter value is true, all shifts for the production run are
Boolean
returned, If it is false, then only the shift specified by the value in Run
Sequence No parameter will be returned.

Top Reasons
to Show

The number of top downtime reasons to return is determined by the

value of this parameter.

Integer

This binding function returns a Dataset with a variable number of

columns based in the parameter settings.

Dataset

Return
Downtime
History
3.6.2.2

Production History

Description
The Production History binding function is used to return historical runtime data for a production run. The
data for this binding function is gathered from the runtime database tables. The Production History binding
function can provide production run data to tables, charts or other types of components.
If the current run is selected, production data from the current production run will be returned.
Function Name
Production History
Parameters
Production Line Path

The line path of the production line that this component is

associated with. This is the full path name of the line starting
with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1".

String

Run ID

The production run ID for which data will be returned. This is

the ID for the "Run" database table. If this parameter is left
blank or set to -1, data for the current production run for the
specified production line will be returned.

Integer

Run Sequence No

The sequence number starts at 0 when a production run starts. ItInteger

is incremented by one at the start of a new shift. This provides a
method to limit results for a single shift or production runs that
span over multiple days.

Inductive Automation

OEE Downtime

460

Include Entire Run

If this parameter value is true, all shifts for the production run are Boolean
returned, If it is false, then only the shift specified by the value in
Run Sequence No parameter will be returned.

Interval

This parameter specifies the time interval that the results are to Hour,
be to organized by.
Minute

Number
Minute
to Show

This parameter specifies the minimum number of minutes in

which the results should be returned. This keeps chart
appearance from shifting on each update.

Integer

Include Actual
Production
Counts

If this parameter value is true, actual production counts will be

included in the results.

Boolean

Include
Standard
Production
Counts

If this parameter value is true, standard production counts will be Boolean

included in the results. Standard production counts are based on
the standard rate.

Include Target
Production
Counts

If this parameter value is true, target production counts will be

included in the results. Target production counts are based on
the scheduling rate.

Include Line
Accumulation
Counts

If this parameter value is true, line accumulation counts will be Boolean

included in the results. Accumulation counts reflect the
difference of the infeed and outfeed counts. In other terms, the
amount of product that has accumulated on the production line.

Include
Efficiency
Values

If this parameter value is true, the percentage of efficiency will be Boolean

included in the results.

Boolean

Return
Production History

3.6.2.3

This binding function returns a Dataset with a variable

number of columns based in the parameter settings.

Dataset

Scheduled vs. Actual

Description
The Scheduled vs. Actual binding function is used to return scheduled and actual data for the selected
production run. Primarily used as the Series Data for the Analysis Time Chart component.
Function Name
Scheduled vs. Actual
Parameters
Production Line Path

The line path of the production line. This is the full path name
of the line starting with the project name. This parameter is
commonly bound to a Production Line Selector component.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1".

String

Inductive Automation

OEE Downtime
Run ID

Sequence No

Normalize Start Times

Include Scheduled

461

The production run ID for which data will be returned. This is

Integer
the ID for the "Run" database table. If this parameter is left
blank or set to -1, data for the current production run for the
specified production line will be returned. This parameter is
commonly bound to Line Run Selector component.
The sequence number starts at 0 when a production run starts. ItInteger
is incremented by one at the start of a new shift. This provides a
method to limit results for a single shift or production runs that
span over multiple days. May be left blank to display all shifts.
If this parameter value is true, the actual start will be offset to be Boolean
equal to the scheduled start time. This is usefull for displaying
run that were not started close to the scheduled time and allows
comparison of scheduled and actual to be aligned.
If this parameter value is false the scheduled data will not be
Boolean
included.

Include Actual

If this parameter value is false the actual run data will not be
included.

Boolean

Include Cells

If this parameter value is true, actual cell run data for each cell
will be included in the results.

Boolean

Include Other Downtime If this parameter value is true, downtime events that are neither

Boolean

planned or unplanned will be returned in the results. For

instance, a cell may have a downtime event for outfeed backup
that is not set to be a recordable or a planned downtime.
Include User Comments If this parameter value is true, the results will contain reference toBoolean

any user comments entered during the actual run. The Analysis
Time Chart component can display the reference.
Stop Type

Determines the type of downtime stops to return. Both will return Long and Short
stops. See the Short Downtime Threshold seconds section for more information
on stop types.
Values
Both
String
Short Stops
Long Stops

Return
Scheduled vs. Actual

Inductive Automation

This binding function returns a Dataset with a variable

number of columns based in the parameter settings.

Dataset

OEE Downtime

3.7

462

Scripting

The OEE Downtime modules support various scripting functions that are availably on both the client and
the gateway. The Line Event scripts are by line and cell and allow performing custom tasks when the line
execution cycle is occurring. The custom OEE calculation scripts allow changing the default OEE
calculations. When overriding the default scripts, it will be effective for run and shift OEE calculation as
well as historical analysis. The Ignition gateway scripts will run on the gateway so that clients do not have
to be running for them to be used. And last there are many events, methods and properties associated
with the components. These are not covered in this section. See Component Reference for more
information.
Additional scripting help and examples can be found in the Ignition Manual.

3.7.1

Line Events

Due to modules included in the OEE Downtime and Scheduling Module, the need for scripting is virtually
nonexistent. However, if the user would like to expand on the existing scripting, or make adjustments to
better fit his or her needs, this can still be done within Ignition. Scripting is also used with Lines and Cells
under the Advanced tab. In order to edit the script under this tab, simply click the
desired script, then click OK to save.

button and enter the

Advanced Tab for a Line

These scripts are executed in relation to the line events:

Run Start Script - When a run is started. Triggered once before the pre-execute script.
Reset Run Script - When a run reset is triggered. This occurrs when a new schedule is selected or a
new product code for a line is selected but, before the line starts actually running. Triggered once before
the pre-execute script.
Pre-execute Script - Triggered before each time the line is to perform the process of updating the line
counts, and calculating the OEE values.
Execute Script - Triggered every time after the line has executed the updates and calculations, but, before
the values have been written to the database.
Inductive Automation

OEE Downtime

463

Post Execute Script - Triggered every time after the line has written the lates values to the database.
Calculate Standard Counts Script - The Calculate Standard Counts Script and allow the use a different
method of OEE calculation. See example below.

Example:
This script is used under Run Start Script in the demo project and will cause the PLC production
simulator to run when the operator clicks Start.
value = 'true'
system.tag.writeToTag('[Default]Line 1/PLC/Run', value)

The Calculate Standard Counts Script and allow the use a different method of OEE calculation
Located in Line -> Advanced -> Calculate Standard Counts Script
Calculations are performed every minute. If you set a new value, it takes affect until the next time
the calculations are performed.
OEECounts event
event.getPath() String
event.getName() String
event.getInfeedCount() Integer
event.getProductionCount() Integer
event.getPackageCount() Double
event.getStandardRate() Double
event.getStandardRatePeriod() String
event.getTargetCount() Integer
event.setTargetCount(Integer targetCount) void
event.getTargetVariance() Integer
event.setTargetVariance(Integer targetVariance) void
event.getStandardCount() Integer
event.setStandardCount(Integer standardCount) void
event.getIdealStandardCount() Integer
event.setIdealStandardCount(Integer idealStandardCount) void
event.getStandardVariance() Integer
event.setStandardVariance(Integer standardVariance) void
event.getWasteCount() Integer
event.setWasteCount(Integer wasteCount) void

3.7.2

Custom OEE Calculations

Created in Project -> Events Script (Gateway) -> Startup

If a custom script is added for any key then it is responsible for setting
the value, internal calculations will not be run.
Each key type will allow access to the component parts of the calculation, see
definition of each key for those parts.
Inductive Automation

OEE Downtime

464

Format:
system.oee.addCustomScript(key, script)
system.oee.removeCustomScript(key)
Key:
system.oee.AVAILABILITY
system.oee.PERFORMANCE
system.oee.QUALITY
system.oee.OEE

Event properties:
AVAILABILITY key
event.getElapsedTime() Double
event.getRunTime() Double
event.getPlannedDownTime() Double
event.getAvailability() Double
event.setAvailability(Double availability) void

PERFORMANCE event
event.getInfeedCount() Integer
event.getPackageCount() Double
event.getStandardRatePeriod() String
event.getStandardRate() Double
event.getProductionCount() Integer
event.getWasteCount() Integer
event.getRunTimeMin() Double
event.getElapsedTimeMin() Double
event.getStandardCount() Integer
event.getPerformance() Double
event.setPerformance(Double performance) void

QUALITY event
event.getInfeedCount() Integer
event.getWasteCount() Integer
event.getQuality() Double
event.void setQuality(Double quality) void

OEE event
event.getAvailability() Double
event.getPerformance() Double
event.getQuality() Double
event.getOEE() Double
event.setOEE(Double oee) void

Example:
script="event.setAvailability(0.85)"
system.oee.addCustomScript(system.oee.AVAILABILITY, script)
system.oee.removeCustomScript(system.oee.AVAILABILITY)

3.7.3

OEE Factor Cap

Created in Project -> Events Script (Gateway) -> Startup

Allows overriding the default cap of 100% for OEE factors of Availability, Performance and Quality.
If this script exists during a gateway save or restart then the OEE factor(s) will be set to the maxPercent.
If the script is removed and the gateway is restarted the OEE factor(s) will be set to 100%.
Inductive Automation

OEE Downtime

465

Format:
system.oee.setOEEFactorCap(key, maxPercent)
Key:
system.oee.AVAILABILITY
system.oee.PERFORMANCE
system.oee.QUALITY

Example:
system.oee.setOEEFactorCap(system.oee.AVAILABILITY, 250)
system.oee.setOEEFactorCap(system.oee.PERFORMANCE, 150)
system.oee.setOEEFactorCap(system.oee.QUALITY, 75)

3.7.4

Gateway Scripts

Methods
system.production.addProductCode(projectName, productCode, description)

Adds a new product code to the system.

parameters
projectName

A valid project name.

Data Type

String

productCode

The product code.

For example: "Cola_12oz_Cans"
Data Type
String

description

A description of this product code.

Data Type
String

result

Error message if the product code could not be added, blank if

successful.
Data Type
String

returns

Inductive Automation

OEE Downtime

466

system.production.utils.addRunComment(projectName, linePath, userName, note, isSticky

Adds a comment note to the current run for the selected line.
parameters
projectName

A valid project name.

Data Type

String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

userName

User name for this comment

Data Type

String

This comment
Data Type

String

note

isSticky

If set to 1 (True) the note will appear at the top of the list, if 0
(False) the note will appear in order it was entered.
Data Type

Boolean

returns
none

Inductive Automation

OEE Downtime

467

system.production.adjustRunData(runUUID, cellName, factorName, factorValue)

system.production.adjustRunData(runUUID, cellName, factorName, factorValue,
adjustInfeed)

Recalculates production data for a line or a cell based on the factor name and the factor value. The run
must be complete for adjustment to be accurate.
parameters
runUUID

The unique run identifier of the run to adjust. This value can be
accessed via the Analysis Controller datapoint called "Run
Identifier".
Data Type
String

cellName

Name of the cell to adjust. Leave blank to indicate the line

Data Type

factorName

The run factor to adjust. The possible values are "InfeedCount",

"ProductionCount" or "WasteCount"
Data Type
String

factorValue

The value to set the factor to. NOTE: PRODUCTION DATA WILL
BE MODIFIED AND CANNOT BE UNDONE. USE WITH
EXTREME CAUTION.
Data Type
Double

adjustInfeed

If set to 1 (True) the InfeedCount will always be modified, if 0

(False) the InfeedCount will not be modified if ProductionCount
or WasteCount are being adjusted. If this parameter is omitted
the default is 1 (True).
Data Type

returns
none

Inductive Automation

String

Boolean

OEE Downtime

468

system.production.adjustRunDataByShift(runUUID, cellName, ShiftDate, factorName,

factorValue)
system.production.adjustRunDataByShift(runUUID, cellName, ShiftDate, factorName,
factorValue, adjustInfeed)

Recalculates production data for a line or a cell based on the shift, factor name and the factor value. The
run must be complete for adjustment to be accurate.
parameters
runUUID

The unique run identifier of the run to adjust. This value can be
accessed via the Analysis Controller datapoint called "Run
Identifier".
Data Type
String

cellName

Name of the cell to adjust. Leave blank to indicate the line

Data Type

shiftDate

String

The shift date you want adjusted. This value can be accessed via
the Analysis Controller datapoint called "Shift Date".
Data Type

Date

factorName

The run factor to adjust. The possible values are "InfeedCount",

"ProductionCount" or "WasteCount"
Data Type
String

factorValue

The value to set the factor to. NOTE: PRODUCTION DATA WILL
BE MODIFIED AND CANNOT BE UNDONE. USE WITH
EXTREME CAUTION.
Data Type
Double

adjustInfeed

If set to 1 (True) the InfeedCount will always be modified, if 0

(False) the InfeedCount will not be modified if ProductionCount
or WasteCount are being adjusted. If this parameter is omitted
the default is 1 (True).
Data Type

Boolean

returns
none

Inductive Automation

OEE Downtime

469

system.production.cancelRun(projectName, linePath)

Cancel the current run for a line. This is only valid if the production run is currently in the changeover
period.
parameters
projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully has been

canceled.
Data Type
Boolean

returns

system.production.endRun(projectName, linePath)

End the current run for a line. This is only valid if the line is currently in a production run. After a production
run has been ended, it can restarted using the resume script function.
parameters
projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully ended.

Data Type
Boolean

returns

Inductive Automation

OEE Downtime

470

system.production.getLineID(projectName, linePath)

Returns the internal line id of the given line path. Allows advanced usage of direct SQL queries in the
database.
parameters
projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

lineID

Returns the internal line id of the linepath or -1 if the line could not
be found.
Data Type
Integer

returns

system.production.isProductionModelRunning(projectName)

Returns true if the production model for this project is running.

parameters
projectName

The project name that contains the specified line path.

Data Type
String

running

Returns true if the production model for this project is running.

Data Type
Boolean

returns

Inductive Automation

OEE Downtime

471

system.production.reset(runUUID, cellName, shiftDate, factorName)

Sets to 0 the Infeed count and the factor count for the cell or line. The run must be complete for
adjustment to be accurate.
parameters
runUUID

The unique run identifier of the run to reset. This value can be
accessed via the Analysis Controller datapoint called "Run
Identifier".
Data Type
String

cellName

Name of the cell to reset. Leave blank to indicate the line.

Data Type

shiftDate

The shift date you want reset. This value can be accessed via the
Analysis Controller datapoint called "Shift Date".
Data Type

factorName

String

Date

The run factor to adjust. The possible values are "InfeedCount",

"ProductionCount" or "WasteCount"
Data Type
String

returns
none

system.production.resumeRun(projectName, linePath)

Resume the current production run for a line. This is only valid if the production run has ended.
parameters
projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully has been

resumed.
Data Type
Boolean

returns

Inductive Automation

OEE Downtime

472

system.production.setLineProductCode(projectName, linePath, productCode)

Set the current product code for a line. If the line is currently in a production run, it will have to be ended
before setting a new product code. The product code must exist in the production code table and the line
must be enabled to run it.
parameters
projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

productCode

The new product code for the line to run next.

Data Type
String

successful

Returns true if the project name, line path and product code
are valid and the new product code has been set.
Data Type
Boolean

returns

system.production.startLineProductCode(projectName, linePath, productCode)

Set the current product code for a line and immediately starts it running. If the line is currently in a
production run, it will have to be ended before setting a new product code. The product code must exist in
the production code table and the line must be enabled to run it.
parameters
projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

productCode

The new product code for the line to run next.

Data Type
String

successful

Returns true if the project name, line path and product code
are valid and the new product code has been set.
Data Type
Boolean

returns

Inductive Automation

OEE Downtime

473

system.production.startRun(projectName, linePath)

Start a new production run for the current product code. This is only valid if the line is not currently in a
production run.
parameters
projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully started.

Data Type
Boolean

returns

system.production.updateProductCodeLineStatus(projectName, productCode, linePath,

enable)

Updates the line enabled status for this product code.

parameters

Inductive Automation

projectName

The project name that contains the specified line path.

Data Type
String

linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

productCode

The new product code for the line to run next.

Data Type
String

enable

Set to 0 to disable, 1 to enable.

Data Type
Integer

OEE Downtime

474

system.schedule.selectRun(projectName, linePath, scheduleID)

Select the schedule entry to run on the specified line. The scheduleID can be obtained from the Schedule
database table. If the line is currently in a production run, it will have to be ended before setting a new
product code. The schedule entry must be valid with a work order and product code appropriate for the
line.
parameters
projectName
linePath

The project name that contains the specified line path.

Data Type
String
The line path of the production line that this component is
associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

scheduleID

The value from the ID column of the schedule database table

Data Type
Integer

successful

Returns true if the new schedule entry for the line has
successfully been selected.
Data Type
Boolean

returns

system.schedule.selectNextRun(projectName, linePath)

Select the next schedule entry to run on the specified line. The next schedule entry is the row in the
database Schedule table in chronological order by the StartDateTime column. The schedule entry must
be valid with a work order and product code appropriate for the line.
parameters
projectName
linePath

The project name that contains the specified line path.

Data Type
String
The line path of the production line that this component is
associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

returns
successful

Returns true if the new schedule entry for the line has
successfully been selected.
Data Type
Boolean

Inductive Automation

OEE Downtime

3.7.5

475

Client/Designer Scripts

Methods
system.production.utils.addProductCode(productCode, description)

Adds a new product code to the system.

parameters
productCode

The product code.

For example: "Cola_12oz_Cans"
Data Type
String

description

A description of this product code.

Data Type
String

result

Error message if the product code could not be added, blank if

successful.
Data Type
String

returns

system.production.utils.addRunComment(linePath, userName, note, isSticky

Adds a comment note to the current run for the selected line.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

userName

User name for this comment

Data Type

String

This comment
Data Type

String

note

isSticky

If set to 1 (True) the note will appear at the top of the list, if 0
(False) the note will appear in order it was entered.
Data Type

returns
none

Inductive Automation

Boolean

OEE Downtime

476

system.production.utils.adjustRunData(runUUID, cellName, factorName, factorValue)

system.production.utils.adjustRunData(runUUID, cellName, factorName, factorValue,
adjustInfeed)

Recalculates production data for a line or a cell based on the factor name and the factor value. The run
must be complete for adjustment to be accurate.
parameters
runUUID

The unique run identifier of the run to adjust. This value can be
accessed via the Analysis Controller datapoint called "Run
Identifier".
Data Type
String

cellName

Name of the cell to adjust. Leave blank to indicate the line

Data Type

String

factorName

The run factor to adjust. The possible values are "InfeedCount",

"ProductionCount" or "WasteCount"
Data Type
String

factorValue

The value to set the factor to. NOTE: PRODUCTION DATA WILL
BE MODIFIED AND CANNOT BE UNDONE. USE WITH
EXTREME CAUTION.
Data Type
Double

adjustInfeed

If set to 1 (True) the InfeedCount will always be modified, if 0

(False) the InfeedCount will not be modified if ProductionCount
or WasteCount are being adjusted.
Data Type

Boolean

returns
none

Inductive Automation

OEE Downtime

477

system.production.utils.adjustRunDataByShift(runUUID, cellName, ShiftDate,

factorName, factorValue)
system.production.utils.adjustRunDataByShift(runUUID, cellName, ShiftDate,
factorName, factorValue, adjustInfeed)

Recalculates production data for a line or a cell based on the shift, factor name and the factor value. The
run must be complete for adjustment to be accurate.
parameters
runUUID

The unique run identifier of the run to adjust. This value can be
accessed via the Analysis Controller datapoint called "Run
Identifier".
Data Type
String

cellName

Name of the cell to adjust. Leave blank to indicate the line

Data Type

shiftDate

The shift date you want adjusted. This value can be accessed via
the Analysis Controller datapoint called "Shift Date".
Data Type

Date

factorName

The run factor to adjust. The possible values are "InfeedCount",

"ProductionCount" or "WasteCount"
Data Type
String

factorValue

The value to set the factor to. NOTE: PRODUCTION DATA WILL
BE MODIFIED AND CANNOT BE UNDONE. USE WITH
EXTREME CAUTION.
Data Type
Double

adjustInfeed

If set to 1 (True) the InfeedCount will always be modified, if 0

(False) the InfeedCount will not be modified if
ProductionCount or WasteCount are being adjusted. If this
parameter is omitted the default is 1 (True).
Data Type

returns
none

Inductive Automation

String

Boolean

OEE Downtime

478

system.production.utils.cancelRun(linePath)

Cancel the current run for a line. This is only valid if the production run is currently in the changeover
period.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully has been

canceled.
Data Type
Boolean

returns

system.production.utils.endRun(linePath)

End the current run for a line. This is only valid if the line is currently in a production run. After a production
run has been ended, it can restarted using the resume scriptioning function.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully ended.

Data Type
Boolean

returns

Inductive Automation

OEE Downtime

479

system.production.utils.getLineID(linePath)

Returns the internal line id of the given line path. Allows advanced usage of direct SQL queries in the
database.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

lineID

Returns the internal line id of the linepath or -1 if the line could not
be found.
Data Type
Integer

returns

system.production.utils.isProductionModelRunning()

Returns true if the production model for this project is running.

parameters
(none)

returns
running

Inductive Automation

Returns true if the production model for this project is running.

Data Type
Boolean

OEE Downtime

480

system.production.utils.reset(runUUID, cellName, shiftDate, factorName)

Sets to 0 the Infeed count and the factor count for the cell or line. The run must be complete for
adjustment to be accurate.
parameters
runUUID

The unique run identifier of the run to reset. This value can be
accessed via the Analysis Controller datapoint called "Run
Identifier".
Data Type
String

cellName

Name of the cell to reset. Leave blank to indicate the line.

Data Type

shiftDate

The shift date you want reset. This value can be accessed via the
Analysis Controller datapoint called "Shift Date".
Data Type

factorName

String

Date

The run factor to adjust. The possible values are "InfeedCount",

"ProductionCount" or "WasteCount"
Data Type
String

returns
none

system.production.utils.resumeRun(linePath)

Resume the current production run for a line. This is only valid if the production run has been ended.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully has been

resumed.
Data Type
Boolean

returns

Inductive Automation

OEE Downtime

481

system.production.utils.setLineProductCode(linePath, productCode)

Set the current product code for a line. If the line is currently in a production run, it will have to be ended
before setting a new product code. The product code must exist in the production code table and the line
must be enabled to run it.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

productCode

The new product code for the line to run next.

Data Type
String

successful

Returns true if the project name, line path and product code
are valid and the new product code has been set.
Data Type
Boolean

returns

system.production.utils.startLineProductCode(linePath, productCode)

Set the current product code for a line and immediately starts it running. If the line is currently in a
production run, it will have to be ended before setting a new product code. The product code must exist in
the production code table and the line must be enabled to run it.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

productCode

The new product code for the line to run next.

Data Type
String

successful

Returns true if the project name, line path and product code
are valid and the new product code has been set.
Data Type
Boolean

returns

Inductive Automation

OEE Downtime

482

system.production.utils.startRun(linePath)

Start a new production run for the current product code. This is only valid if the line is not currently in a
production run.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the production run successfully started.

Data Type
Boolean

returns

system.production.utils.updateProductCodeLineStatus(productCode, linePath, enable)

Updates the line enabled status for this product code.

parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

productCode

The new product code for the line to run next.

Data Type
String

enable

Set to 0 to disable, 1 to enable.

Data Type
Integer

Inductive Automation

OEE Downtime

483

system.schedule.selectRun(linePath, scheduleID)

Select the schedule entry to run on the specified line. The scheduleID can be obtained from the Schedule
database table. If the line is currently in a production run, it will have to be ended before setting a new
product code. The schedule entry must be valid with a work order and product code appropriate for the
line.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

scheduleID

The value from the ID column of the schedule database table

Data Type
Integer

successful

Returns true if the new schedule entry for the line has
successfully been selected.
Data Type
Boolean

returns

system.schedule.selectNextRun(linePath)

Select the next schedule entry to run on the specified line. The next schedule entry is the row in the
database Schedule table in chronological order by the StartDateTime column. The schedule entry must
be valid with a work order and product code appropriate for the line.
parameters
linePath

The line path of the production line that this component is

associated with. This is the full path name of the line
starting with the project name.
For example: "OEEDemo\Your Enterprise\Your Site\Your
Area\Line 1"
Data Type
String

successful

Returns true if the new schedule entry for the line has
successfully been selected.
Data Type
Boolean

returns

Inductive Automation

OEE Downtime

3.8

484

Analysis Providers

Analysis providers determine which information will be viewed on a graph or pie chart. Based on which
Analysis Provider is selected, some filter, compare by, and data point options may or may not be visible.
For example, the filter Recordable Downtime can be selected if the analysis provider is Downtime, but
not if the analysis provider is Comment.

Analysis Providers

3.8.1

Comment

Description
The Comment Analysis Provider is used to query production run comments entered by users.
Provider Name
Comment
Filters
These are the filters that are available in the OEE Downtime and Scheduling Module. However, in addition
to these filters, additional factors may be available if they are string data type. All additional factors start
with "Factor:". For example, "Factor:Operator". A filter will allow the user to see all of the data points in the
analysis provider as it pertains to a specific area, shift, etc. For more information on filters, see the Filter
By paragraph in the Analysis Screen section.
Area
Enterprise
Line
Package Count
Product Code
Production Units
Run
Shift
Site

Compare By
These are the comparisons that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". A comparison allows one data point
to be compared between all areas, days, etc. For more information on comparisons, see the Compare By
paragraph in the Analysis Screen section.
Area
Inductive Automation

OEE Downtime

485

Day
Enterprise
Line
Month
Package Count
Product Code
Production Units
Run
Shift
Site
Week

Data Points
These are the data points that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". Data points are the different values
that will be presented or compared on a graph or chart. For more information on data points, see the Data
Point paragraph in the Analysis Screen section.
Area
Comment
Date
Entered By
Enterprise
Line
Package Count
Product Code
Product Code Description
Production Units
Run
Shift
Site

3.8.2

Downtime

Description
The Downtime Analysis Provider is used to analyze downtime data.
Provider Name
Downtime

Inductive Automation

OEE Downtime

486

Filters
These are the filters that are available in the OEE Downtime and Scheduling Module. However, in addition
to these filters, additional factors may be available if they are string data type. All additional factors start
with "Factor:". For example, "Factor:Operator". A filter will allow the user to see all of the data points in the
analysis provider as it pertains to a specific area, shift, etc. For more information on filters, see the Filter
By paragraph in the Analysis Screen section.
Area
Automatic Reason
Cell Name
Enterprise
Line
Operator Reason
Package Count
Planned Downtime
Product Code
Production Units
Recordable Downtime
Run
Shift
Site

Compare By
These are the comparisons that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". A comparison allows one data point
to be compared between all areas, days, etc. For more information on comparisons, see the Compare By
paragraph in the Analysis Screen section.
Area
Automatic Reason
Cell Name
Enterprise
Line
Operator Reason
Package Count
Product Code
Production Units
Run
Shift

Inductive Automation

OEE Downtime

487

Site

Data Points
These are the data points that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". Data points are the different values
that will be presented or compared on a graph or chart. For more information on data points, see the Data
Point paragraph in the Analysis Screen section.
Area
Automatic Reason
Cell Name
Enterprise
Line
Occurrences
Operator Reason
Package Count
Product Code
Production Units
Run
Shift
Site

3.8.3

OEE

Description
The Run Analysis Provider is used to analyze OEE and production data.
Provider Name
Run

Inductive Automation

OEE Downtime

488

Filters
These are the filters that are available in the OEE Downtime and Scheduling Module. However, in addition
to these filters, additional factors may be available if they are string data type. All additional factors start
with "Factor:". For example, "Factor:Operator". A filter will allow the user to see all of the data points in the
analysis provider as it pertains to a specific area, shift, etc. For more information on filters, see the Filter
By paragraph in the Analysis Screen section.
Area
Cell Name
Enterprise
Hour Of Run
Line
Package Count
Product Code
Production Units
Run
Shift
Site

Compare By
These are the comparisons that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". A comparison allows one data point
to be compared between all areas, days, etc. For more information on comparisons, see the Compare By
paragraph in the Analysis Screen section.
Area
Cell Name
Day
Enterprise
Hour Of Run
Line
Month
Package Count
Product Code
Production Units
Run
Shift
Site
Week
Inductive Automation

OEE Downtime

489

Data Points
These are the data points that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". Data points are the different values
that will be presented or compared on a graph or chart. For more information on data points, see the Data
Point paragraph in the Analysis Screen section.
Area
Cell Down Time
Cell Infeed Count
Cell Name
Cell Package Count
Cell Production Count
Cell Production Units
Cell Run Time
Cell Standard Count
Cell Target Count
Cell Waste Count
Date
Enterprise
Hour Of Run
Line
Line Infeed Count
Line Production Count
Line Standard Count
Line Standard Rate
Line Standard Rate Period
Line Target Count
Line Waste Count
OEE
OEE Availability
OEE Performance
OEE Quality
Package Count
Product Code
Production Units
Run
Run Down Time

Inductive Automation

OEE Downtime

490

Run Elapsed Time

Run Planned Down Time
Run Time
Shift
Site

3.8.4

Schedule

Description
The Schedule Analysis Provider is used to analyze scheduled versus actual production run times.
Provider Name
Schedule
Filters
These are the filters that are available in the OEE Downtime and Scheduling Module. However, in addition
to these filters, additional factors may be available if they are string data type. All additional factors start
with "Factor:". For example, "Factor:Operator". A filter will allow the user to see all of the data points in the
analysis provider as it pertains to a specific area, shift, etc. For more information on filters, see the Filter
By paragraph in the Analysis Screen section.
Area
Enterprise
Line
Package Count
Product Code
Production Units
Run
Shift
Site
Compare By
These are the comparisons that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". A comparison allows one data point
to be compared between all areas, days, etc. For more information on comparisons, see the Compare By
paragraph in the Analysis Screen section.
Area
Enterprise
Line
Package Count
Product Code
Inductive Automation

OEE Downtime

491

Production Units
Site
Data Points
These are the data points that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". Data points are the different
values that will be presented or compared on a graph or chart. For more information on data points, see
the Data Point paragraph in the Analysis Screen section.
Actual Finish Time
Actual Run Start Time
Actual Start Time
Area
Enterprise
Line
Package Count
Product Code
Product Code Description
Production Units
Run
Scheduled Finish Time
Scheduled Quantity
Scheduled Run Start Time
Scheduled Start Time
Site

3.8.5

TEEP

Description
The TEEP Analysis Provider is used to analyze utilization data.
Provider Name
TEEP

Inductive Automation

OEE Downtime

492

Filters
These are the filters that are available in the OEE Downtime and Scheduling Module. However, in addition
to these filters, additional factors may be available if they are string data type. All additional factors start
with "Factor:". For example, "Factor:Operator". A filter will allow the user to see all of the data points in the
analysis provider as it pertains to a specific area, shift, etc. For more information on filters, see the Filter
By paragraph in the Analysis Screen section.
Area
Enterprise
Line
Package Count
Product Code
Production Units
Run
Site

Compare By
These are the comparisons that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". A comparison allows one data point
to be compared between all areas, days, etc. For more information on comparisons, see the Compare By
paragraph in the Analysis Screen section.
Area
Enterprise
Line
Package Count
Product Code
Production Units
Run
Site

Data Points
These are the data points that are available in the OEE Downtime and Scheduling Module. However, in
addition to these comparisons, additional factors may be available if they are string data type. All
additional factors start with "Factor:". For example, "Factor:Operator". Data points are the different values
that will be presented or compared on a graph or chart. For more information on data points, see the Data
Point paragraph in the Analysis Screen section.
Area
Enterprise
Line
Loading (Actual)
Inductive Automation

OEE Downtime
Loading (Scheduled)
OEE
OEE Availability
OEE Performance
OEE Quality
Package Count
Product Code
Production Units
Run
Shift
Site
TEEP (Actual)
TEEP (Scheduled)

Inductive Automation

493

OEE Downtime

3.9

494

Miscellaneous

This section contains additional information to be used for reference.

3.9.1

Additional Factors

The OEE Downtime and Scheduling Module collects and logs a number of downtime and production data
values. However, what if other values outside of downtime and production values are of interest?
Additional factors are the solution.
Additional Factors are user defined data points that are logged along with the production and downtime
information. Once they are logged, they can be shown in charts, tables and reports. Additionally, other
analyses can be done by filtering and/or setting up comparisons by their values.
Any value that can be read from an Ignition SQLTag can be added as a additional factor. This includes
values derived from scripts, or from barcode readers, databases, calculations, PLCs, etc.
Example: An additional factory named cardboard manufacturer can be added. The operator can select
the manufacturer that provided the cardboard or it can be obtained from some other source. Now, OEE
and downtime results can be shown for each cardboard manufacturer. This can identify quality problems
with raw material that directly affect efficiencies.
In the OEEDemo, the operator is setup as an additional factor. The operator's name will be logged along
with the production and downtime data. By doing so, OEE and downtime information can be filtered and
grouped by the operator name. But this could just as well be the production crew, supervisor,
maintenance crew or any other user defined value that can be monitored or entered into the system.

3.9.2

Production Rate Calculation

Rate per Minute

The production rate per minute is calculated from the change between the current production count and
the production count from the prior minute.
Rate per Hour
The production rate per hour is calculated by recording the production count every minute. Then the
hourly rate is calculated from the change between the current production count and the production count
from an hour ago. When a production line first starts up and there are no production counts from one hour
ago, a project calculation is used.

Inductive Automation

SPC Quality
Part IV

SPC Quality

496

SPC Quality
This section of the manual is intended for documenting the SPC Module and does not expand on SPC
(Statistical Process Control) itself. There are many books that go into great detail of both quality and SPC
that should be referenced for information and procedures on determining how to improve quality.
Even though quality and SPC are sometimes used interchangeably, they are different. Quality is very
broad and includes much more than just SPC, while SPC is used as a tool in the quality process. The
Ignition SPC module focuses only on SPC.
A quick example may help with pointing out the difference between quality and SPC. If product in the
warehouse is going bad over time, then a process has to start to narrow in on the cause. It will involve
brainstorming and fishbone diagrams to determine the possible causes which may be the source of the
problem. In the case of an off-color product, it could be rust building up in pipes, chemical formulation
changes, or different raw materials being used. This part of the example refers to quality. Unlike SPC,
quality requires more than installing software, collecting samples and analyzing the results.
Once the most likely causes of the off-color product have been determined, SPC can be used to monitor
the attributes and narrow down and isolate the cause. It may be determined that when the pH of a subingredient falls out of a certain range, the stability of the product color is degraded. With this knowledge,
SPC can be used to monitor the pH so that if it falls out side of range, it can be corrected quickly. This
prevents a bigger problem that may appear after the product sits in the warehouse for a period of time.

Inductive Automation

SPC Quality

4.1

497

Introduction

The Ignition SPC module exceeds the capabilities of normal SPC software. It performs many tasks
beyond control charts and manual data entry. Below is a list of some of the features that the SPC
modules is capable of:
Manual sample collections
Automatic sample collections
Scheduling samples based on realtime production conditions
Alerting of samples coming due, due or overdue
Automatic evaluation of control limits and out of control signals without human intervention
Alerting of out of control conditions
Customizable screens
An much more
The SPC module is very powerful, but some implementations need more functionality or different
functionality than what is originally included. The SPC module sits on top of the Ignition platform, which
allows for configuring it to accommodate the desired functionality.

4.1.1

SPC Charts

Here is a brief overview of the control charts in the Quality modules. The control charts can be separated
into three groups: value charts, attribute charts, and analysis charts. On all charts, it is possible to add
assignable causes and notes to explain a data point. A sample note can be entered on the Lab or Test
Stations page when the sample is first entered. This can be done by selecting a sample, then clicking
Add Note. An attribute note is added directly from an SPC chart by right-clicking on a data point and
selecting Set Note from the drop-down list. In addition to attribute notes, an assignable cause can also be
added in this way. Assignable causes can also be saved for future use.
Out-of-Control Signals and Control Limits can also be added to the graphs.
Value Charts
X Bar Range Chart: The X Bar Range Chart is used when there are multiple measurements taken in
one sample. For example, if the pH is taken for five different pieces of product, the five different
measurements will show up in the X Bar Range table. If all of these values are added together and then
divided by the number of measurements taken, it will equal the average value, or x bar. This is what is
graphed on the X Bar chart. When the lowest value is subtracted from the highest value, this equals the
range, which is graphed on the Range chart. The range shows the overall consistency of the attribute
being measured. The larger the range is, the less consistent the measurements are. If a point is not
consistent with the rest of the data and is affecting other calculated values, this data point can be deleted.
This will allow other calculated values, such as the x-double-bar and control limits, to reflect the data
more accurately. X-double-bar is the average of all the averages, or the average of all the data points
shown on the graph. Control limits are calculated to show where most data points on the graph will fall,
provided the process is not out-of-control.
The X Bar Range chart should be used when data is generated frequently and is variable. This chart is
useful for detecting small changes in the process and when multiple measurements are taken to
represent a larger group of product.
Individuals Chart: The Individuals Chart is similar to the X Bar Range Chart. However, only one
Inductive Automation

SPC Quality

498

measurement is taken per sample instead of multiple. This means that the X Bar will always be the same
value as the measurement, and a moving range will be calculated instead of the basic range. This means
that instead of subtracting the lowest value from the highest value in one sample, moving range will
calculate the difference between one sample and the next, showing the change from sample to sample. If
a single measurement is used on the X Bar Range Chart, the range will always be zero, which fails to
show the consistency between measurements.
Individuals charts are useful in situations when testing of a product results in the destruction of the
product or if the testing is time consuming. It can also be used when a sample will yield the same result
for a long period of time no matter how many measurements are made, such as batch operations. When
using the Individuals Chart, the variable data should fall into a normal distribution, meaning the data points
are equally likely to fall on either side of the average. This would appear as a bell curve on a histogram.
Median Chart: The Median Chart is also known as the MA-MR Chart or Moving Average-Moving Range
Chart. Because data is generated slowly, the data on this chart is displayed differently. The first sample
will contain three new data points. The second sample will contain the two most recent data points from
sample one, in addition to one new data point. Sample three will contain the two most recent from sample
two, as well as one new data point, and so on. Even though there are three samples with three data
points each, there is only a total of five data points. Ont his chart, the median and the moving range are
graphed. The median is the middle value based on the measurements in the sample (this is not the same
as the average), while the range is the highest value minus the lowest value for each sample.
Like an individual chart, this chart should be used when the data is variable. In addition, data may also be
costly or time-consuming to gather, or remain constant for a long periods of time. This chart should also
be used when the data will not be normally distributed or when detecting small process changes.
X Bar Standard Deviation Chart: This chart is very similar to the X Bar Range Chart. The major
difference between the two is that the X Bar and S chart uses standard deviation to find the amount of
variation within a sample instead of the range.
Data must be in variable form to use this chart. It should also be used when data is plentiful enough that
samples can have ten measurements or more, or when there is a need to rapidly detect small changes.
Attribute Charts
P Chart: P charts are used to track the proportion of nonconforming items in a sample. The number of
nonconformities per item is irrelevant for this type of chart, which only tracks the total number of items;
however, it is possible to have the types of nonconformities displayed on the same chart.
P charts are used only when looking at the number of nonconforming items and when the sample size is
not consistent.
NP Chart: Unlike the P Chart, the NP chart requires that all the sample sizes are the same. The number
of nonconforming items is graphed instead of the proportion because the samples can be directly
compared. The types of nonconformities can also be displayed on the same chart.
This chart should be used when counting nonconforming items when the sample size does not change.
C Chart: Also know as a count chart, this type counts the total number of nonconformities (not
nonconforming items) on all the items in a sample. Often, the types of nonconformities and their
individual counts are noted as well.
Inductive Automation

SPC Quality

499

This chart is best used when counting nonconformities when the sample size will not vary. It is also
important that each sample has equal opportunity for nonconformities.
U Chart: A U Chart also graphs the number of nonconformities, but does so through a proportion. In this
chart, the types and counts of nonconformities are tracked as well.
This chart should be used when counting nonconformities when the sample size will vary. Also, if some
samples have a greater opportunity for nonconformities than others, this chart should be used over the C
Chart.
Analysis Charts
Histogram: A histogram shows the distribution of the data provided from the samples. A typical histogram
has a "normal distribution," meaning that most data points will fall in the middle of the graph and fewer will
fall towards the outside, forming a bell curve. A distribution that is normal is just the most common
pattern. There are other types of curves, such as skewed distribution or double-peaked distribution, which
may be typical for certain processes. If a bell-shaped curve is formed on the histogram, then any
variations in the data are most likely due to an assignable cause. Assignable causes influence variations,
which can occur in materials, environment, machines, peoples, etc. Ultimately, the histogram shows the
consistency of a process.
Histograms should be used when data is numerical and the shape of the distribution is to be observed.
Observing the shape of the graph can help to determine whether or not the data is distributed normally, if
a change has occurred in the process over time, or if two or more processes are different. This graph can
also help to communicate with others about the data distribution or determine if a process will be able to
meet the requirements of a customer.
Pareto: The pareto chart is a bar chart that is used to show which factors are the biggest problems. The
bars are arranged so that the most significant factor, that is, the factor that occurs the most frequently or
cost the most (whether that be in time or money), is on the left, while the shortest bar, or least significant,
is on the right.
Because of the organization of the pareto chart, it is best used when looking at how often problems or
causes occur and which of those are the most significant, or when looking at a specific component of a
larger problem. Like the histogram chart, the pareto is also useful for the communication of data.

4.1.2

Scheduling Samples

If you worry about samples being taken at the correct time and not being faked after the fact, you are not
alone. It is not a matter of whether or not the person responsible for taking samples has been distracted
and missed taking samples, it is a matter of when. The Ignition SPC module has powerful features that
will schedule samples based on current realtime production conditions.
For example, if a lab staff is required to take samples every hour a production line is running, what
happens when there is a break down or the production start is delayed because the lack of raw
materials? How does the lab technician know when production started and if it has been a hour? In a
variety of ways, the Ignition module can let the lab technician know that production has started and a
sample is coming due, is due or is overdue. This can be expanded to instantly inform all parties that
should know of various sample due states.
This can be utilized for more than taking live process samples. It can also be used for other checks that
have to be done around the production facility such as weekly inspections of values or rodent traps.
Inductive Automation

SPC Quality

4.1.3

500

Evaluating Signals

Typically, SPC software requires that someone opens a screen and visually checks for out of control
conditions. Just like the scheduling of samples, someone may be distracted by other pressing production
issues and fail to complete the task. The Ignition SPC module has powerful features that will automatically
evaluate out of control signals every time new sample data is recorded. This can be expanded to instantly
inform all parties that should know of various out of control conditions.

Inductive Automation

SPC Quality

4.2

501

Getting Started

This getting started guide will step you though SPC Quality module installation, demo installation, the
demo user interface and configuration features.

4.2.1

Installation

To install the SPC module into an existing Ignition system, follow the instructions in the Existing Ignition
System. If you are installing Ignition at the same time, use the instructions in the New Ignition System.
To install the Quality Demo project, follow the steps in the Demo Installation section.
4.2.1.1

Existing Ignition System

4.2.1.1.1 Installing Modules

To install the SPC module on to an existing Ignition server, follow the steps below:
Before installing the SPC module, it is recommended to first setup the database connection that will be
used to store SPC data.
1. Download the Quality-Installer-module.modl module
from the Inductive Automation download website. It will be under the MES modules heading.
2. Install the Quality-Installer-module.modl module
Navigate to the Modules page of the Ignition gateway. At the bottom of the list of already installed modules,
click the
link. Next, browse to the Quality-Installer-module.modl file and
click the install button as shown below.

Inductive Automation

SPC Quality

502

Install Ignition Module

Inductive Automation

SPC Quality

503

The SPC Installer module will install all required modules. These are the Production and SPC modules. It
is important to keep in mind not to install or update these modules individually. Instead, it should be done
by updating the SPC Installer module.
4.2.1.2

New Ignition System

4.2.1.2.1 Selecting Install Options

To install the SPC module at the same time as Ignition add the following steps to the normal Ignition
installation:
1. Select "Custom Configuration" on the setup step during the Ignition installation.
The following screen will appear. Scroll down to SPC Module and select it. This will cause the modules
required for SPC functionality to be installed at the same time as Ignition.

.
Ignition Installer

4.2.1.3

Configure Database

SPC data is stored in databases external to Ignition. These database(s) are setup in the gateway
configuration section by selecting the Databases> Connections section from the left-hand configuration
menu. See the Ignition documentation for more information on setting up a database connection. Below
shows a typical database connection that is required for the SPC module.

Inductive Automation

SPC Quality

504

Sam ple Database Connection

4.2.1.4

MES Module Settings

The OEE Downtime, Scheduling and SPC module stores data in a SQL database. Because Ignition can
be configured to multiple databases, the MES Module Settings configuration page is used to select which
databases to store OEE, downtime, scheduling and SPC data. If only one database has been configured
in Ignition, then it will be selected by default.
To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules.
If more than one database connection exists, then the desired database connection can be selected to be
used by the MES modules as shown below.

Inductive Automation

SPC Quality

505

MES Module Settings Page

4.2.2

User Interface

This section is a quick walk through of the demo project that is included with the SPC Module. It is
intended to provide a starting point for SPC implementation. It can be modified, added to or completely
replaced to meet you specific requirements.
The functionality of the SPC demo project includes:
Sample definitions
Scheduling samples
Sample entry
Late / missing sample indication
Control charts
Analysis beyond control charts
The demo is divided into two sections: control charts and user screens. Click on the Quality User
Screens or SPC Control Charts for the section you wish to work with.

Inductive Automation

SPC Quality

506

SPC Module Dem o Project Main Screen

4.2.2.1

Quality User Screens

This is the Quality User Screen Menu. Here, the user can click on the menu item to select the
corresponding screen or click on the Back to Main to return back to the main demo menu.

Inductive Automation

SPC Quality

507

User Screen Menu

4.2.2.1.1 Overview

Below is the overview screen that is included with the SPC demo. It demonstrates control charts that are
updated automatically every time new sample measurement data is recorded. It also demonstrates
indicators of both overdue samples and processes that are out of control. The indicators can just as
easily be alerts that appear in the alarm list or are sent as emails or text messages using the Ignition
alerting functionality.

Inductive Automation

SPC Quality

508

Overview Screen

4.2.2.1.2 Sample Definitions

Sample definitions originate from two different sources. One source is the Tag Collectors that are defined
in the designer and are for the sole purpose of creating samples automatically from Ignition tags (no
human intervention). The other source is from the sample definitions created using the screens covered
in this section, and are for the purpose of manual or semi-automatic collection of sample data (human
intervention).
The sample definition screen is made up of components from the SPC modules that work together to
allow for the management of sample definitions.
By selecting a sample definition, the attributes, locations, control limits and signals associated with it are
shown. The attributes define the data measurements to collect for each sample. The locations define the
virtual locations that are appropriate for this sample definition. The Control Limits table defines which
limits to apply to this sample definition. And last, the signals define which out of control signals to apply to
the sample definition.

Inductive Automation

SPC Quality

509

Sam ple Definitions Screen

Adding a New Sample Definition

A new sample definition can be added by right-clicking the Definitions Table and selecting "Add" from the
drop-down menu. A window will appear, allowing the user to define multiple general information settings.
The auto approve will automatically approve a sample when the measurement data associated with it is
recorded. Once a sample is approved, it will appear on the control charts and will included when
automatically evaluating for out of control conditions behind the scenes. If the auto approve is not selected
then samples based on this sample definition will have to be manually or programmatically approved.
The other general information is straight forward and is described in more detail in the Sample Definition
section of this manual. The default auto schedule information defines how samples are scheduled. In the
image below, the pH sample definition is set to manual meaning samples are created manually be the
user. See the location section below for more information.

Inductive Automation

SPC Quality

510

Add Sam ple Definition Window

After adding a new definition, the attributes must be defined. This is done by right-clicking the Attributes
table and selecting "Add" from the drop-down menu. This opens a window similar to the one before,
which allows users to define each attribute. Some examples of attributes include pH, temperature,
viscosity, weight, nonconformities, and nonconforming items. From here, the name, description, dataype,
format, default value, minimum value, and maximum value can be defined. This window also allows the
users to decide if the attribute will be required when entering sample data on the Lab or Test Stations
screen.

Inductive Automation

SPC Quality

Add and Edit Attribute Window s

Inductive Automation

511

SPC Quality

512

Next, the locations, or where the samples will be taken, can be defined. Again, this can be done by rightclicking on the Locations table and selecting "Add" from the drop-down menu. The ownership field
declares who is responsible for the testing of the sample, whether that be the lab or the operator at the
testing station.
The interval type defines how the samples will automatically be scheduled. Or as in the image below, they
will be manually created by the user. If the interval is set to Timed Interval (Hours) then a sample will
automatically scheduled as defined by the Interval setting. When a new project is created, the default
Intervals options are also created but they can be modified, added to or even removed. See Sample
Definition Location for more details of each of the settings.

Add Location Window

Any selected control limits will be available to include on the control charts and will also be included in the
automatic evaluation of out of control conditions of the sample data. When a new project is created, the
default control limit options are also created but they can be modified, added to or even removed. Keep in
mind that each control limit is associated with a particular control chart. For example, XBar UCL is
associated and can only be used with the XBar chart. This is because the calculation used to determine
the XBar UCL value is specific to only the XBar chart.

Inductive Automation

SPC Quality

513

Control Lim its Table

Any selected signals will be available to include on the control charts and will also be included in the
automatic evaluation of out of control conditions of the sample data. When a new project is created, the
default signal options are also created but they can be modified, added to or even removed. Keep in mind
that each signal is associated with a particular control chart. For example, Individual Outside is
associated with, and can only be used with, the Individual chart. This is because the calculation and
control limits used to determine if a sequence of individual values are out of control is specific to the
Individual chart.

Signals Table

After all the desired settings have been defined, the user can select "Save" to commit all the changes, or
"Cancel" to undo any changes that have been made.
Inductive Automation

SPC Quality

514

After a sample definition has been created, samples based on them may appear or be manually added
depending on the Interval setting.
4.2.2.1.3 Sample Entry

Although it is not required, the sample list is used to view samples coming due, due, overdue, waiting for
approval and approved. Based on the color, users can easily see the current state of samples.
From this list, users can select a sample to enter measurements for or create new samples. See the
sample definition section for more information about how to schedule samples or define them to be taken
manually. By selecting a sample and clicking on the Edit Sample button, the sample data can be entered.
Likewise, by clicking on the Add Sample button, a new sample can be added. Depending on the sample
definition, samples can be automatically or manually approved. Once a sample has been approved, it will
appear in the control charts and will be automatically evaluated for an out of control condition. In this
demo, the Unapprove Sample button has been added to demonstrate the ability to correct previously
approved sample data. This can be removed from the screen or allowed based on the user's security
role.

Sam ple List

Once the user has clicked on the Edit Sample or Add Sample button, the sample entry form appears. If a
new sample has been added, the location can be selected. For a location to appear as an option here, it
must first be added to the location list for the desired sample definition with the Ownership setting set to
"Lab" for the lab entry screen or "Test Station" test station entry screen. These ownership tags can be
changed using the designer or additional ownership tags can be added.
The following screen shows the entering of measurements for a value based sample. In this case,
Inductive Automation

SPC Quality

515

viscosity and temperature values. Users also have the ability to enter a product code and reference
number (located in the upper right-hand corner). These can be used when viewing the samples in the
control charts or for analysis beyond control charts.
Because multiple measurements are being entered for each attribute, the attributes appear horizontally
and the measurements vertically. If the sample definition only calls for one measurement, then the
attributes will appear vertically.

Value Sam ple Entry

Below represents entering data for a attribute based sample.

Inductive Automation

SPC Quality

516

Attribute Sam ple Entry

4.2.2.2

SPC Control Charts

This is the SPC Control Chart Menu. Here, the user can click on the menu item to select the
corresponding control chart or click on the Back to Main to return back to the main demo menu.

Inductive Automation

SPC Quality

517

Control Chart Menu

4.2.2.2.1 Control Charts

When a sample definition is created, it will appear as an option in the Stored SPC Settings selection box.

Stored SPC Settings Selection Box

Inductive Automation

SPC Quality

518

Note: When the demo is first installed there is no SPC data. After it has run for 10 minutes or so, the
SQLTag-Line 1 Checkweigher and SQLTag-Line 2 Checkweigher options will have collected a sample
amount of data. If any samples have been entered on the sample entry screens, they will appear as well.
After selecting one of the Stored SPC Settings options, the appropriate control chart will be shown. From
here other options can be selected, which will be discussed later on.
The image below labels the major parts of the control chart. The Date Range Selector is used to select
the date range of samples to view. It defaults to the current period of time, but can be used to select
samples from the past. The table shows the data collected and the calculated values. The calculated
values that are included depends on the kind of control chart being displayed. When the scroll bar at the
bottom of the table is moved to the left, the table, primary chart and secondary chart will all scroll in
unison to previous samples within the selected date range.
For the attribute type of control charts the secondary table will not appear.

Control Chart

Changing what attribute is currently being shown in the control chart is done using the SPC settings panel. To
Inductive Automation

SPC Quality

519

change the attribute, click on the + select to the right of the Attribute label. This will show all of the attributes
defined in the sample definition. In the case of the SQLTag-Line 1 Checkweigher, only one attribute is
available.
Control limits and signals can be selected or hidden using the same method as the attribute with the
exception that more than one control limit or signal can be selected.
The filter by section allows for the limiting of samples that will be shown and included in the calculated values.
At a minimum, at least one location must be specified. This is because data collected from one location could
be completely unrelated or in a different range than another location. If this is not the case, then multiple
locations can be added to the filter.

SPC Settings

The show options allow for the appearance of the control chart to be changed. By removing the Table option,
the table will not appear leaving only the charts and allowing more samples to be viewed at once.

Control Chart Show Options

Inductive Automation

SPC Quality

520

4.2.2.2.2 Analysis

The analysis screen allows for free form analysis of production and quality data. This data can also be
filtered to include only specific criteria. Additionally, comparisons can be made between different factors.
For example, sample count by operator can be analyzed, or even process out of control conditions by
operator by shift. The four icons in the upper right corner are used to select between pie chart, bar chart,
line chart or tabular format.

SPC Analysis Screen

The date range selector at the bottom is used to define the data range that will be included in the analysis.
As you change the start or end dates, only the production runs that are within that range will be included in
the analysis.
Stored Analysis
Start out by creating a new analysis by clicking on the menu of the Stored Settings panel and then
selecting the New menu item. Next type in a name, select Quality for the type and click the OK button.

New Quality Analysis

Filter By
Once an stored analysis has been created or selected, you can change the selections to zero in on the
Inductive Automation

SPC Quality

521

data that is desired. The filter section allows you to limit the data that is included in the analysis. Filters
can be added by clicking on the
icon on the right side of the Filter By section. Within the popup filter
selection window, scroll down to the Shift option and click the icon. Notice the shifts can now be
selected. Clicking on 1 for first shift will add the Shift = 1 causing the analysis results to included quality
data for only for first shift. Any combination on filters can be added and the corresponding results will be
shown.

Filter By Options

The list of available filters change based on the date range. For example, if no samples were taken during
the second shift, then a 2 will not appear as an available option under shift.
Filter By items can be removed by clicking on the

located to the left of the filter name.

Compare By
Breaking up information into groups is more meaningful than just seeing a total for a given date range. For
example, knowing the total sample count for a given data range does not provide actionable information
that can be used to improve quality. Now, comparing by the sample count for each person entering
sample data may provide meaningful and actionable data that can be used to determine staffing
requirements.
Additional Compare By items can be added by clicking on the
icon on the right side of the Compare
By section. Within the popup Compare By selection window, click on the item that you want to compare
analysis results between.

Inductive Automation

SPC Quality

522

Com pare By Selections

Compare By items can be removed by clicking on the

located to the left of the name.

Data Points
Data points are the individual pieces of information that will be present in the analysis. For example,
sample count or approved count are just two of the many available data points. To add a data point, click
on the
icon on the right side of the Data Points section. Within the popup Data Point selection
window, click on the data point item to include in the analysis.

Data Point Selections

Data Points can be removed by clicking on the

located to the left of the name.

The pie chart will only show one data point. For this reason if more than one data point is selected the bar
chart, line chart or table must be selected to see all the selected data points.

Inductive Automation

SPC Quality

523

Drill Down
The drill down feature simplifies the compare by and filter selections. Click on a chart series to display the
available drill down options. As shown in Drill Down Example 1 below, clicking on the Line 1 Quality pie
segment will show a popup menu of drill down options. If the Shift option is selected, then the analysis
filters will show the information by Shift and the Filter By and the Compare By sections add Shift. The
result is shown in Drill Down Example 2. Again, by clicking on the pie segment and selecting another
drill down option, the Filter By and Compare By selections will change to show the appropriate information
. This can be continued any number of times.

Drill Dow n Exam ple 1

Drill Dow n Exam ple 2

Inductive Automation

SPC Quality

4.3

524

Configuration

There are two areas to configure the SPC Quality module. The first area is in the Ignition Gateway and
affects all SPC Modules.
The second is in the Ignition Designer and is used to configure production models, user screens and the
like. These settings are saved in an Ignition project and can be backed up and restored using the built-in
project backup and restore features of Ignition.

4.3.1

MES Module Configuration

The SPC Quality module is just one of the SPC (Statistical Process Control) modules that has settings
which can be set.
4.3.1.1

Datasource Settings

OEE, downtime and schedule data is stored in databases external to Ignition. These database(s) are
setup in the gateway configuration section by selecting the Databases> Connections section from the
left-hand configuration menu in Ignition. See the Ignition documentation for more information on setting up
a database connection.
Below shows a typical database connection that is required for the OEE, Downtime and Scheduling
module.

Sam ple Database Connection

To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules.
If more than one database connection exists, then the desired database connection can be selected to be
used by the MES modules as shown below.

Inductive Automation

SPC Quality

525

MES Module Settings Page

Runtime Database
The runtime database is where production and downtime data is stored during a production run. During a
production run, data is logged every minute or partial minute if a downtime event occurs, so a larger
amount of data is stored in the runtime database.
Data Retention Duration
This setting specifies the number of days to retain the data in the runtime database after a production run
has completed. The default setting is 30 days, This allows for viewing current and past production run
information, down to the minute, for the past 30 days.
Analysis Database
The analysis database is where summarized production and downtime data is saved. For single
production site installations, this can be the set to the same database as the runtime database. For multiproduction site installations, all sites must set the analysis database to the same database to allow for
enterprise analysis and reporting.
Analysis Database (Auxiliary)
The MES Modules will mirror the hsitorical analysis data that is written to the local analysis database to
this database. For single site implementations, set this to "-none-". For multi-site implementations, set
this to the datasource for the common remote enterprise database.
Analysis Query Cache Duration
This setting represents the number of seconds to cache analysis results.

4.3.2

Production Model Configuration

A production model defines your manufacturing or process in tree view form. It provides an organized way
to easily configure, control and analyze your facility. It starts with your enterprise, which represents your
company, and continues down to the site (physical location), area, location, line and cells.
Inductive Automation

SPC Quality

4.3.2.1

526

Production Module

The production model is configured within the Ignition designer and is accessed by selecting the
"Production" folder in the project browser. From here, your enterprise, site, area(s), line(s) and cell(s) can
be added, renamed and deleted.

Production Model Tree

4.3.2.1.1 Enterprise Configuration

Adding an Enterprise
To add your enterprise, right-click on the "Production" folder in the project browser and select the New
Production Item > New Production Enterprise menu item. An enterprise named "New Enterprise" will
be added to the "Production" folder.
Renaming an Enterprise
To rename it to the name of your enterprise, right-click on it and select Rename, then enter the new
name.

Enterprise Nam e

Deleting an Enterprise
To remove an existing enterprise, right-click on the enterprise item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production enterprise. Please note
Inductive Automation

SPC Quality

527

that the site, area(s), line(s) and cell(s) underneath the enterprise will also be permanently removed.

Inductive Automation

SPC Quality

528

General Enterprise Settings

These settings are accessed by selecting the enterprise item contained in the"Production" folder in the
project browser and then selecting the "General" tab as shown below.

Enterprise General Settings

Enabled

By default, added enterprises are enabled. It can be disabled by un-checking the

Enabled setting and saving the project. This will stop the OEE, downtime and
scheduling module from executing the enterprise, the site and all area(s), line(s) and
cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Enterprise Quality Settings

These settings are accessed by selecting the enterprise item contained in the"Production" folder in the
project browser and then selecting the "Quality" tab as shown below.

Inductive Automation

SPC Quality

529

Enterprise Quality Settings

From here, the Control Limits, Out of Control Signals, and Sample Intervals can be defined. This definition
will determine what options will appear for every sample that is defined. For example, if the Histogram
LCL control limit is not defined on the Enterprise page, it will not be an available option when selecting
control limits on the Sample Definition page. Default control limits, out of control signals, and sample
intervals will be present and these may be edited or deleted. New limits, signals or intervals can also be
added.
Adding a Control Limit, Out of Control Signal, or Sample Interval
To add a limit, signal, or interval, right-click on the table and select New. After filling in the necessary
fields, select OK.
Editing a Control Limit, Out of Control Signal, or Sample Interval
To edit a limit, signal, or interval, select the item to be edited, right-click, and select Edit from the dropdown menu. After making the desired changes, select OK.
Deleting a Control Limit, Out of Control Signal, or Sample Interval
To delete a limit, signal, or interval, select the item to be deleted, right-click, and select Delete from the
drop-down menu.
For more information, view the pages on Control Limits, Out of Control Signals, and Sample Intervals.
4.3.2.1.2 Site Configuration

Adding a Site
To add your site, right-click on your enterprise folder in the project browser and select the New
Production Item > New Production Site menu item. A site named "New Site" will be added to the
enterprise folder.
Inductive Automation

SPC Quality

530

Renaming a Site
To rename it to the name representing the site's physical location, right-click on it and select Rename,
then enter the new name.
Deleting a Site
To remove an existing site, right-click on the site item and select the Delete menu item. A window will
appear confirming that you permanently want to delete the production site. Please note that the area(s),
line(s) and cell(s) underneath the site will also be permanently removed.

New Site

General Site Settings

These settings are accessed by selecting the site item contained in the enterprise folder in the project
browser, and then selecting the "General" tab.
Enabled

By default, added sites are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the site and all area(s), line(s) and cell(s) that are underneath
it.

Description

This is an optional description and is just for your reference.

Shift 1:
Default Enabled If checked, shift 1 will be included during scheduling. If not checked, shift 1 will be
Default Start
Time

scheduled around.
The time of day that first shift starts. The first shift ends at the start of second shift.

Shift 2:
Default Enabled If checked, shift 2 will be included during scheduling. If not checked, shift 2 will be
Default Start
Time

scheduled around.
The time of day that second shift starts. The second shift ends at the start of third
shift.

Shift 3:
Default Enabled If checked, shift 3 will be included during scheduling. If not checked, shift 3 will be
Default Start
Time

scheduled around.
The time of day that third shift starts. The third shift ends at the start of first shift.

Note: The shift enabled and shift start times are the default for your production site and can be overridden
by the production area and/or production line.

Inductive Automation

SPC Quality

531

4.3.2.1.3 Area Configuration

Adding an Area
To add a production area, right-click on your site folder in the project browser and select the New
Production Item > New Production Area menu item. An area named "New Area" will be added to the
site folder. Multiple production areas can be added to your production site. Each area can represent a
physical or logical production area within your production site. Some examples of production areas are:
packaging, cracking, filtration, fabrication, etc.
Renaming an Area
To rename it to the name representing the production area, right-click on it and select Rename, then
enter the new name.
Deleting an Area
To remove an existing production area, right-click on the area item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production area. Please note that
the line(s) and cell(s) underneath the area will also be permanently removed.

New Area

Area General Settings

These settings are accessed by selecting the desired area item contained in the site folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added areas are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the area and all line(s) and cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Shift 1
Default Enabled If checked, shift 1 will be included during scheduling. If not checked, shift 1 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the site, select the
"Inherit From Parent" option.
The time of day that first shift starts. The first shift ends at the start of second shift. To
inherit the time of day that first shift starts setting from the site, select the "Inherit
From Parent" option.

Shift 2
Default Enabled If checked, shift 2 will be included during scheduling. If not checked, shift 2 will be

Default Start
Time

Inductive Automation

scheduled around. To inherit the shift enabled from the from the site, select the
"Inherit From Parent" option.
The time of day that second shift starts. The second shift ends at the start of third
shift. To inherit the time of day that second shift starts setting from the site, select the
"Inherit From Parent" option.

SPC Quality

532

Shift 3
Default Enabled If checked, shift 3 will be included during scheduling. If not checked, shift 3 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the site, select the
"Inherit From Parent" option.
The time of day that third shift starts. The third shift ends at the start of first shift. To
inherit the time of day that third shift starts setting from the site, select the "Inherit
From Parent" option.

Note: The shift start times are the default for your production site and can be overridden by the production
area and/or production line.
4.3.2.1.4 Line Configuration

Adding a Line
To add a production line, right-click on an area folder in the project browser and select the New
Production Item > New Production Line menu item. A line named "New Line" will be added to the area
folder. Multiple production lines can be added to a production area.
Renaming a Line
To rename it to the name representing the production line, right-click on it and select Rename, then enter
the new name.
Deleting a Line
To remove an existing production line, right-click on the line item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production line. Please note that
the cell(s) underneath the line will also be permanently removed.

New Line

Line General Settings

These settings are accessed by selecting the desired line item contained in the area folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added lines are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the line and cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Shift 1
Default Enabled If checked, shift 1 will be included during scheduling. If not checked, shift 1 will be

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
Inductive Automation

SPC Quality
Default Start
Time

533

The time of day that first shift starts. The first shift ends at the start of second shift. To
inherit the time of day that first shift starts setting from the area, select the "Inherit
From Parent" option.

Shift 2
Default Enabled If checked, shift 2 will be included during scheduling. If not checked, shift 2 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that second shift starts. The second shift ends at the start of third
shift. To inherit the time of day that second shift starts setting from the area, select
the "Inherit From Parent" option.

Shift 3
Default Enabled If checked, shift 3 will be included during scheduling. If not checked, shift 3 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that third shift starts. The third shift ends at the start of first shift. To
inherit the time of day that third shift starts setting from the area, select the "Inherit
From Parent" option.

4.3.2.1.5 Location Configuration

Adding a Location
To add a production location, right-click on an area or line folder in the project browser and select the
New Production Item > New Production Location menu item. A location named "New Location" will be
added to the area or line folder. Multiple production locations can be added to a production area or line.
Renaming a Location
To rename it to the name representing the production location, right-click on it and select Rename, then
enter the new name.
Deleting a Location
To remove an existing production location, right-click on the location item and select the Delete menu
item. A window will appear confirming that you permanently want to delete the production location. Please
note that the line(s) and cell(s) underneath the location will also be permanently removed.

New Location

Location General Settings

These settings are accessed by selecting the desired location item contained in the area or line folder in
the project browser and then selecting the "General" tab.
Inductive Automation

SPC Quality

534

Enabled

By default, added lines are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the line and cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Shift 1
Default Enabled If checked, shift 1 will be included during scheduling. If not checked, shift 1 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that first shift starts. The first shift ends at the start of second shift. To
inherit the time of day that first shift starts setting from the area, select the "Inherit
From Parent" option.

Shift 2
Default Enabled If checked, shift 2 will be included during scheduling. If not checked, shift 2 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that second shift starts. The second shift ends at the start of third
shift. To inherit the time of day that second shift starts setting from the area, select
the "Inherit From Parent" option.

Shift 3
Default Enabled If checked, shift 3 will be included during scheduling. If not checked, shift 3 will be

Default Start
Time

scheduled around. To inherit the shift enabled from the from the area, select the
"Inherit From Parent" option.
The time of day that third shift starts. The third shift ends at the start of first shift. To
inherit the time of day that third shift starts setting from the area, select the "Inherit
From Parent" option.

Additional Factors Additional Factors are user defined data points that are logged along with the

production and downtime information. Once they are logged, they can be shown in
charts, tables and reports. Additionally, other analysis can be done by filtering and/or
setting up comparisons by their values.
Any value that can be read from an Ignition SQLTag can be added as a additional factor. This
includes, values from barcode readers, databases, calculations, PLCs, or values derived from
scripts, etc.
Example: An additional factor named cardboard manufacturer can be added. The operator can select
the manufacturer that provided the cardboard or it can be obtained from some other source. Now,
SPC results can be shown for each cardboard manufacturer. This can identify problems with raw
material that directly affect quality.
Below is an example of an operator additional factor. The operators name will be logged along with the
production and downtime data. By doing so, OEE and downtime information can be filtered and
grouped by the operator name.

Inductive Automation

SPC Quality

535

Additional Factor List

Adding an Additional Factor

To add an additional factor, right-click anywhere on the additional factor table and select the New menu
item. A dialog box will appear to allow entry of a new additional factor as shown below.

Additional Factor Settings

Factor Name
The required name of the additional factor is used to reference one additional factor from another. You
can have any number of additional factors, but user usability will be hindered if too many are added. This
is because the additional factors are added to user menus and if too many are added, the menus can
become too long and confuse the end user.
The name given to an additional factor should be meaningful to the end user. Again, this is because
additional factors appear in menus allowing the end user to filter and group analysis and report data by
them.
Factor Description
Inductive Automation

SPC Quality

536

The optional description is just for reference or to keep internal notes about the additional factor.
Factor SQLTag
The required SQLTag is the source of the data value that will be logged. It is an Ignition SQLTag and the
values can come from a PLC, a database query, other device in the field such as a barcode reader,
expression, user input, or script. This opens the door to mesh any type of outside data into the MES
module analysis and reporting.
Any type (format) of data that can be stored in an SQLTag can be logged. If SQLTag value is a string,
then the end user can filter and group by the additional factor. If the SQLTag is a number, the option to
filter and group by the additional factor will not be shown to the end user.
The SQLTag can be manually typed or pasted into the Factor SQLTag edit box. Optionally, clicking on
the

icon will display a browser where a SQLTag can be selected.

Editing an Additional Factor

To edit an existing additional factor, right-click on the desired entry in the additional factor table and select
the Edit menu item. A dialog box similar to the add dialog box will appear, allowing editing of the additional
factor.
Deleting an Additional Factor
To remove an existing additional factor entry, right-click on the desired entry in the additional factor table
and select the Delete menu item. A window will appear confirming that you want to remove the additional
factor. The additional factor will no longer be logged. However, any production runs that occurred before
the additional factor was deleted, will still show in the analysis and reporting.
Location Quality Settings
These settings can be found in the Location folder under the "Quality" tab. The SQLTag Sample
Collectors allow for the automatic collection of sample data. For more information, see Tag Sample
Collectors.

Location Quality Settings Screen

See SQLTag Sample Collectors for more information.

4.3.3

Control Limits

Inductive Automation

SPC Quality
4.3.3.1

537

Overview

Control limits are upper (UCL) and lower (LCL) values that are calculated from the data that is gathered
from a process. These limits, typically shown as horizontal lines on the control charts, reflect the past
performance of that process. For the p and u Charts, the control limits can vary for each sample
depending on the number of items inspected for each sample. See the SPC Charts in the Introduction
sections for more information. In the SPC Quality Module, these limits can be calculated automatically, or
entered manually. In the SPC module, control limits can be either calculated or can act as specification
limits. Specification limits are requirements made by the company, not a reflection of the process itself.
There are different control limits types for each type of control chart. For example, the XBar only supports
XBar UCL, XBar LCL and XBar Other control limits types and cannot be calculated or shown for any other
control chart besides the XBar control chart.
The control limits are defined by the enterprise and can be added, edited or deleted on the Enterprise
page in the designer under the "Quality" tab. By default, the standard control limits are added when a new
Enterprise Production Item is added.
4.3.3.2

Default Control Limits

When a new Enterprise Production Item is added, the following control limits are added:
c LCL
c UCL
Histogram LCL
Histogram UCL
Individual LCL
Individual UCL
Median LCL
Median UCL
MR LCL
MR UCL
np LCL
np UCL
p LCL
p UCL
Range LCL
Range UCL
StdDev LCL
StdDev UCL
StdDev XBar LCL
StdDev XBar UCL
u LCL
uUCL
XBar LCL
XBar LSL
XBar UCL
XBar USL
4.3.3.3

Add Control Limits

To add a control limit, right-click the Control Limits table and select New from the drop-down menu. A
window will appear with several fields to be completed, including the name and kind of the control limit, as
well as the scripting necessary to use the control limit.
Inductive Automation

SPC Quality

538

Adding a Control Lim it

Name
This is the required unique name of the control limit as it will appear in selection lists and control charts. It
is better to keep this short in length so that it will fit better on the control charts.
Kind
Each type of control chart has control limit kinds that it works with. If a control limit will be used with a
Individual control chart, then either the Individual LCL (lower control limit), Individual UCL(upper control
limit) or Individual Other control limit kinds must be used.
Available control limits kinds grouped by control chart type:
XBar
XBar UCL
XBar LCL
XBar Other

XBar, Xbar S

XBar Range
Range LCL
Range UCL
Range Other

XBar

Individual
Individual LCL
Individual UCL
Individual Other

Individual

Moving Range
MR LCL
MR UCL
MR Other

Individual, Median

Standard Deviation
XBar S
Standard Deviation LCL
Standard Deviation UCL
Standard Deviation Other
Median
Median LCL
Median UCL

Median

Inductive Automation

SPC Quality

539

Median Other
p

p Chart
p LCL
p UCL
p Other

np

np Chart
np LCL
np UCL
np Other

u Chart
u LCL
u UCL
u Other

c Chart
c LCL
c UCL
c Other

Histogram
Histogram LCL
Histogram UCL
Histogram Other

Histogram

Calculation Script
Because control limit calculations can vary, the SPC module uses scripting. This allows the user to
override the default calculation of a control limit or add new control limits that the SPC module may not
provide by default. Additionally, they can be removed, cleaning up selection lists of control limits that may
never be used.
When a user or script function is used to initiate a control limit to be calculated, the script in the
associated control limit is executed. An event object is passed into the script that contains the information
and data to calculate the new control limit value. We will introduce this event here, but see Control Limit
Event object for more information.
In the example below, any lines that start with the pound (#) character are comments and are ignored
when the script is executed.
The event.getData() on line 8, returns the samples that will be used to calculate the new control limit. It is
a data set (see Ignition DataSet in scripting for more information) and contains a row of data for each
sample. Each sample row includes measurement values, calculated values (such as xBar, standard
deviation, etc), sample date and time. For the p and u charts where the control limits can vary by sample,
this data set includes columns to which the the newly calculated control limit for each sample can be
saved.
The ds.getColumnIndex on lines 11 and 12, returns the column number of the "XBar" and "Range"
columns. This is done for speed reasons because it is faster to reference the column by number instead
of finding the column by name.
From line 19 to 21, each sample row in the data set is cycled through. This is done to total the xBar and
range values. The ds.getValueAt() function returns the value in the data set for the specified row and
column.
Inductive Automation

SPC Quality

540

Line 24 calculates the average of the xBar values, also known as x double bar (XDBar).
Line 25 calculates the average of the range values, also known as range bar (RBar).
The event.getSampleSize() in line 28, returns the number of measurements per sample. This will be used
to determine which a2 value to use from the array in line 5. The a2 is a factor to calculate the 3 sigma or 3
times standard deviation value and changes based on the number of measurements in each sample.
Lines 31 through 34 lookup the a2 value that is going to used to calculate the new control limit value. A
quick range check is done to prevent reading a value that is outside of the array limits.
Line 37 calculates the new UCL value.
And finally, the value is saved to pass back the new control limit value in line 40.
Default XBar UCL control limit calculation script:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

#XBar UCL Calculation

#Define the A2 factors array.
#The A2 factors correspond to the sample size which starts at 2.
#This is why element 0 and 1 of the array are 0.
a2 = [0.0, 0.0, 1.880, 1.023, 0.729, 0.577, 0.483, 0.419, 0.373, 0.337, 0.308, 0.285, 0.266, 0.249, 0.
#Get the SPC data that the XBar UCL will be calculated for
ds = event.getData()
#Get the columnn indexes within the SPC data
xBarColNdx = ds.getColumnIndex("XBar")
rangeColNdx = ds.getColumnIndex("Range")
#Initialize xBar and range sums that are need to calculate average xBar and range.
xBarSum = 0.0
rSum = 0.0
#Cycle through each row and add to the sums
for row in range(ds.rowCount):
xBarSum = xBarSum + ds.getValueAt(row, xBarColNdx)
rSum = rSum + ds.getValueAt(row, rangeColNdx)
#Calculate the average xBar and range
xDBar = xBarSum / ds.rowCount
rBar = rSum / ds.rowCount
#Get the sample size.
sampleSize = event.getSampleSize()
#Lookup the A2 value
if sampleSize < len(a2):
a2Value = a2[sampleSize]
else:
a2Value = a2[len(a2) - 1]
#Calculate the xBar UCL
ucl = xDBar + a2Value * rBar
#Return the new xBar UCL back to the SPC module
event.setControlLimitValue(ucl)

Looking at the default control limit calculations along with the Scripting section of this manual and the
Inductive Automation

SPC Quality

541

Scripting section in the Ignition manual is the best method to learn all the possibilities of calculating control
limits.
4.3.3.4

Edit Control Limits

To edit a control limit, right-click the Control Limits table and select Edit from the drop-down menu. A
window will appear identical to the window used to add control limits. Once the desired fields have been
edited, select OK.
For more information see Add Control Limit section.
4.3.3.5

Delete Control Limits

To delete a control limit, select the item to be deleted. After selecting, right-click the item and select
Delete from the drop-down menu. A window will appear confirming that you permanently want to delete
the control limit.
4.3.3.6

Import/Export

To export control limit entries, right-click anywhere on the table containing control limit entries and select
the Export menu item. A dialog box will appear to allow selection of an existing file or the entry of a name
for the new file to which the control limit entries are saved. If a file extension is not entered, then the
default .csv will be used.
The first line of the file must contain at least the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing multiple control limit entries. The lines in the example shown below have been shortened.

Inductive Automation

SPC Quality

542

To import downtime entries, right-click anywhere on the control limit table and select the Import menu
item. A dialog box will appear to allow selection of a comma separated values (csv) formatted file.

4.3.4

Out of Control Signals

4.3.4.1

Overview

Out-of-control signals occur in a variety of situations, but all the signals indicate a change in the process
where it is considered to be abnormal, or out of control. Some signals include: six points in a row that are
increasing or decreasing, eight points in a row that are farther than one standard deviation away from the
centerline, or fourteen points in a row that are alternating up and down. When used properly, these
signals can identify important changes that can help to improve or maintain the process.
Signals can be configured so that they are evaluated every time new sample data is recorded. This allows
for quick and automatic detection of out of control conditions. Once an out of control condition is
automatically detected, Ignition provides a variety of actions that can be performed, such as standard
alerting, communications, logging and more.
Inductive Automation

SPC Quality

543

For automatic signal evaluation to be enabled, the Look Back Period must be set to something other than
"No Auto Evaluation", a valid look back duration must be set and the signal must be selected for the desired
sample definitions.
Out of Control Signals can be added, edited or deleted on the Enterprise page in the designer under the
"Quality" tab.
4.3.4.2

Default Signals

When a new Enterprise Production Item is added, the following control limits are added:
Individual Outside
Out of Limits
Outside Limits
4.3.4.3

Add Signals

To add an out of control signal, right-click the Out of Control Signals table and select New from the dropdown menu. A window will appear with several fields to be completed, including the signal name, kind,
calculation script, lookback period, lookback duration, chart point color and chart point shape.

Adding a Signal

Signal Name
This is the required unique name of the signal as it will appear in selection lists and control charts. It is
better to keep this short in length so that it will fit better on the control charts.
Kind
Each type of control chart has signal kinds that it works with. If a signal will be used with a Individual
control chart, then the Individual signal kind must be used.
Available control limits kinds grouped by control chart type:
XBar
Range
Inductive Automation

SPC Quality

544

Individual
MR
Standard Deviation
Median
p
np
u
c

Calculation Script
Because signal calculations can vary, the SPC module uses scripting. This allows the user to override
the default calculation of a signal or adding new signals that the SPC module may not provide by default.
Additionally, they can be removed, cleaning up selection lists of signals that may never be used.
Signals are evaluated when viewing them on control charts or when new sample data is recorded. When
either of these trigger the signals to be calculated, the script in the associated signal is executed. An
event object is passed into the script that contains the information and data to calculate the signal state
values. We will introduce this event here but see Signal Event object for more information.
In the example below, any lines that start with the pound (#) character are comments and are ignored
when the script is executed.
Line 2 initializes a variable used to track how many consecutive calculated values (like the x bar value)
are above the control line (like the x double bar value).
The event.getData() on line 5, returns the samples that will be used to calculate the signal state values. It
is a data set (see Ignition DataSet in scripting for more information) and contains a row of data for each
sample. Each sample row includes measurement values, calculated values (such as xBar, standard
deviation, etc), sample date and time and control limits. There is also a column named the sample as the
signal to save the signal state value. By setting the value of this column to a zero (0), the sample is in
control for this signal, and by setting the value of this column to a one (1), the sample is out of control.
The ds.getColumnIndex on lines 8 through 10, returns the column number of the "XBar", "XDBar" and
signal result columns. This is done for speed reasons because it is faster to reference the column by
number instead of finding the column by name.
Starting with line 13, each sample row in the data set is cycled through.
Line 16 reads the calculated value that in this case is the xBar value.
Line 17 reads the average of the calculated values, which in this case is the xDBar value.
In line 20, a test is done for the xBar value being greater than the xDBar. If it is, further checking is done in
lines 22 through 38. If it is not, then the consecutive count variable is reset and the signal state value is
set to 0 for the sample in lines 42 and 43.
Line 22 adds to the consecutive count variable before checking if the threshold of 8 has been exceeded.
Line 25 checks if the consecutive count threshold has been exceed. If not, the signal state value for the
sample is set to 0 and the consecutive count variable is left at its current value.
Line 28 checks if the consecutive count just exceeded the threshold. If it just did, the signal state values
for the previous 8 samples are set to 1. This flags the current sample and the previous 7 samples as out
Inductive Automation

SPC Quality

545

of control.
The else statement in line 35 is a check that occurs if more than 8 consecutive xBar values exceed the
xBar value. It sets the signal state value to 1 and leaves the consecutive count variable at its current
value.
Default 8 consecutive points above control limit signal calculation script:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

#8 Consecutive points above control line signal calculation

consecutiveCount = 0
#Get the SPC data that the signal will be calculated for
ds = event.getData()
#Get the columnn indexes within the SPC data
xBarColNdx = ds.getColumnIndex("XBar")
xDBarColNdx = ds.getColumnIndex("XDBar")
resultColNdx = ds.getColumnIndex("XBar 8 Above Control Line")
#Cycle through each row and check signal
for row in range(ds.rowCount):
#Get the values to compare
xBar = ds.getValueAt(row, xBarColNdx)
xDBar = ds.getValueAt(row, xDBarColNdx)
#Test if the x bar value is above x double bar value
if xBar > xDBar:
#Add to the consecutive count
consecutiveCount = consecutiveCount + 1
#Test if less than 8 consecutive x bar values are above x double bar
if consecutiveCount < 8:
#Write a zero to the result column, meaning we are in control
ds.setValueAt(row, resultColNdx, 0)
elif consecutiveCount == 8:
#Now 8 consecutive x bar values are above the x double bar
#Write a 1 into the last 8 row because, they are all out of control
ndx = row
while ndx > 0 and ndx > row - 8:
ds.setValueAt(ndx, resultColNdx, 1)
ndx = ndx - 1
else:
#Over 8 consecutive x bar values are above x double bar
#Continue writing a 1 into the result because this row is still out of control
ds.setValueAt(row, resultColNdx, 1)
else:
#x bar value is below, reset the consecutive count
#and write a zero to the result column, meaning we are in control
consecutiveCount = 0
ds.setValueAt(row, resultColNdx, 0)

Look Back Period

This property defines the time units of the Look Back Duration property.
No Auto Evaluation
Seconds
Minutes
Hours
Inductive Automation

Disable automatic signal evaluation after new sample

data is recorded.

SPC Quality

546

Days
Months

Look Back Duration

When automatic signal evaluation is used, this property, along with the Look Back Period property,
defines the time range of samples to pass to the calculation script. The calculation script can then cycle
through the range of samples to find out of control conditions.
Chart Point Color
For samples that are out of control, this is the color to display the sample value on the control charts.
Chart Point Shape
For samples that are out of control, this is the shape to display for sample value on the control charts.
Looking at the default signal calculations along with the Scripting section of this manual and the Scripting
section in the Ignition manual is the best method to learn all the possibilities of calculating signals.
View the section on Scripting for more information.
4.3.4.4

Edit Signals

To edit an out of control signal, right-click the Out of Control Limits table and select Edit from the dropdown menu. A window will appear identical to the window used to add out of control limits. Once the
desired fields have been edited, select OK.
For more information see Add Signals section.
4.3.4.5

Delete Signals

To delete an out of control signal, select the item to be deleted. After selecting, right-click the item and
select Delete from the drop-down menu. A window will appear confirming that you permanently want to
delete the out of control signal.
4.3.4.6

Import/Export

To export signal entries, right-click anywhere on the table containing signal entries and select the Export
menu item. A dialog box will appear to allow for the selection of an existing file or the entry of a name for
the new file to which the out of control signal entries are saved. If a file extension is not entered, then the
default .csv will be used.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing multiple signal entries. The lines in the example shown below have been shortened.

Inductive Automation

SPC Quality

4.3.5

Sample Intervals

4.3.5.1

Overview

547

Samples can always be taken manually, but the SPC module supports scheduling samples to be taken
manually and automatically taking samples.
Sample Intervals are used to define the amount of time or number of readings that pass between
samples. For example, the interval may be a timed interval that occurs every three minutes, every 100
readings, or samples can be taken continuously. These options will be available when defining a sample
on the Sample Definition page when adding or editing a location. They also are used by Tag Sample
Collectors.
Sample Intervals can be added, edited or deleted on the Enterprise page of the designer under the
"Quality" tab.
4.3.5.2

Default Intervals

When a new Enterprise Production Item is added, the following intervals are added:
Every Value Change
Every x Value Change
Manual
Once at Production End
Once at Production Start
Shift Change
Timed Interval (Days)
Timed Interval (Hours)
Timed Interval (Minutes)
Timed Interval (Seconds)
4.3.5.3

Add Intervals

To add a sample interval, right-click the Sample Intervals table and select New from the drop-down menu.
A window will appear with several fields to be completed, including the name of the sample interval, as
well as the scripting necessary to use the sample interval.

Name
This is the required unique name of the interval as it will appear in selection lists.
Inductive Automation

SPC Quality

548

Script
Because the default intervals may not be exactly what you are looking for, the SPC module uses
scripting. This allows the user to override the default calculation of an interval or adding new intervals that
the SPC module may not provide by default. Additionally, they can be removed, cleaning up selection lists
of intervals that may never be used.
In the sample definition, an interval can be selected and will define when new samples are scheduled.
These scheduled samples require manual entry of measurements.
In the Tag Sample Collector configuration, an interval is used to define when to automatically add new
samples.
In the example below, any lines that start with the pound (#) character are comments and are ignored
when the script is executed.
Line 2 will allow us to use the Calendar object to do math with date values. See the Ignition
documentation for more information.
Line 5 returns the seconds since the last time a sample was scheduled. There is a wealth of information
in the event object that can be used to determine if a sample should be scheduled or taken. See Interval
Line 8 returns the duration to use. In this case it is in minutes
Line 9 returns the coming due minutes. It is going to be used to schedule a sample prior to the time it is
due, so that it will show in the sample list component prior to the time it is actually due. For automatic Tag
Sample Collectors, the coming due will be 0 and the sample will be recorded and measurements
collected when the sample is created.
Line 12 does the actual checks to determine if a new sample should be scheduled. If secSinceLastSample
equals None, then it means a sample has not been scheduled for the sample definition and location that
is being checked. In this case, a new sample should be created.
Lines 15 through 17 calculate the scheduled start time for the sample. This is the time that the sample will
appear in the sample list component and set the Sample Coming Due tag associated with the production
location.
Line 20 sets the create sample flag that tells the SPC module to create a new sample after executing this
script. This can be done through script functions specifically for creating samples, but this simplifies the
task of doing so down to one line of script.
Time Interval (Minutes) script:
1
2
3
4
5
6
7
8
9
10
11
12
13

#Time Interval (Minutes)

from java.util import Calendar
#Get the last time a sample was scheduled
secSinceLastSample = event.getSecSinceLastSampleScheduled()
#Calculate the interval in seconds
intervalSec = event.getInterval() * 60
comingDueSeconds = event.getComingDueMin() * 60
#If a sample has not been scheduled or intervalSec has expired, schedule a new sample
if secSinceLastSample == None or secSinceLastSample >= intervalSec - comingDueSeconds:
Inductive Automation

SPC Quality
14
15
16
17
18
19
20

4.3.5.4

549

#Schedule next sample to start now + coming due minutes

cal = Calendar.getInstance()
cal.add(Calendar.SECOND, int(comingDueSeconds))
event.setScheduleStart(cal.getTime())
#Create new sample - no values are recorded
event.setCreateSample(1)

Edit Intervals

To edit a sample interval, right-click the Sample Intervals table and select Edit from the drop-down menu.
A window will appear identical to the window used to add sample intervals. Once the desired fields have
been edited, select OK.
4.3.5.5

Delete Intervals

To delete a sample interval, select the item to be deleted. After selecting, right-click the item and select
Delete from the drop-down menu. A window will appear confirming that you permanently want to delete
the sample interval.
4.3.5.6

Import/Export

To export interval entries, right-click anywhere on the table containing interval entries and select the
Export menu item. A dialog box will appear to allow selection of an existing file or the entry of a name for
the new file to which the interval entries are saved. If a file extension is not entered, then the default .csv
will be used.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing multiple interval entries. The lines in the example shown below have been shortened.

4.3.6

SQLTag Sample Collectors

4.3.6.1

Overview

Tag Sample Collectors are used to automatically collect measurement data from an Ignition tag and
create samples with the collected measurement data. When configuring, the selected interval defines
how often to create a new sample. For example, on every 100th value change of a checkweigher value,
create a new sample and record the current value. Or, every 10 minutes while a process is running,
create a sample and record the current temperature.
The measurement data can come from a variety of sources including any OPC connected device, values
from external databases, manual entries, etc.
Inductive Automation

SPC Quality

550

Any samples that are automatically created and recorded by a Tag Sample Collector are automatically
approved and will appear in the control charts. By setting the Auto Refresh property of either the SPC
Selector or SPC Controller components, new samples will appear in the control charts in real time as
they are created. In addition, the appropriate events found on the Advanced tab for the production location
will be executed.
Tag Sample Collectors can be added, edited or deleted on the Location page of the designer under the
"Quality" tab.
4.3.6.2

Add Sample Collectors

To add a Tag Sample Collector, right-click the Tag Sample Collector table and select New from the dropdown menu. A window will appear with several fields to be completed, including the name of the tag
sample collector, as well as the tag path and other properties required.

Add SQL Tag Sam ple Collector

Enabled
Tag Sample Collectors enabled property provides a method of stopping the automatic collection of
measurements and creation of samples. Additionally, any tags associated with this property can be
changed to start and stop automatic collection. See Quality OPC Values for more information.
Inductive Automation

SPC Quality

551

Name
This is the required unique name of the Tag Sample Collector as it will appear, with "SQLTag-" pre
pended to it, in selection lists. Behind the scenes, a sample definition is created using this sample name.
Sample definitions created for the purpose of Tag Sample Collectors will not appear in the definition
management and manual sample entry client screens.
SQLTag Path
This is the SQLTag path from which measurement values will be read.
Interval Type
The interval options that can be selected here match those defined in the Intervals list on the Enterprise
quality tab. Only intervals that have script will be included as options for Tag Sample Collectors. The
reason for this is that manual intervals, which are the those without script, will never be created and do
not apply to automatic collection of measurements.
Interval
The interval to collect data and create new samples. The units of this interval are defined by the interval
type and can be minutes, days, every x value read, etc.
Control Limits
The control limits that are checked will be calculated for this Tag Sample Collector during signal
evaluations. Available control limit options are defined in the Control Limits list on the Enterprise quality
tab. It is important to include control limits that a signal depends on or the signal will not be evaluated
correctly.
Signals
The signals that are checked will be evaluated every time a new sample is recorded by the Tag Sample
Collector. Available signal options are defined in the Signals list on the Enterprise quality tab.
4.3.6.3

Edit Sample Collectors

To edit a tag sample collectors, right-click the Tag Sample Collector table and select Edit from the dropdown menu. A window will appear identical to the window used to add tag sample collector. Once the
desired fields have been edited, select OK.
4.3.6.4

Delete Sample Collectors

To delete a tag sample collector, select the item to be deleted. After selecting, right-click the item and
select Delete from the drop-down menu. A window will appear confirming that you permanently want to
delete the tag sample collector.
4.3.6.5

Import/Export

To export tag sample collector entries, right-click anywhere on the table containing tag sample collector
entries and select the Export menu item. A dialog box will appear to allow selection of an existing file or
the entry of a name for the new file to which the collector entries are saved.. If a file extension is not
entered, then the default .csv will be used.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
showing multiple tag sample collector entries. The lines in the example shown below have been
shortened.

Inductive Automation

SPC Quality

4.4

552

Component Reference

This section is a reference for all of the components that come with the SPC Module.

4.4.1

Quality Components

Quality Com ponents

4.4.1.1

Definition List

Description
A component that provides a list of sample definitions. A sample definition defines the attributes
(measurements), locations, control limits and out of control signals to use for samples. It allows for
adding, editing and deleting samples and works with the Definition Attribute List, Definition Location List,
Definition Control Limit List and Definition Signals List components.
There is no need for SQL queries or scripting to display sample definitions. The SPC Module will send
notifications to each client with a Definition List component being displayed when there is a change to any
sample definitions made by another user. This event-based functionality optimizes updates, reducing
database updates and network bandwidth.

Sam ple Definition List

The Ignition table customizer is used to change the appearance of the table. To access the customizer,
right-click on the Definition List component and select the Cutomizers->Table Customizer menu item.
Using the customizer, you can hide columns, change colors, and change formatting to make the
Definition List appear as desired.

Inductive Automation

SPC Quality

Ignition Table Custom izer

Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

553

SPC Quality

554

Show DisabledWhen set to true, disabled sample definitions will be shown. This provides a method to re-enable
previously disabled sample definitions.

Scripting name
Data Type
Read Only

When set to true, prevents the popup menu from appearing when the user right-clicks on the
Definition List component.

Scripting name
Data Type
Activity

showDisabled
boolean

readOnly
boolean

Number of seconds to wait after user activity before automatic refresh of data.
There
T
is no scripting support for this property.
i
m
e
o
u
t

Events
This component has standard Ignition events with the addition of the following events:
add
Event Properties

Is fired when "Add" menu item is selected. The "Add" menu item
will only appear if script has been added to this event.
(none)

edit
Event Properties
event.getSampleDefinitionName()
Return the currently selected sample definition name.
D
String
a
t
a
T
y
p
e
remove
Event Properties
event.getSampleDefinitionName() Return the currently selected sample definition name.
Data Type String
event.setRemoveDefinition
(boolean)

event.setSuppressConfirmation

Used to tell the Definition List component to remove the selected

sample definition. If this is not included in the remove event
script with a parameter of 1, then the sample definition will have to
be removed using another method.
By including this in the remove event script with a parameter of 1,
Inductive Automation

SPC Quality

(boolean)

555

the confirmation message will not be shown before

removing a sample definition. Including the event.RemoveDefinition
(0) and setSuppressConfirmation(1) script lines in
the remove event will prevent default handling of sample definitions.
This allows for custom handling of the removal of
sample definitions.

Methods
save()
Save changes to the currently selected sample definition.
parameters
(none)
returns
nothing
cancel()
Undo the changes to the currently selected sample definition.
parameters
(none)
returns
nothing
getSampleDefinition()
Return the currently selected sample definition.
returns

Sample Definition

An instance of the currently selected sample definition

Data Type
SampleDefinition

See SampleDefinition Object for more information.

addSampleDefinition(sampleDefinition)
Add the sample definition specified in the parameter.
parameters

sampleDefinition

Instance of the sample definition to add.

Data Type
SampleDefinition

See SampleDefinition Object for more information.

returns

message

Contains a description of any error encountered, otherwise it will be

empty
Data Type
String

updateSampleDefinition(sampleDefinition)
Update the sample definition specified in the parameter.
parameters

sampleDefinition

Instance of the sample definition to update.

Data Type
SampleDefinition

See SampleDefinition Object for more information.

returns

message
Inductive Automation

Contains a description of any error encountered, otherwise it will be

empty

SPC Quality

Data Type

556

String

refresh()
Refresh the currently selected sample definition. This causes any associated components such as the
Definition Attribute List to also be refreshed.
parameters
(none)
returns
nothing
4.4.1.2

Definition Attribute List

Description
A component that provides a list of measurement attributes associated with a sample definition.
There is no need for SQL queries or scripting to display sample definition attributes. If the Definition List
component is on the same screen, the Definition Attribute List will find the Definition List component and
register as a listener. Anytime the sample definition changes or the users selects a different sample
definition, the Definition Attribute List the attributes will be updated automatically.

Sam ple Definition Attribute List

The Ignition table customizer is used to change the appearance of the table. To access the customizer,
right click on the Definition Attribute List component and select the Cutomizers->Table Customizer menu
item. Using the customizer, you can hide columns, change colors, and change formatting to make the
Definition Attribute List appear as desired.
When the Read Only property is set to false, the Move Up and Move Down menu items will appear in the
popup menu. This allows the user to change the order that attributes appear in the Sample Entry
component.
Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

SPC Quality

557

Show DisabledWhen set to true, disabled sample attributes will be shown. This provides a method to re-enable
previously disabled sample attributes.

Scripting name
Data Type

showDisabled
boolean

Attribute Name The attribute name property does not show in the Ignition Designer property list. It is only
available in scripting to read the name of the current attribute that is selected when the Edit
menu item is clicked.

Scripting name
Data Type
Read Only

attrName
String

When set to true, prevents the popup menu from appearing when the user right-clicks on the
Definition Attribute List component.

Scripting name
Data Type

readOnly
boolean

Events
This component has standard Ignition events with the addition of the following events:
add
Event Properties
edit
Event Properties
event.getSampleAttrName()

remove
Event Properties
event.getSampleAttrName()

event.setRemoveAttribute(boolean)

event.setSuppressConfirmation(boolean)

Inductive Automation

Is fired when "Add" menu item is selected. The "Add"

menu item will only appear if script has been added to
this event.
(none)

Return the currently selected sample definition attribute

name.
Data
String
Type

Return the currently selected sample definition attribute

name.
Data
String
Type
Used to tell the Definition Attribute List component to
remove the selected sample definition attribute. If this is
not included in the remove event script with a parameter
of 1, then the sample definition attribute will have to be
removed using another method.
By including this in the remove event script with a
parameter of 1, the confirmation message will not be
shown before removing a sample definition attribute.
Including the event.RemoveAttribute(0) and
setSuppressConfirmation(1) script lines in the remove
event will prevent default handling of sample definition

SPC Quality

558

attributes. This allows for custom handling of the removal

of sample definition attributes.
Methods
(none)
4.4.1.3

Definition Location List

Description
A component that provides a list of production locations that a sample can be taken from for the
associated sample definition. In other words, a test is defined (sample definition) and it has locations that
are appropriate to take the test at (production location).
There is no need for SQL queries or scripting to display allowable locations. If the Definition List
component is on the same screen, the Definition Location List will find the Definition List component and
register as a listener. Anytime the sample definition changes or the users selects a different sample
definition, the Definition Location List will be updated automatically.

Sam ple Definition Location List

The Ignition table customizer is used to change the appearance of the table. To access the customizer,
right-click on the Definition Location List component and select the Cutomizers->Table Customizer menu
item. Using the customizer, you can hide columns, change colors, and change formatting to make the
Definition Location List appear as desired.
When the Read Only property is set to false, the Move Up and Move Down menu items will appear in the
popup menu. This allows the user to change the order that attributes appear in the Sample Entry
component.
Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

SPC Quality
Location ID

The location ID property does not show in the Ignition Designer property list. It on only available
in scripting to read the ID of the current production location that is selected when the Edit menu
item is clicked.

Scripting name
Data Type
Read Only

559

locID
int

When set to true, prevents the popup menu from appearing when the user right-clicks on the
Definition Location List component.

Scripting name
Data Type

readOnly
boolean

Events
This component has standard Ignition events with the addition of the following events:
add
Event Properties
edit
Event Properties
event.getSampleLocName()

remove
Event Properties
event.getSampleLocName()

Is fired when "Add" menu item is selected. The "Add"

menu item will only appear if script has been added to
this event.
(none)

Return the currently selected sample definition location

name.
Data
String
Type

Return the currently selected sample definition location

name.
Data
String
Type

event.setRemoveLocation(boolean)

Used to tell the Definition Location List component to

remove the selected sample definition location. If this is
not included in the remove event script with a parameter
of 1, then the sample definition location will have to be
removed using another method.

event.setSuppressConfirmation(boolean)

By including this in the remove event script with a

parameter of 1, the confirmation message will not be
shown before removing a sample definition location.
Including the event.RemoveLocation(0) and
setSuppressConfirmation(1) script lines in the remove
event will prevent default handling of sample definition
locations. This allows for custom handling of the removal
of sample definition locations.

Methods
Inductive Automation

SPC Quality

560

(none)
4.4.1.4

Definition Control Limit List

Description
A component that provides a list of control limits to apply to a sample definition. All control limits that are
configured in the project will appear in the list and can be selected by the user. Control limits that are
selected by the user will be available to show on control charts and may be used during automatic signal
evaluation.
There is no need for SQL queries or scripting to display control limits. If the Definition List component is
on the same screen, the Definition Control Limit List will find the Definition List component and register as
a listener. Anytime the sample definition changes or the users selects a different sample definition, the
Definition Control Limit List will be updated automatically.

Sam ple Definition Control Lim it List

Properties
This component has standard Ignition properties.
(none)

Events
This component has standard Ignition events.
(none)

Methods
(none)

Inductive Automation

SPC Quality
4.4.1.5

561

Definition Signals List

Description
A component that provides a list of signals (rules) to apply to a sample definition. All signals that are
configured in the project will appear in the list and can be selected by the user. Signals that are selected
by the user will be available to show on control charts and will be automatically evaluated when new
samples are added.
There is no need for SQL queries or scripting to display signals. If the Definition List component is on the
same screen, the Definition Signals List will find the Definition List component and register as a listener.
Anytime the sample definition changes or the users selects a different sample definition, the Definition
Signals List will be updated automatically.

Sam ple Definition Signal List

Properties
This component has standard Ignition properties.
(none)

Events
This component has standard Ignition events.
(none)

Methods
(none)
4.4.1.6

Location Selector

Description
A component that allows selection of production locations. Production locations are defined in the
Inductive Automation

SPC Quality

562

production model using the Ignition Designer. See Production Model Configuration for more information.
There is no need for SQL queries or scripting to display locations. The selected location is reflected in
Selected Location Name, Path and Location ID properties.

Location Selector

Properties
This component has standard Ignition properties with the addition of the following properties:
Selected Location Name

The name of the currently selected location.

Scripting
name
Data Type
Selected Location Path

selectedLocationName
String

The full location path of the currently selected location. This includes the
project, enterprise, site, area, and possibly a line and the location, each
separated by the backslash \ character. Example: QualityDemo\New
Enterprise\New Site\Packaging\Line 1\Line 1 Quality

Scripting name
Data Type
Selected Path Without Project

selectedLocationPath
String

The location path, excluding the project name, of the currently selected
location. This is useful when using this component with the SPCController
component. This includes the enterprise, site, area, possible a line and the
location each separated by the backslash \ character. Example: New
Enterprise\New Site\Packaging\Line 1\Line 1 Quality

Scripting name
Data Type
Selected Location ID

The location ID of the currently selected location.

Scripting name
Data Type
Display Path

selectedPathWithoutProject
String
selectedLocationID
int

When set to true, the full location paths will be displayed in the drop down
list. Otherwise, just the location name will be displayed.

Scripting name
Data Type

displayPath
boolean

Inductive Automation

SPC Quality

563

Events
This component has standard Ignition events.
(none)

Methods
(none)
4.4.1.7

Interval Selector

Description
A component that allows selection of sample intervals. All intervals that are configured in the project will
appear in the list and can be selected by the user. See the Sample Intervals section for more information
on intervals.
There is no need for SQL queries or scripting to display intervals.

Interval Selector

Properties
This component has standard Ignition properties with the addition of the following properties:
Selected Interval

The name of the currently selected interval.

Scripting name
Data Type

Events
This component has standard Ignition events.
(none)

Inductive Automation

selectedInterval
String

SPC Quality

564

Methods
(none)
4.4.1.8

Datatype Selector

Description
A component that allows selection of sample attribute data types. The data types are built into the SPC
module and cannot be added to or changed.
There is no need for SQL queries or scripting to display the data types.

Data Type Selector

The following table describes each data type.

Data Type
Integer
Real

Boolean
Inspected Count
Nonconforming Count
Nonconformity Count

Description
Positive and negative numbers without decimal points and
fractional digits.
Numbers including decimal points and fractional digits.

Range
-2,147,483,648 to
2,147,483,647
1.40129846432481707e-45 to
3.40282346638528860e+38
(positive or negative)
True or false
True or false
A count of inspected units in an integer format. This is used up to 2,147,483,647
for attribute types of sample definitions.
A count of nonconforming (defective) units in an integer
up to 2,147,483,647
format. This is used for attribute types of sample definitions.
A count of nonconformities (defects) in an integer format.
up to 2,147,483,647
This is used for attribute types of sample definitions.

Properties
This component has standard Ignition properties with the addition of the following properties:
Selected Data Type The currently selected data type.

Scripting name
Data Type

selectedDataType
AttributeDataType

Inductive Automation

SPC Quality

565

Events
This component has standard Ignition events.
(none)

Methods
(none)
4.4.1.9

Definition Selector

Description
A component that allows selection of sample definitions. One source of sample definitions is from the
definition management screen that uses the Definition List component.
There is no need for SQL queries or scripting to display the data types.

Sam ple Definition Selector

When an allowable location is added to a sample definition, a tag value can be set. This component can
limit the sample definitions that appear by entering in a matching tag values. It is typically used for defining
who has ownership for collecting sample data. For example, the lab takes samples at packaging line 1
every 2 hours. The operator also takes samples at packaging line 1 every 1 hour. When the lab takes a
sample, they don't want to see information that the operator has ownership for and visa versa. To
accomplish this, set the tag value to "Lab" for sample definitions that the lab has ownership for and to
"Operator" for sample definitions that the operator has ownership for.
Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

SPC Quality
Location Path

Set to a valid path of a production location item to show the sample

definition for the location.

Scripting name
Data Type
Tag

locationPath
String

The currently selected sample definition name.

Scripting name
Data Type
Selected Sample DefUUID

locationPath
String

Optionally, set to a value to filter the sample definition by.

Scripting name
Data Type
Selected Sample Definition Name

566

selectedSampleDefinitionName
String

Return the UUID assigned to the currently selected sample definition. A

UUID is a universally unique identifier that, once assigned to a sample
definition, will never change. It is automatically generated when a sample
definition is created and is unique in that no two samples definitions will
have the same UUID.

Scripting name
Data Type

selectedSampleDefUUID
String

Events
This component has standard Ignition events.
(none)

Methods
(none)
4.4.1.10 Location Sample List

Description
A component that displays samples for a location and optionally by sample ownership. Through
configuration properties, it can show samples that are scheduled to be coming due, due, overdue, or
waiting approval or approved.
There is no need for SQL queries or scripting to display the samples.

Inductive Automation

SPC Quality

567

Sam ple Definition Selector

When an allowable location is added to a sample definition, a tag value can be set. This component can
limit the samples that appear by entering in matching tag values. It is typically used for defining who has
ownership for collecting sample data. For example, the lab takes samples at packaging line 1 every 2
hours. The operator also takes samples at packaging line 1 every 1 hour. The lab does not want to see
samples that the operator has ownership for and vice versa. To accomplish this, set the tag value to
"Lab" for sample definitions that the lab has ownership for and to "Operator" for sample definitions that the
operator has ownership for.
The Ignition table customizer is used to change the appearance of the table. To access the customizer,
right-click on the Location Sample List component and select the Cutomizers->Table Customizer menu
item. Using the customizer, you can hide columns, change colors, change formatting to make the
Location Sample List appear as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Location Path

Set to a valid path of a production location item to show samples for that
location.

Scripting name
Data Type
Tag

Optionally, set to a value to filter the samples by.

Scripting name
Data Type
Read Only

showApprovedSamples
boolean

When set to true, includes samples that are due.

Scripting name
Data Type
Inductive Automation

showWaitingApproval
boolean

When set to true, includes samples that have been approved.

Scripting name
Data Type
Show Due Samples

readOnly
boolean

When set to true, includes samples that are waiting approval.

Scripting name
Data Type
Show Approved Samples

locationPath
String

When set to true, prevents the popup menu from appearing when the user
right-clicks on the Location Sample List component.

Scripting name
Data Type
Show Waiting Approval

locationPath
String

showDueSamples
boolean

SPC Quality

Show Coming Due Samples

When set to true, includes samples that are coming due.

Scripting name
Data Type
Show Overdue Samples

showOverdueSamples
boolean

When set to true, includes samples that have been previously removed.

Scripting name
Data Type
Sort Type

showDueSamples
boolean

When set to true, includes samples that are overdue.

Scripting name
Data Type
Show Removed Samples

568

showRemovedSamples
boolean

Changes the order that the sample will appear in the list.
Options:
None
Display samples in natural order.
Due State
Display samples in order of the severity of due state.
Taken Date Time
Display samples in order by the date it is taken.
Taken Date Time (Descending) Display samples in reverse order by the date it is taken.

Scripting name
Data Type

sortType
int

Numeric value used in scripting.

None
Due State
Taken Date Time
Taken Date Time (Descending)

Enable Note Editing

When set to true, allows users to enter a note tied to a sample.

Scripting name
Data Type
Start Date

endDate
Date

Optionally, set this property to only show samples for specified product code.

Scripting name
Data Type
Reference No

startDate
Date

Optionally, set this property to only show samples that are scheduled before the
specified End Date.

Scripting name
Data Type
Product Code

showEnableNoteEditing
boolean

Optionally, set this property to only show samples that are scheduled after the
specified Start Date.

Scripting name
Data Type
End Date

0
1
2
3

productCode
String

Optionally, set this property to only show samples for specified reference number.
Reference numbers can represent anything such as lot number, batch number,
raw material lot number, raw material vendor, etc.

Scripting name
Data Type

referenceNo
String

Events
This component has standard Ignition events with the addition of the following events:
Inductive Automation

SPC Quality

add
Event Properties
edit
Event Properties
event.getSampleUUID()

remove
Event Properties
event.getSampleUUID()

approve
Event Properties
event.getSampleUUID()

unapprove
Event Properties
event.getSampleUUID()

review
Event Properties
event.getSampleUUID()

Methods
Inductive Automation

569

Is fired when "Add" menu item is selected. The "Add" menu item will only
appear if script has been added to this event.
(none)
Is fired when "Edit" menu item is selected. The "Edit" menu item will only
appear if script has been added to this event.
Return the sample UUID for the currently selected sample. A UUID is a
universally unique identifier that, once assigned to a sample,
will never change. It is automatically generated when a sample is created
and is unique in that no two samples will have the same UUID.
Data Type
String
Is fired when "Remove" menu item is selected. The "Remove" menu item
will only appear if script has been added to this event.
Return the sample UUID for the currently selected sample. A UUID is a
universally unique identifier that, once assigned to a sample,
will never change. It is automatically generated when a sample is created
and is unique in that no two samples will have the same UUID.
Data Type String
Is fired when "Approve" menu item is selected. The "Approve" menu item
will only appear if script has been added to this event.
Return the sample UUID for the currently selected sample. A UUID is a
universally unique identifier that, once assigned to a sample,
will never change. It is automatically generated when a sample is created
and is unique in that no two samples will have the same UUID.
Data Type String
Is fired when "Unapprove" menu item is selected. The "Unapprove" menu
item will only appear if script has been added to this event.
Return the sample UUID for the currently selected sample. A UUID is a
universally unique identifier that, once assigned to a sample,
will never change. It is automatically generated when a sample is created
and is unique in that no two samples will have the same UUID.
Data Type String
Is fired when "Review" menu item is selected. The "Review" menu item
will only appear if script has been added to this event.
Return the sample UUID for the currently selected sample. A UUID is a
universally unique identifier that, once assigned to a sample,
will never change. It is automatically generated when a sample is created
and is unique in that no two samples will have the same UUID.
Data Type String

SPC Quality

570

createByDefUUID(defUUID)
Create a new sample based on the sample definition specified by the defUUID parameter.
parameters

defUUID

Sample definition UUID to base the new sample on. A UUID is a

universally unique identifier that, once assigned to a sample
definition, will never change. It is automatically generated when a
sample definition is created and is unique in that no two samples
definitions will have the same UUID.

Data Type

String

See SampleDefinition Object for more information.

returns

Sample

An instance of a new sample

Data Type

Sample

See Sample Object for more information.

createByDefName(defName)
Create a new sample based on the sample definition specified by the defName parameter.
parameters

defName

Sample definition name to base the new sample on.

Data Type

String

See SampleDefinition Object for more information.

returns

Sample

An instance of a new sample

Data Type

Sample

See Sample Object for more information.

update(sample)
Create a new sample based on the sample definition specified by the defName parameter.
parameters

sample

This is the sample to either update, if it already exists, or add, if it

does not already exist.

Data Type

Sample

See Sample Object for more information.

returns

String

Message of any errors that may have occurred during the update
operation.
Data Type
String

approve(sample)
Approve the sample specified by the sample parameter.
parameters

sample

This is the sample to approve.

Data Type

Sample

See Sample Object for more information.

returns

String

Message of any errors that may have occurred during the

approve operation.
Data Type
String
Inductive Automation

SPC Quality

571

unapprove(sample)
Unapprove the sample specified by the sample parameter.
parameters
This is the sample to unapprove.

sample

Data Type

Sample

See Sample Object for more information.

returns

String

Message of any errors that may have occurred during the

unapprove operation.
Data Type
String

remove(sample)
Remove the sample specified by the sample parameter. Caution: this will permanently remove the
data from the database and it cannot be recovered.
parameters
This is the sample to remove.

sample

Data Type

Sample

See Sample Object for more information.

returns

String

Message of any errors that may have occurred during the remove
operation.
Data Type
String

getSample(sampleUUID)
Return the sample specified by the sampleUUID parameter.
parameters

sampleUUID

Sample UUID to return the sample for. A UUID is a universally

unique identifier that, once assigned to a sample, will never change.
It is automatically generated when a sample is created and is unique
in that no two samples will have the same UUID.

Data Type

String

See Sample Object for more information.

returns

Sample

An instance of a sample
Data Type

Sample

See Sample Object for more information.

showEditNotePopup()
Show the note popup to allow the user to add or edit the note tied to the currently selected sample.
parameters
(none)
returns
nothing

Inductive Automation

SPC Quality

572

4.4.1.11 Sample Entry

Description
A component used to display and enter sample measurement data. The entry fields are dynamically
created based on attributes defined in the sample definition. Additionally, the number of measurements
are defined by the measurement count setting in the sample definition. The Up Down Traversal property
can be used to change the field tab order between column and row. When saving, the measurement data
is validated, and if any validation errors exists a message is displayed to the user.
Depending on the measurement count defined in the sample definition, the orientation of the edit fields will
change. If the measurement count is greater than 1, then there will be a row for each measurement with
the attributes appearing horizontally. If the measurement count is equal to 1, then the attributes appear
vertically in separate rows. This reduces the need for the user to have to scroll while entering sample data
if the are a number of attributes.

Multiple Measurem ent Sam ple Entry

Inductive Automation

SPC Quality

573

Single Measurem ent Sam ple Entry

Properties
This component has standard Ignition properties with the addition of the following properties:
Up Down Traversal

When set to true, causes the focused field to move down to the next field
when the Tab or Enter keys are pressed. If it is on the last measurement, it
will move to the top field in the next column. When set to false, causes the
focused field to move right to the next field when the Tab or Enter keys are
presses. If it is on the last column, it will move to the left column of the next
row.

Scripting name
Data Type
Read Only

When set to true, prevents the popup menu from appearing when the user
right-clicks on the Location Sample List component.

Scripting name
Data Type
Sample Taken Date Time

backgroundColor
Color

This is the header text for the measurement column.

Scripting name
Data Type
Inductive Automation

foregroundColor
Color

This is the color of the body of the Sample Entry component.

Scripting name
Data Type
Measurement Label

sampleTakenDateTime
Date

This is the color of the text within the Sample Entry component.

Scripting name
Data Type
Background Color

readOnly
boolean

When set, it will be used for the date and time the sample was taken. If not set,
the current date and time will be used for the date and time the sample was
taken. This is useful if samples are taken but not entered until a later time.

Scripting name
Data Type
Foreground Color

upDownTraversal
boolean

measurementLabel
String

SPC Quality
Label Font

Font used for the column headers.

Scripting name
Data Type
Title

fieldFont
Font

Space in pixels between columns.

Scripting name
Data Type
Row Gap Size

numberFont
Font

Font to use for the entry fields.

Scripting name
Data Type
Column Gap Size

titleFont
Font

Font to use for the measurement numbers.

Scripting name
Data Type
Entry Field Font

title
String

Font to use for the title.

Scripting name
Data Type
Measurement Number
Font

labelFont
Font

Text to show at the top of the Sample Entry component.

Scripting name
Data Type
Title Font

574

gapx
int

Space in pixels between rows.

Scripting name
Data Type

gapy
int

Events
This component has standard Ignition events.
(none)

Methods
save()
Save changes made to the measurement values. This method also records the current product code and
reference number for the production location.
parameters
(none)
returns

String

Message of any errors that may have occurred during the save
operation.
Data Type
String

save(productCode, refNo)
Save changes made to the measurements values along with a product code and reference number
specified in the parameters.
parameters
Inductive Automation

SPC Quality

productCode

Product code to record along with the measurement values.

Data Type
refNo

575

String

Reference number to record along with the measurement values.

Data Type

String

returns

String

Message of any errors that may have occurred during the save
operation.
Data Type
String

undo()
Any changed measurement values will be restored to their original values.
parameters
(none)
returns
nothing
approve()
Approve the current sample.
parameters
(none)
returns

String

Message of any errors that may have occurred during the

approve operation.
Data Type
String

unapprove()
Unapprove the current sample.
parameters
(none)
returns

String

Message of any errors that may have occurred during the

unapprove operation.
Data Type
String

showEditNotePopup()
Show the note popup to allow the user to add or edit the note tied to the currently selected sample.
parameters
(none)
returns

String

4.4.2

Message of any errors that may have occurred during the show
note operation.
Data Type
String

SPC Components

SPC Com ponents

Inductive Automation

SPC Quality
4.4.2.1

576

SPC Selector

Description
A component that allows selections of SPC data. As the user makes selections, this component will
query the server for results. These results can be accessed through the SPC Results and SPC Data and
can be linked with any of the SPC control charts.

SPC Selector

A filter can be added by selecting the

link to the right of Filter By. A window panel will open and filter

categories will be displayed. Click the link by the filter category and specific filter items will be displayed.
When selected they will be added to the filters as shown below. To minimize the number of filter options,
reduce the date range defined by the Start Date and End Date properties and the associated filter values
will be shown. Because values collected from different locations being shown together does not make
sense, a location must be added to the Filter By section.

Filter By List
Inductive Automation

SPC Quality

577

Sample definitions can have more than one attribute. At the time sample data is recorded, each attribute
will have a value associated with it. For example, when collecting viscosity reading it may also be
important to know the temperature. But, showing and making calculations on a viscosity value of 10000
with a temperature value of 75.2 does not make sense. The SPC Selector allow selecting a single
attribute as shown below.
If a attribute type of sample definition is selected, then the Attribute section will not appear. This is
because with attribute charts, all attributes are included and shown. For example, if a sample definition
has an attribute for Torn, Discolored, Pitted, etc. then all will show in the table and included in the
calculations.

Attribute Selection

Similar to filters, control limits and signals can be added to the SPC results. Any selected control limits,
and signals that depend on them, will not appear on the control chart until the control limit value has been
set.
Selections can be removed by selecting the

link to the left of the selection.

To display the SPC results of this component in a control charts, bind the SPC Results property of the
control chart to the SPC Results property of this component.
Properties
This component has standard Ignition properties with the addition of the following properties:
Start Date

This property is the starting date for retrieving analysis data and determining
available filter and compare by options.
Scripting name
startDate
Data Type
Date

End Date

This property is the ending date for retrieving analysis data and determining
available filter and compare by options.
Scripting name
endDate
Data Type
Date

Inductive Automation

SPC Quality
Definition Name

578

The sample definition to used when building SPC results.

Scripting name
Data Type

definitionName
String

Auto Refresh

If true, the SPC results will be updated every time a new sample is added for the
selected sample definition and location.
Scripting name
autoRefresh
Data Type
Boolean

SPC Results

This bind only property holds the SPC results and includes a data set with the
raw data, sample definition information and calculated value information. With all
the information included in the SPC Results, control charts can display the
results which is not possible with the data set alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Suppress Warnings

Suppress Errors

If true, any warnings received back when requesting SPC results

are not shown. Instead the Message property can be bound to
display any warning in a text or other component. Warning include
requesting SPC data with settings that do not make sense. For
example, requesting p chart results for a sample definition that
contains no attribute type of data.
Scripting name
suppressWarnings
Data Type
Boolean
If true, any errors received back when requesting SPC results are not shown.
Scripting name
Data Type

Include Disabled
Attributes

Filter
Selection
Summary

suppressErrors
Boolean

If true, any attributes that have been disabled in the sample definition
will appear in the attribute selection panel. This provides a method to
view old attribute data that has been disabled.
Scripting name
includeDisabledAttributes
Data Type
Boolean
This property holds the current filter item selections that the results will be
filtered by. If more than one item exists, they are separated by commas.
Scripting name
Data Type

filterSummary
String

Inductive Automation

SPC Quality

579

Attribute Name

This property holds the currently selected attribute to include in the results. For
each sample definition there may be multiple attributes that are collected. This
property selects which one to show get the SPC Results for.
Scripting name
attributeName
Data Type
String

Control Limit
Summary

This property holds the current control limit selections to include in the results. If
more than one item exists, they are separated by commas.
Scripting name
controlLimitSummary
Data Type
String

Signal
Summary

This property holds the currently selected signals to include in the results. If
more than one item exists, they are separated by commas.
Scripting name
signalSummary
Data Type
String

SPC Data Format

This property specifies the type of control chart to retrieve the SPC data for.
Options:
None - No results will be returned.
XBarR - XBar and range data will be returned.
XBarS - XBar and standard deviation data will be returned.
Individual - Individual and moving range data will be returned.
Median - Median and moving range data will be returned.
P - P chart data will be returned.
NP - NP chart data will be returned.
C - C chart data will be returned.
U - U chart data will be returned.
Histogram - Histogram data will be returned.
Pareto - Pareto data will be returned.
Scripting name
Data Type

spcDataFormat
SPCDataFormat

Numeric value used in scripting.

None
XBarR
XBarS
Individual
Median
U
C
P
NP
Histogram
Pareto

Auto Bar Count

If set to true, the number of histogram bars will be automatically determined.

Scripting name
Data Type

Inductive Automation

0
1
2
3
4
5
6
7
8
9
10

autoBarCount
boolean

SPC Quality

580

Data Bar Count

If Auto Bar Count is set to false, the value of this property will determine the
number of histogram bars.
Scripting name
dataBarCount
Data Type
int

Padding Bar Count

The value of this property determines how many empty bars will be included in
histogram results.
Scripting name
paddingBarCount
Data Type
int

Events
This component has standard Ignition events.
Methods
refreshInfo()
Force refresh of the SPC results.
parameters
(none)
returns
nothing
setSpcDataFormat(spcDataFormat)
Change to format if the SPC data to return.
parameters

spcDataFormat

Format of the SPC data to return.

Data Type
None
XBarR
XBarS
Individual
Median
U
C
P
NP
Histogram
Pareto

returns

int
0
1
2
3
4
5
6
7
8
9
10

nothing

setRowLimit(rowLimit)
Change the default number of samples to return to the value specified in the rowLimit parameter. By
default only 500 samples are returned in the SPC results. This is done to unburden the database,
network bandwidth and memory.
parameters

rowLimit

New row limit.

Data Type

returns

int

nothing

getRowLimit()
Inductive Automation

SPC Quality

581

Returns the current row limit value.

parameters
(none)
returns
nothing
Example Code
This script will change the format of the SPC results.
event.source.parent.getComponent('SPC Selector').setSpcDataFormat(system.quality.spc.format.P.getValue())
4.4.2.2

Stored SPC Selector

Description
A component that allows creating, recalling and saving SPC selections in the SPC Selector component.
This component will automatically use the available SPC Selector in the container. Keep in mind that
whenever a new sample definition is created, a new stored SPC settings items will be created with the
default values. This being said, additional stored SPC settings items can be created each with different
filters, attribute, control limits and signals.

Stored SPC Selector

By clicking on the
settings will popup.

link, a menu with the option to create new, save, delete and rename SPC

To add a new saved SPC settings item, click on New menu item, enter a name, select a sample
definition and click OK. This will create a default SPC Settings item. Now the user can select filters,
attribute, control limits and signals that will be saved and can easily be selected at a later time.

New Stored SPC Settings

To rename a stored SPC Settings item, select an item and click on the Rename menu item, enter a new
name and click OK.

Renam e Stored SPC Settings

To delete a stored SPC Settings item, select an item and click on Delete menu item, and select Yes to
Inductive Automation

SPC Quality

582

the confirmation message.

If changes to a stored SPC settings values have been made and the user selects a different stored SPC
Settings, they will be prompted to save the changes. Alternatively, the changes can be saved by clicking
on the Save menu item.
Properties
This component has standard Ignition properties with the addition of the following properties:
Show Disabled When true, disabled attributes will be included in the attribute list.

Scripting name
Data Type

showDisabled
Boolean

Show Menu

When true, the menu will be displayed. By setting the property to false, it will only allow
users to select stored SPC settings items and prevent them from creating new,
renaming existing, saving over existing or deleting stored SPC Settings items.
Scripting name
showMenu
Data Type
Boolean

Menu Top

The y coordinate to display the menu at.

P
o
s
i
t
i
o
n

Scripting name
Data Type
Menu Left

menuTopPosition
int

The x coordinate to display the menu at.

P
o
s
i
t
i
o
n

Scripting name
Data Type
Menu Image

menuLeftPosition
int

The image to show for the menu.

Scripting name
Data Type

menuImage
Image

Events
This component has standard Ignition events with the addition of the following events:
Inductive Automation

SPC Quality

selected
Event Properties
event.getSettingsName()
event.getSettings()
created
Event Properties
event.getSettingsName()
event.getSettings()

583

Is fired when a different SPC Settings item is selected menu item is

selected.
Returns the name of the newly selected SPC Settings item.
Returns a reference to the SPCSettings object that contains the filter, attribute,
control limit and signal selections.

Is fired when a new SPC Settings item is created.

Returns the name of the newly created SPC Settings item.
Returns a reference to the SPCSettings object that contains the filter, attribute,
control limit and signal selections.

deleted
Event Properties
event.getSettingsName()

Is fired when a SPC Settings item is deleted.

renamed
Event Properties
event.getSettingsName()

Is fired when a SPC Settings item is renamed.

event.getPrevName()

Returns the previous name of the SPC Settings item.

event.getSettings()

Returns a reference to the SPCSettings object that contains the filter, attribute,
control limit and signal selections.

Returns the name of the deleted SPC Settings item.

Returns the new name of the SPC Settings item.

Methods
(none)
4.4.2.3

SPC Controller

Description
An invisible component that makes SPC data available for reports and other components. The term
invisible component means that this component appears during design time, but is not visible during
runtime.
In cases where the SPC Selector offers too many options to the use, this component can be used. It has
all of the same functionality as the SPC Selector but without the user interface. This means property
bindings or script must be used to make the filter, compare by and data point selections. It also is used
for providing data to canned reports and optionally allowing the user to make limited filter options.
To display the SPC results of this component in a control charts, bind the SPC Results property of the
control chart to the SPC Results property of this component.
Properties
This component has standard Ignition properties with the addition of the following properties:
Inductive Automation

SPC Quality

584

Automatic Update

When true, when any property that changes the results, the results will
automatically be updated.
Scripting name
automaticUpdate
Data Type
Boolean

Auto Refresh

If true, the SPC results will be updated every time a new sample is added for the
selected sample definition and location.
Scripting name
autoRefresh
Data Type
Boolean

Row Limit

The number of samples to return in the SPC Results. This is done to unburden the
database, network bandwidth and memory.
Scripting name
autoRefresh
Data Type
Boolean

SPC Data Format

This property specifies the type of control chart to retrieve the SPC data for.
Options:
None - No results will be returned.
XBarR - XBar and range data will be returned.
XBarS - XBar and standard deviation data will be returned.
Individual - Individual and moving range data will be returned.
Median - Median and moving range data will be returned.
P - P chart data will be returned.
NP - NP chart data will be returned.
C - C chart data will be returned.
U - U chart data will be returned.
Histogram - Histogram data will be returned.
Pareto - Pareto data will be returned.
Scripting name
Data Type

spcDataFormat
SPCDataFormat

Numeric value used in scripting.

None
XBarR
XBarS
Individual
Median
U
C
P
NP
Histogram
Pareto

Start Date

0
1
2
3
4
5
6
7
8
9
10

This property is the starting date for retrieving analysis data and determining
available filter and compare by options.
Scripting name
startDate
Data Type
Date

Inductive Automation

SPC Quality

585

End Date

This property is the ending date for retrieving analysis data and determining
available filter and compare by options.
Scripting name
endDate
Data Type
Date

Stored SPC Name

This optional property can be used to populate the Definition Name, Attribute
Name, FIlter, Control Limits, SIgnals, SPC Data Format properties with those in
a store SPC settings. Stored SPC settings are saved using the SPC Selector
and Stored SPC Selector components.
Scripting name
storedSPCName
Data Type
String

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

definitionName
String

Attribute Name

This property holds the attribute from the sample definition to include in the
results. For each sample definition there may be multiple attributes that are
collected. This property selects which one to show get the SPC Results for.
Scripting name
attributeName
Data Type
String

Filter

This property holds the filter expression that the results will be filtered by. If more
than one item exists, they are separated by commas. Example: Approved
By=John Doe
Scripting name
filter
Data Type
String

Control Limits

This property holds the control limits to include in the results. If more than one
item exists, they are separated by commas. Example: Individual LCL, Individual
UCL
Scripting name
controlLimits
Data Type
String

Signals

This property holds the signals to include in the results. If more than one item
exists, they are separated by commas.
Example: Individual Outside
Scripting name
signals
Data Type
String

SPC Results

This bind only property holds the SPC results and includes a data set with the
raw data, sample definition information and calculated value information. With all
the information included in the SPC Results, control charts can display the
results which is not possible with the data set alone.
Scripting name
spcResults
Data Type
SPCResults

Inductive Automation

SPC Quality

586

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

SPC Data

Include Disabled Attributes

If true, any attributes that have been disabled in the sample

definition will appear in the attribute selection panel. This provides a
method to view old attribute data that has been disabled.
Scripting name
includeDisabledAttributes
Data Type
Boolean

Error Message

If an error is encountered while retrieving SPC results, it will be readable from

this property.
Scripting name
errorMessage
Data Type
String

Warning Message

If a warning is encountered while retrieving SPC results, it will be readable from

this property.
Scripting name
warningMessage
Data Type
String

Auto Bar Count

If set to true, the number of histogram bars will be automatically determined.

Scripting name
Data Type

autoBarCount
boolean

Data Bar Count

If Auto Bar Count is set to false, the value of this property will determine the
number of histogram bars.
Scripting name
dataBarCount
Data Type
int

Padding Bar Count

The value of this property determines how many empty bars will be included in
histogram results.
Scripting name
paddingBarCount
Data Type
int

Dynamic
Properties

Depending on the setting of the Definition Name property, the dynamic properties will
change. A dynamic property to be created for each filter category that can be bound to
by other components. These dynamic properties can also be set through script.

Events
This component has standard Ignition events with the addition of the following events:
beforeUpdate
Is fired just before SPC results are requested from the SPC module.
Event Properties (none)
afterUpdate
Is fired just after SPC results are requested from the SPC module.
Event Properties (none)
Inductive Automation

SPC Quality

587

Methods
refreshInfo()
Causes the sample definition information to be refreshed.
parameters
(none)
returns
nothing
---------------------------------------------------------------------------------------------------------------------------------------------------------------

update()
Causes the SPC results to be updated.
parameters
(none)
returns
nothing
4.4.2.4

Histogram Chart

Description
The Histogram chart is used to display frequency distribution of sample measurements. It does not
retrieve SPC results from the SPC module so it must be used with either the SPC Selector or the SPC
Controller components that do. Only SPC results with Histogram SPC Data Format specified will be
displayed.

Histogram Chart
Inductive Automation

SPC Quality

588

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Background Color

The background color.

Scripting name
Data Type

No Data Message

backgroundColor
Color

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

noDataMessage
String

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Chart Properties
Vertical

If true, the bars will be shown vertically.

Scripting name
Data Type

vertical
boolean
Inductive Automation

SPC Quality

589

Chart Background
The background color of the chart.
Colo
r

Scripting name
Data Type
Bar Color

chartBackgroundColor
Color

Color of the bars.

Scripting name
Data Type

barColor
Color

Bar Spacing

Specifies the spacing between the bars. It is a fractional value from 0.0 to 1.0
and represents the percentage of the bar width to make as space between the
bars.
Scripting name
barSpacing
Data Type
float

Gradient

If true, show bars with gradient fill.

Scripting name
Data Type

Shadows

If true, show bars shadows for each bar.

Scripting name
Data Type

Tick Label Font

tickLabelFont
Font

The color to show values on the value and count axis.

Scripting name
Data Type

Value Axis Title

shadows
boolean

The font to show values on the value and count axis.

Scripting name
Data Type

Tick Label Color

gradient
boolean

tickLabelColor
Color

The title to display on the value axis.

Scripting name
Data Type

valueAxisTitle
String

Frequency Axis Title The title to display on the frequency axis.

Scripting name
Data Type

Inductive Automation

frequencyAxisTitle
String

SPC Quality
Axis Title Font

The font to show the axis titles.

Scripting name
Data Type

Axis Title Color

590

axisTitleFont
Font

The color to show the axis titles.

Scripting name
Data Type

Vertical Grid Line Color

axisTitleColor
Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

Horizontal Grid Line Color

showVerticalGridLines
boolean

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

verticalGridLineColor
Color

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

showHorizontalGridLines
boolean

Events
This component has standard Ignition events.
(none)

Methods
showSetLimitPanel()
Causes the calculate and set control limit dialog to be shown.

4.4.2.5

parameters

(None)

returns

nothing

Pareto Chart

Inductive Automation

SPC Quality

591

Description
The Pareto chart is used to display which nonconforming items or nonconformities are the largest issue.
It does not retrieve SPC results from the SPC module so it must be used with either the SPC Selector or
the SPC Controller components that do. Only SPC results with Pareto SPC Data Format specified will be
displayed.

Pareto Chart

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Inductive Automation

SPC Quality
Background Color

The background color.

Scripting name
Data Type

No Data Message

592

backgroundColor
Color

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

noDataMessage
String

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Chart Properties
Vertical

If true, the bars will be shown vertically.

Scripting name
Data Type

Chart Background Color

vertical
boolean

The background color of the chart.

Scripting name
Data Type

Bar Color

Color of the bars.

Scripting name
Data Type

Accumulation Line Color

barColor
Color

Color of the total accumulation line.

Scripting name
Data Type

Bar Spacing

chartBackgroundColor
Color

accumulationLineColor
Color

Specifies the spacing between the bars. It is a fractional value from 0.0 to 1.0
and represents the percentage of the bar width to make as space between the
bars.
Scripting name
barSpacing
Data Type
float

Inductive Automation

SPC Quality
Gradient

If true, show bars with gradient fill.

Scripting name
Data Type

Shadows

tickLabelFont
Font

The color to show values on the value and count axis.

Scripting name
Data Type

Category Axis Title

shadows
boolean

The font to show values on the value and count axis.

Scripting name
Data Type

Tick Label Color

gradient
boolean

If true, show bars shadows for each bar.

Scripting name
Data Type

Tick Label Font

593

tickLabelColor
Color

The title to display on the category axis.

Scripting name
Data Type

categoryAxisTitle
String

Frequency Axis Title The title to display on the frequency axis.

Scripting name
Data Type
Axis Title Font

The font to show the axis titles.

Scripting name
Data Type

Axis Title Color

frequencyAxisTitle
String

axisTitleFont
Font

The color to show the axis titles.

Scripting name
Data Type

Horizontal Grid Line Color

axisTitleColor
Color

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Inductive Automation

horizontalGridLineColor
Color

showHorizontalGridLines
boolean

SPC Quality

Show Accumulation Line

594

If true, show the accumulation line in the chart.

Scripting name
Data Type

showAccumulationLine
boolean

Events
This component has standard Ignition events.
(none)

Methods
(none)
4.4.2.6

Xbar and R Chart

Description
The XBar Range control chart is used to display SPC results that have multiple measurements for each
sample. It does not retrieve SPC results from the SPC module so it must be used with either the SPC
Selector or the SPC Controller components that do. Only SPC results with XBar and Range SPC Data
Format specified will be displayed.

XBar Range Control Chart

Inductive Automation

SPC Quality

595

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count This property represents the number of measurements for each sample in the

SPC results.
Scripting name
Data Type

measurementCount
int

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

Inductive Automation

backgroundColor
Color

noDataMessage
String

SPC Quality

596

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Table Properties
Show Table

If true, the table containing measurement and calculated values will be shown at
the top of the control chart.
Scripting name
showTable
Data Type
boolean

Min Visible Samples

The minimum number of sample to show on the control chart. If

more than the minimum visible samples exist in the SPC results,
then a horizontal scroll bar will appear and allow the user to scroll
back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int

Min Visible Measurements

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be expanded to
match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

rowHeight
int

The background color of the sample date row.

Scripting name
Data Type

dateBackground
Color

Inductive Automation

SPC Quality
Date Foreground

The foreground color of the sample date values.

Scripting name
Data Type

Date Font

The font to display the sample date values.

Scripting name
Data Type

Date Format

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Inductive Automation

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

labelForeground
Color

The font to display the labels.

Scripting name
Data Type

Data Background

labelBackground
Color

The foreground color of the labels.

Scripting name
Data Type

Label Font

dateFormat
String

The background color of the labels.

Scripting name
Data Type

Label Foreground

dateFont
Font

The date formatting pattern to display the sample dates.

Scripting name
Data Type

Label Background

dateForeground
Color

calcBackground
Color

597

SPC Quality

Calc Foreground

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

598

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

calcFont
Font

Chart Properties
Show Primary Chart

If true, the primary chart will appear.

Scripting name
Data Type

Show Secondary Chart

If true, the secondary chart will appear.

Scripting name
Data Type

Right Axis Width

showPrimaryChart
boolean

showSecondaryChart
boolean

The width of the right chart axis in pixels.

Scripting name
Data Type

rightAxisWidth
int

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

limitDialogVerticalOffset
int

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

showVerticalGridLines
boolean

Inductive Automation

SPC Quality
Horizontal Grid Line Color

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

Secondary Chart Background

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

599

primaryChartBackground
Color

The background color of the secondary chart.

Scripting name
Data Type

secondaryChartBackground
Color

Show Notes

If true, show the note icon next to the chart point for any samples
that have notes or assignable causes.
Scripting name
showNotes
Data Type
boolean

Note Image

The image to display next to the chart point for any samples that
have notes or assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing

If true, allow the user to add and edit notes and assignable causes.
Scripting name
Data Type

enableNoteEditing
boolean

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

Events
Inductive Automation

enableControlLimitEditing
boolean

SPC Quality

600

This component has standard Ignition events.

(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary" or "Secondary"
Data Type

returns
4.4.2.7

String

nothing

Xbar and S Chart

Description
The XBar Standard Deviation (S) control chart is used to display SPC results that have multiple
measurements for each sample. It does not retrieve SPC results from the SPC module so it must be
used with either the SPC Selector or the SPC Controller components that do. Only SPC results with XBar
and S SPC Data Format specified will be displayed.

XBar Standard Deviation Control Chart

Inductive Automation

SPC Quality

601

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count

This property represents the number of measurements for each

sample in the SPC results.
Scripting name
measurementCount
Data Type
int

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

Inductive Automation

backgroundColor
Color

noDataMessage
String

SPC Quality

602

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Table Properties
Show Table

If true, the table containing measurement and calculated values will be shown at
the top of the control chart.
Scripting name
showTable
Data Type
boolean

Min Visible Samples The minimum number of sample to show on the control chart. If more than the

minimum visible samples exist in the SPC results, then a horizontal scroll bar
will appear and allow the user to scroll back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int
Min Visible Measurements

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be expanded to
match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

The background color of the sample date row.

Scripting name
Data Type

Date Foreground

rowHeight
int

dateBackground
Color

The foreground color of the sample date values.

Scripting name
Data Type

dateForeground
Color
Inductive Automation

SPC Quality

Date Font

The font to display the sample date values.

Scripting name
Data Type

Date Format

The date formatting pattern to display the sample dates.

Scripting name
Data Type

Label Background

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Inductive Automation

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

labelForeground
Color

The font to display the labels.

Scripting name
Data Type

Data Background

labelBackground
Color

The foreground color of the labels.

Scripting name
Data Type

Label Font

dateFormat
String

The background color of the labels.

Scripting name
Data Type

Label Foreground

dateFont
Font

calcBackground
Color

603

SPC Quality
Calc Foreground

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

604

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

calcFont
Font

Chart Properties
If true, the primary chart will appear.

Show Primary Chart

Scripting name
Data Type
Show Secondary Chart

If true, the secondary chart will appear.

Scripting name
Data Type

Right Axis Width

showPrimaryChart
boolean

showSecondaryChart
boolean

The width of the right chart axis in pixels.

Scripting name
Data Type

rightAxisWidth
int

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

limitDialogVerticalOffset
int

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

showVerticalGridLines
boolean

Inductive Automation

SPC Quality
Horizontal Grid Line Color

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

primaryChartBackground
Color

The background color of the secondary chart.

Scripting name
Data Type

Show Notes

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

Secondary Chart Background

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

605

secondaryChartBackground
Color

If true, show the note icon next to the chart point for any samples that have notes
or assignable causes.
Scripting name
showNotes
Data Type
boolean

Note Image

The image to display next to the chart point for any samples that
have notes or assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing

If true, allow the user to add and edit notes and assignable causes.
Scripting name
Data Type

enableNoteEditing
boolean

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

Events
Inductive Automation

enableControlLimitEditing
boolean

SPC Quality

606

This component has standard Ignition events.

(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary" or "Secondary"
Data Type

returns
4.4.2.8

String

nothing

Median and Range Chart

Description
The Median Moving Range (MR) control chart is used to display SPC results that have multiple
measurements for each sample. It does not retrieve SPC results from the SPC module so it must be
used with either the SPC Selector or the SPC Controller components that do. Only SPC results with
Median and MR SPC Data Format specified will be displayed.

Median Moving Range Control Chart

Inductive Automation

SPC Quality

607

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count This property represents the number of measurements for each sample in the

SPC results.
Scripting name
Data Type

measurementCount
int

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

Inductive Automation

backgroundColor
Color

noDataMessage
String

SPC Quality

608

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Table Properties
Show Table

If true, the table containing measurement and calculated values will be shown at
the top of the control chart.
Scripting name
showTable
Data Type
boolean

Min Visible Samples

The minimum number of sample to show on the control chart. If

more than the minimum visible samples exist in the SPC results,
then a horizontal scroll bar will appear and allow the user to scroll
back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int

Min Visible Measurements

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be expanded to
match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

rowHeight
int

The background color of the sample date row.

Scripting name
Data Type

dateBackground
Color

Inductive Automation

SPC Quality
Date Foreground

The foreground color of the sample date values.

Scripting name
Data Type

Date Font

The font to display the sample date values.

Scripting name
Data Type

Date Format

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Inductive Automation

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

labelForeground
Color

The font to display the labels.

Scripting name
Data Type

Data Background

labelBackground
Color

The foreground color of the labels.

Scripting name
Data Type

Label Font

dateFormat
String

The background color of the labels.

Scripting name
Data Type

Label Foreground

dateFont
Font

The date formatting pattern to display the sample dates.

Scripting name
Data Type

Label Background

dateForeground
Color

calcBackground
Color

609

SPC Quality

Calc Foreground

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

610

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

calcFont
Font

Chart Properties
Show Primary Chart If true, the primary chart will appear.

Scripting name
Data Type
Show Secondary Chart

showPrimaryChart
boolean

If true, the secondary chart will appear.

Scripting name
Data Type

Right Axis Width

showSecondaryChart
boolean

The width of the right chart axis in pixels.

Scripting name
Data Type

rightAxisWidth
int

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

limitDialogVerticalOffset
int

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

showVerticalGridLines
boolean

Inductive Automation

SPC Quality
Horizontal Grid Line Color

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

Secondary Chart Background

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

611

primaryChartBackground
Color

The background color of the secondary chart.

Scripting name
Data Type

secondaryChartBackground
Color

Show Notes

If true, show the note icon next to the chart point for any samples that have notes
or assignable causes.
Scripting name
showNotes
Data Type
boolean

Note Image

The image to display next to the chart point for any samples that have notes or
assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing If true, allow the user to add and edit notes and assignable causes.

Scripting name
Data Type

enableNoteEditing
boolean

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

Events
Inductive Automation

enableControlLimitEditing
boolean

SPC Quality

612

This component has standard Ignition events.

(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary" or "Secondary"
Data Type

returns
4.4.2.9

String

nothing

Individual and Range Chart

Description
The Individual Moving Range (MR) control chart is used to display SPC results that have a single
measurement for each sample. It does not retrieve SPC results from the SPC module so it must be used
with either the SPC Selector or the SPC Controller components that do. Only SPC results with Individual
and MR SPC Data Format specified will be displayed.

Individual Moving Range Control Chart

Inductive Automation

SPC Quality

613

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count This property represents the number of measurements for each sample in the

SPC results.
Scripting name
Data Type

measurementCount
int

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

Inductive Automation

backgroundColor
Color

noDataMessage
String

SPC Quality

614

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Table Properties
Show Table

If true, the table containing measurement and calculated values will be shown at
the top of the control chart.
Scripting name
showTable
Data Type
boolean

Min Visible Samples

The minimum number of sample to show on the control chart. If

more than the minimum visible samples exist in the SPC results,
then a horizontal scroll bar will appear and allow the user to scroll
back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int

Min Visible Measurements

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be expanded to
match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

rowHeight
int

The background color of the sample date row.

Scripting name
Data Type

dateBackground
Color

Inductive Automation

SPC Quality
Date Foreground

The foreground color of the sample date values.

Scripting name
Data Type

Date Font

The font to display the sample date values.

Scripting name
Data Type

Date Format

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Inductive Automation

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

labelForeground
Color

The font to display the labels.

Scripting name
Data Type

Data Background

labelBackground
Color

The foreground color of the labels.

Scripting name
Data Type

Label Font

dateFormat
String

The background color of the labels.

Scripting name
Data Type

Label Foreground

dateFont
Font

The date formatting pattern to display the sample dates.

Scripting name
Data Type

Label Background

dateForeground
Color

calcBackground
Color

615

SPC Quality

Calc Foreground

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

616

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

calcFont
Font

Chart Properties
Show Primary Chart If true, the primary chart will appear.

Scripting name
Data Type
Show Secondary Chart

showPrimaryChart
boolean

If true, the secondary chart will appear.

Scripting name
Data Type

Right Axis Width

showSecondaryChart
boolean

The width of the right chart axis in pixels.

Scripting name
Data Type

rightAxisWidth
int

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

limitDialogVerticalOffset
int

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

showVerticalGridLines
boolean

Inductive Automation

SPC Quality
Horizontal Grid Line Color

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

Secondary Chart Background

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

617

primaryChartBackground
Color

The background color of the secondary chart.

Scripting name
Data Type

secondaryChartBackground
Color

Show Notes

If true, show the note icon next to the chart point for any samples that have notes
or assignable causes.
Scripting name
showNotes
Data Type
boolean

Note Image

The image to display next to the chart point for any samples that have notes or
assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing If true, allow the user to add and edit notes and assignable causes.

Scripting name
Data Type

enableNoteEditing
boolean

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

Events
Inductive Automation

enableControlLimitEditing
boolean

SPC Quality

618

This component has standard Ignition events.

(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary" or "Secondary"
Data Type

returns
4.4.2.10 P-Chart

String

nothing

Description
The Percentage of Nonconforming Items (p) control chart is used to display SPC results that have
nonconforming counts for each sample. It does not retrieve SPC results from the SPC module so it must
be used with either the SPC Selector or the SPC Controller components that do. Only SPC results with p
chart SPC Data Format specified will be displayed.

P Control Chart

Inductive Automation

SPC Quality

619

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count This property represents the number of measurements for each sample in the

SPC results.
Scripting name
Data Type

measurementCount
int

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

Inductive Automation

backgroundColor
Color

noDataMessage
String

SPC Quality

620

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Table Properties
Show Table

If true, the table containing measurement and calculated values will be shown at
the top of the control chart.
Scripting name
showTable
Data Type
boolean

Min Visible Samples

The minimum number of sample to show on the control chart. If

more than the minimum visible samples exist in the SPC results,
then a horizontal scroll bar will appear and allow the user to scroll
back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int

Min Visible Measurements

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be expanded to
match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

rowHeight
int

The background color of the sample date row.

Scripting name
Data Type

dateBackground
Color

Inductive Automation

SPC Quality
Date Foreground

The foreground color of the sample date values.

Scripting name
Data Type

Date Font

The font to display the sample date values.

Scripting name
Data Type

Date Format

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Inductive Automation

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

labelForeground
Color

The font to display the labels.

Scripting name
Data Type

Data Background

labelBackground
Color

The foreground color of the labels.

Scripting name
Data Type

Label Font

dateFormat
String

The background color of the labels.

Scripting name
Data Type

Label Foreground

dateFont
Font

The date formatting pattern to display the sample dates.

Scripting name
Data Type

Label Background

dateForeground
Color

calcBackground
Color

621

SPC Quality

Calc Foreground

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

622

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

calcFont
Font

Chart Properties
Show Primary Chart

If true, the primary chart will appear.

Scripting name
Data Type

Right Axis Width

showPrimaryChart
boolean

The width of the right chart axis in pixels.

Scripting name
Data Type

rightAxisWidth
int

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

Horizontal Grid Line Color

limitDialogVerticalOffset
int

showVerticalGridLines
boolean

The color of the chart horizontal grid lines.

Scripting name
Data Type

horizontalGridLineColor
Color

Inductive Automation

SPC Quality
Show Horizontal Grid Lines

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

623

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

primaryChartBackground
Color

Show Notes

If true, show the note icon next to the chart point for any samples
that have notes or assignable causes.
Scripting name
showNotes
Data Type
boolean

Note Image

The image to display next to the chart point for any samples that
have notes or assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing

If true, allow the user to add and edit notes and assignable causes.
Scripting name
Data Type

enableNoteEditing
boolean

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

Events
This component has standard Ignition events.
(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
Inductive Automation

enableControlLimitEditing
boolean

SPC Quality

624

parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary".
Data Type

returns
4.4.2.11 NP-Chart

String

nothing

Description
The Number of Nonconforming Items (np) control chart is used to display SPC results that have
nonconforming counts for each sample. It does not retrieve SPC results from the SPC module so it must
be used with either the SPC Selector or the SPC Controller components that do. Only SPC results with
np chart SPC Data Format specified will be displayed.

NP Control Chart

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties

Inductive Automation

SPC Quality

625

SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count This property represents the number of measurements for each sample in the

SPC results.
Scripting name
Data Type

measurementCount
int

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

backgroundColor
Color

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

noDataMessage
String

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

The font to display the no data message.

Scripting name
Data Type

Table Properties
Inductive Automation

noDataForeground
Color

noDataFont
Font

SPC Quality

Show Table

626

If true, the table containing measurement and calculated values will be shown at
the top of the control chart.
Scripting name
showTable
Data Type
boolean

Min Visible Samples

The minimum number of sample to show on the control chart. If

more than the minimum visible samples exist in the SPC results,
then a horizontal scroll bar will appear and allow the user to scroll
back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int

Min Visible Measurements

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be expanded to
match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

The background color of the sample date row.

Scripting name
Data Type

Date Foreground

dateForeground
Color

The font to display the sample date values.

Scripting name
Data Type

Date Format

dateBackground
Color

The foreground color of the sample date values.

Scripting name
Data Type

Date Font

rowHeight
int

dateFont
Font

The date formatting pattern to display the sample dates.

Scripting name
Data Type

dateFormat
String

Inductive Automation

SPC Quality
Label Background

The background color of the labels.

Scripting name
Data Type

Label Foreground

The foreground color of the labels.

Scripting name
Data Type

Label Font

Inductive Automation

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

Chart Properties

calcBackground
Color

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Calc Foreground

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

labelForeground
Color

The font to display the labels.

Scripting name
Data Type

Data Background

labelBackground
Color

calcFont
Font

627

SPC Quality
Show Primary Chart

If true, the primary chart will appear.

Scripting name
Data Type

Right Axis Width

628

showPrimaryChart
boolean

The width of the right chart axis in pixels.

Scripting name
Data Type

rightAxisWidth
int

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

Show Notes

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

showVerticalGridLines
boolean

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

Horizontal Grid Line Color

limitDialogVerticalOffset
int

primaryChartBackground
Color

If true, show the note icon next to the chart point for any samples
that have notes or assignable causes.
Scripting name
showNotes
Data Type
boolean
Inductive Automation

SPC Quality

629

Note Image

The image to display next to the chart point for any samples that
have notes or assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing

If true, allow the user to add and edit notes and assignable causes.
Scripting name
Data Type

enableNoteEditing
boolean

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

enableControlLimitEditing
boolean

Events
This component has standard Ignition events.
(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary".
Data Type

returns
4.4.2.12 U-Chart

String

nothing

Description
The Percentage of Nonconformities (u) control chart is used to display SPC results that have
nonconformities counts for each sample. It does not retrieve SPC results from the SPC module so it
Inductive Automation

SPC Quality

630

must be used with either the SPC Selector or the SPC Controller components that do. Only SPC results
with u chart SPC Data Format specified will be displayed.

U Control Chart

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count This property represents the number of measurements for each sample in the

SPC results.
Scripting name
Data Type

measurementCount
int

Inductive Automation

SPC Quality

631

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

backgroundColor
Color

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

noDataMessage
String

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Table Properties
Show Table

If true, the table containing measurement and calculated values will

be shown at the top of the control chart.
Scripting name
showTable
Data Type
boolean

Min Visible Samples

The minimum number of sample to show on the control chart. If

more than the minimum visible samples exist in the SPC results,
then a horizontal scroll bar will appear and allow the user to scroll
back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int

Inductive Automation

SPC Quality

632

Min Visible Measurements

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be
expanded to match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

The background color of the sample date row.

Scripting name
Data Type

Date Foreground

dateFormat
String

The background color of the labels.

Scripting name
Data Type

Label Foreground

dateFont
Font

The date formatting pattern to display the sample dates.

Scripting name
Data Type

Label Background

dateForeground
Color

The font to display the sample date values.

Scripting name
Data Type

Date Format

dateBackground
Color

The foreground color of the sample date values.

Scripting name
Data Type

Date Font

rowHeight
int

labelBackground
Color

The foreground color of the labels.

Scripting name
Data Type

labelForeground
Color

Inductive Automation

SPC Quality
Label Font

The font to display the labels.

Scripting name
Data Type

Data Background

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

calcBackground
Color

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Calc Foreground

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

calcFont
Font

Chart Properties
Show Primary Chart

If true, the primary chart will appear.

Scripting name
Data Type

Right Axis Width

The width of the right chart axis in pixels.

Scripting name
Data Type

Inductive Automation

showPrimaryChart
boolean

rightAxisWidth
int

633

SPC Quality

634

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

showVerticalGridLines
boolean

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

Horizontal Grid Line Color

limitDialogVerticalOffset
int

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

primaryChartBackground
Color

Show Notes

If true, show the note icon next to the chart point for any samples
that have notes or assignable causes.
Scripting name
showNotes
Data Type
boolean

Note Image

The image to display next to the chart point for any samples that
have notes or assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing

If true, allow the user to add and edit notes and assignable causes.
Scripting name
Data Type

enableNoteEditing
boolean
Inductive Automation

SPC Quality

635

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

enableControlLimitEditing
boolean

Events
This component has standard Ignition events.
(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary".
Data Type

returns
4.4.2.13 C-Chart

String

nothing

Description
The Number of Nonconformities (c) control chart is used to display SPC results that have
nonconformities counts for each sample. It does not retrieve SPC results from the SPC module so it
must be used with either the SPC Selector or the SPC Controller components that do. Only SPC results
with c chart SPC Data Format specified will be displayed.

Inductive Automation

SPC Quality

636

C Control Chart

Through the use of the properties listed below, the appearance and functionality of this component can
modified as desired.
Properties
This component has standard Ignition properties with the addition of the following properties:
Data Properties
SPC Results

Bind this property to the SPC Results property of the SPC Controller or SPC
Selector components. Ther SPC Results contain all the information so that the
control charts can display the results which is not possible with the data set
alone.
Scripting name
spcResults
Data Type
SPCResults

SPC Data

This property holds the SPC data and includes columns for the calculated
values based on the SPC Data Format and selected attribute, control limits and
signals.
Scripting name
spcData
Data Type
Dataset

Measurement Count This property represents the number of measurements for each sample in the

SPC results.
Scripting name
Data Type

measurementCount
int

Inductive Automation

SPC Quality

637

User

This property can optionally be set to override the current user logged in. It is
used when notes or assignable causes are added or modified.
Scripting name
user
Data Type
String

Background Color

The background color.

Scripting name
Data Type

Definition Name

The sample definition to used when building SPC results.

Scripting name
Data Type

No Data Message

backgroundColor
Color

definitionName
String

Text to display if not data is available to show in the control chart.

Scripting name
Data Type

noDataMessage
String

No Data Foreground The foreground color to display the no data message.

Scripting name
Data Type
No Data Font

noDataForeground
Color

The font to display the no data message.

Scripting name
Data Type

noDataFont
Font

Table Properties
Show Table

Min Visible Samples

Inductive Automation

If true, the table containing measurement and calculated values will be shown at
the top of the control chart.
Scripting name
showTable
Data Type
boolean
The minimum number of sample to show on the control chart. If
more than the minimum visible samples exist in the SPC results,
then a horizontal scroll bar will appear and allow the user to scroll
back to earlier samples.
Scripting name
minVisibleSamples
Data Type
int

SPC Quality
Min Visible Measurements

638

The minimum number of measurements to show in the table of the

control chart. If more than the minimum visible measurements exist
in the SPC results, then a vertical scroll bar will appear and allow
the user to through all measurements.
Scripting name
minVisibleMeasurements
Data Type
int

Column Width

The width of the table column for each sample. The charts will be expanded to
match the column width.
Scripting name
columnWidth
Data Type
int

Row Height

The height of the table rows.

Scripting name
Data Type

Date Background

The background color of the sample date row.

Scripting name
Data Type

Date Foreground

dateFormat
String

The background color of the labels.

Scripting name
Data Type

Label Foreground

dateFont
Font

The date formatting pattern to display the sample dates.

Scripting name
Data Type

Label Background

dateForeground
Color

The font to display the sample date values.

Scripting name
Data Type

Date Format

dateBackground
Color

The foreground color of the sample date values.

Scripting name
Data Type

Date Font

rowHeight
int

labelBackground
Color

The foreground color of the labels.

Scripting name
Data Type

labelForeground
Color

Inductive Automation

SPC Quality
Label Font

The font to display the labels.

Scripting name
Data Type

Data Background

The background color of the measurement data values.

Scripting name
Data Type

Data Foreground

calcBackground
Color

The foreground color of the calculated data values.

Scripting name
Data Type

Calc Font

dataFont
Font

The background color of the calculated data values.

Scripting name
Data Type

Calc Foreground

dataForeground
Color

The font to display the measurement values.

Scripting name
Data Type

Calc Background

dataBackground
Color

The foreground color of the measurement data values.

Scripting name
Data Type

Data Font

labelFont
Font

calcForeground
Color

The font to display the calculated values.

Scripting name
Data Type

calcFont
Font

Chart Properties
Show Primary Chart

If true, the primary chart will appear.

Scripting name
Data Type

Right Axis Width

The width of the right chart axis in pixels.

Scripting name
Data Type

Inductive Automation

showPrimaryChart
boolean

rightAxisWidth
int

639

SPC Quality

640

Limit Dialog Horizontal Offset

The horizontal, or x, position to display the set control limit dialog

box.
Scripting name
limitDialogHorizontalOffset
Data Type
int

Limit Dialog Vertical Offset

The vertical, or y, position to display the set control limit dialog box.
Scripting name
Data Type

Vertical Grid Line Color

The color of the chart vertical grid lines.

Scripting name
Data Type

Show Vertical Grid Lines

horizontalGridLineColor
Color

If true, show the horizontal grid lines in the charts.

Scripting name
Data Type

Primary Chart Background

showVerticalGridLines
boolean

The color of the chart horizontal grid lines.

Scripting name
Data Type

Show Horizontal Grid Lines

verticalGridLineColor
Color

If true, show the vertical grid lines in the charts.

Scripting name
Data Type

Horizontal Grid Line Color

limitDialogVerticalOffset
int

showHorizontalGridLines
boolean

The background color of the primary chart.

Scripting name
Data Type

primaryChartBackground
Color

Show Notes

If true, show the note icon next to the chart point for any samples
that have notes or assignable causes.
Scripting name
showNotes
Data Type
boolean

Note Image

The image to display next to the chart point for any samples that
have notes or assignable causes.
Scripting name
noteImage
Data Type
Image

Enable Note Editing

If true, allow the user to add and edit notes and assignable causes.
Scripting name
Data Type

enableNoteEditing
boolean
Inductive Automation

SPC Quality

641

Enable Point Deletion

If true, allow the user to temporarily remove samples from chart.

This is used to remove samples that are known to out of control
before calculating control limits. The sample that have been
removed are not removed from the database and can be restored
by selecting the Restore Points menu item.
Scripting name
enablePointDeletion
Data Type
boolean

Enable Control Limit Editing

If true, allow the user to calculate and set new control limit values.
Scripting name
Data Type

enableControlLimitEditing
boolean

Events
This component has standard Ignition events.
(none)

Methods
showSetLimitPanel(chartName)
Causes the calculate and set control limit dialog to be shown.
parameters

chartName

Which chart to show the control limit dialog for. Available options a
"Primary".
Data Type

returns

Inductive Automation

nothing

String

SPC Quality

4.5

642

Quality OPC Values

The production model is defined in the Ignition designer and contains your production areas, lines and
locations. Runtime access into configuration and current state of the production model is available
through the Production OPC Server. It is added automatically when the SPC Module is installed. When
the production items are added, removed or modified, the changes will be reflected in the Production
OPC Server when the project is saved in the designer.
Below is a part of the values available to read, and in some cases write to, for the demo project.

Dem o OPC Values

Inductive Automation

SPC Quality

4.5.1

643

Using OPC Values_2

The SPC configuration settings and runtime values are available for use in Ignition windows, transaction
groups, scripting, etc. Before values from the Production OPC Server can be used, they must be added
to the Ignition SQLTags. This is done in the designer by selecting the SQLTags Browser and clicking on
the
icon. This will cause the OPC Browser to appear. Next, drill down in the Production node within
the OPC Browser. Drag the desired Production OPC Values over to the SQLTags Browser as depicted
below.

Add Production OPC Server Values to SQLTags

Important:
When writing to OPC values that are related to production model settings, the new value is not retained
upon restarting. This is because production model settings are saved in the Ignition project and is only
saved when done so in the designer.

4.5.2

SPC OPC Value Reference

This references details the OPC values and child folders for node types that appear when browsing the
Production OPC Server. For each property, the Ignition data type is listed and if it is read only. The Ignition
data types correspond to the data types that are available for SQLTags.
Within this reference, the "Read Only" means that the OPC value cannot be written to through the OPC
Production Server. It can only be set in the designer or it is a calculated value. Trying to write to a read
only property will result in an error message being shown.
4.5.2.1

Project

Description
Each project within Ignition has its own production model. The first node(s) under the main Production
node represent the Ignition project(s). Their names are the same as the project name. The image below
represents the OEEDemo project.
Inductive Automation

SPC Quality

644

Project

Inductive Automation

SPC Quality

645

Child Folders
Enterprise

4.5.2.2

One folder will exist for each Enterprise that has been configured in the Ignition
Designer. The folder can be opened to view all values within the enterprise.

Enterprise

Description
The enterprise folder contains some properties associated with the enterprise and a folder for each
production Site within it. The name is the same as the enterprise name that is configured in the designer.
The image below represents the "New Enterprise" of the QualityDemo project.

Enterprise

Child Folders
Site

One folder will exist for each Site that has been configured in the Ignition Designer.
The folder can be opened to view all values within the site.

Control Limits This is the parent folder that holds all of the control limits.

Signals

This is the parent folder that holds all of the signals.

Intervals

This is the parent folder that holds all of the intervals.

Properties

Inductive Automation

SPC Quality

Optionally, this property can be set to a

description for the enterprise. It is not used
by the SPC Module other than for reference.

Description

This reflects the enterprise Enabled

property in the Designer. If the enterprise
Enabled is set to true, then the SPC module
will perform calculations for the enterprise
and all sites, areas, lines and locations
within it. If this property is set to false, then
none of the sites, areas, lines or locations
will have calculations performed.
Name
This reflects the name of the enterprise that
is set in the designer.
Analysis DB Connection Name This reflects the Analysis Database setting
in the MES section in the Ignition Gateway.
Runtime DB Connection Name This reflects the Runtime Database setting
in the MES section in the Ignition Gateway.
Enabled

646

String

Boolean

String
Read Only
String
Read Only
String
Read Only

4.5.2.2.1 Control Limits

Description
The control limits folder contains a folder for each control limit. The name of each folder is the same as
the control limit name that is configured in the designer. The image below represents the "Histogram LCL"
control limit of the QualityDemo project.

Control Lim its

Properties
Kind

The ordinal value of the kind of control chart that the control limit is
associated with. See ControlLimitKindTypes for more information.

int
Read Only

Name

This reflects the name of the control limit that is configured in the
designer.

String
Read Only

4.5.2.2.2 Signals

Description
The signals folder contains a folder for each signal. The name of each folder is the same as the signal
name that is configured in the designer. The image below represents the "Individual Outside" signal of the
QualityDemo project.
Inductive Automation

SPC Quality

647

Out of Control Signals

Properties
The ordinal value of the kind of control
chart that the signal is associated with.
See SignalKindTypes for more
information.
SignalName
This reflects the name of the signal that is
configured in the designer.
SignalAutoEvaluatePeriod
This reflects the ordinal value of the
evaluation time period of the
SignalAutoEvaluateDuration value. See
SignalAutoEvaluatePeriodTypes for
more information.
SignalAutoEvaluateDuration This reflects the duration to use when
automatically evaluating sample data for a
location for this signal.
SignalChartShape
This reflects the ordinal value of the
shape to display in the control charts
when a sample is out of control for this
signal. See SPCChartShapeTypes for
more information.
Kind

int
Read Only

String
Read Only
int
Read Only

int
Read Only
int
Read Only

4.5.2.2.3 Intervals

Description
The quality intervals folder contains a folder for each interval. The name of each folder is the same as the
interval name that is configured in the designer. The image below represents the "Every Value Change"
interval of the QualityDemo project.

Inductive Automation

SPC Quality

648

Sam pling Intervals

Properties
QualityIntervalName

4.5.2.3

This reflects the name of the interval that

is configured in the designer.

String
Read Only

Site

Description
The site folder contains some properties associated with the production site and a folder for each
production area within it. The name is the same as the site name that is configured in the designer. The
image below represents the "Your Site" of the QualityDemo project.

Site

Child Folders
Area

One folder will exist for each area that has been configured in the Ignition Designer.
The folder can be opened to view all values within the area.

Properties

Inductive Automation

SPC Quality

649

Description

Optionally, this property can be set to a description for the

site. It is not used by the OEE Downtime and Scheduling
Module other than for reference.

String

Enabled

This reflects the site Enabled property in the Designer. If the

site Enabled is set to true, then the OEE Downtime and
Scheduling module will perform calculations for the site and
all areas, lines and cells within it. If this property is set to
false, then none of the areas, lines or cells will have
calculations performed.

Boolean

Name

This reflects the name of the site that is set in the designer.

Default Shift 1
Start Time

This reflects the site Default Shift 1 Start Time property in

the Designer. See Site Configuration for more details.

String
Read Only
DateTime
Read Only

Default Shift 2
Start Time

This reflects the site Default Shift 2 Start Time property in

the Designer. See Site Configuration for more details.

DateTime
Read Only

Default Shift 3
Start Time

This reflects the site Default Shift 3 Start Time property in

the Designer. See Site Configuration for more details.

DateTime
Read Only

4.5.2.4

Area

Description
The area folder contains some properties associated with the production area and a folder for each
production line within it. The name is the same as the area name that is configured in the designer. The
image below represents the "Your Area" of the QualityDemo project.

Area

Child Folders
Line

One folder will exist for each Line that has been configured in the Ignition Designer. The
folder can be opened to view all values within the line.

Properties

Inductive Automation

SPC Quality

650

Description

Optionally, this property can be set to a description for the area. It is

not used by the OEE Downtime and Scheduling Module other than for
reference.

String

Enabled

This reflects the site Enabled property in the Designer. If the area
Enabled is set to true, then the OEE Downtime and Scheduling
module will perform calculations for the area and all lines and cell
within it. If this property is set to false, then none of the lines or cells
will have calculations performed.

Boolean

Name

This reflects the name of the area that is set in the designer.

Shift 1
Start Time

The current Shift 1 Start Time time for the production area. If the
associated Shift 1 Start Time property for the area in the designer is
set to Inherit From Parent, this will be the time defined for the parent
production site. See Area Configuration for more details.

String
Read Only
DateTime
Read Only

Shift 2
Start Time

The current Shift 2 Start Time time for the production area. If the
associated Shift 2 Start Time property for the area in the designer is
set to Inherit From Parent, this will be the time defined for the parent
production site. See Area Configuration for more details.

DateTime
Read Only

Shift 3
Start Time

The current Shift 3 Start Time time for the production area. If the
associated Shift 3 Start Time property for the area in the designer is
set to Inherit From Parent, this will be the time defined for the parent
production site. See Area Configuration for more details.

DateTime
Read Only

4.5.2.5

Line

Description
The line folder contains some properties associated with the production line and a folder for each
production location within it. The name is the same as the line name that is configured in the designer.
The image below represents the "Line 1" of the QualityDemo project.

Inductive Automation

SPC Quality

651

Line

Child Folders
Location

One folder will exist for each Location that has been configured under the line in the
Ignition Designer. The folder can be opened to view all values within the location.

Inductive Automation

SPC Quality

652

Properties
Only the properties that may be useful for the SPC module are shown below. See OEE DT Line for more
properties.
Enabled

This reflects the line Enabled property in the Designer. If the line
Enabled is set to true, then the OEE Downtime and Scheduling
module will perform calculations for the all cells within it. If this
property is set to false, then none of the cells will have calculations
performed.

Boolean

Name

This reflects the name of the line that is set in the designer.

String
Read Only

Product Code

The current product code being run on the line. Typically, this is
controlled by the functionality of the operator screen, but it can also
be handled programmatically. It should only be changed when
Enable Run is false.

String

Product Code
Description

The description for the current Product Code.

String
Read Only

Running

This value will be true if a production run is started and production

line is running.

Boolean
Read Only

Sequence No

A number that is 0 at the beginning of a production run and

increments at the beginning of every shift.

Int4
Read Only

Shift

The current shift based on the shift start times configured for the
production line.

Int4
Read Only

Shift 1
Enabled

The current Shift 1 enabled state for the production line. It reflects
the Shift 1 Enabled property for the line in the designer. The initial
value of this property is determined by the Shift 1 Initial Enabled
State property for the production line in the designer. See Line
Configuration for more details. It can be changed from the initial
value.

Boolean

Shift 1
Start Time

The current Shift 1 Start Time time for the production line. If the
associated Shift 1 Start Time property for the line in the designer is
set to Inherit From Parent, this be the time defined for the parent
production area. See Line Configuration for more details.

DateTime
Read Only

Shift 2
Enabled

The current Shift 2 enabled state for the production line. It reflects
the Shift 2 Enabled property for the line in the designer. The initial
value of this property is determined by the Shift 2 Initial Enabled
State property for the production line in the designer. See Line
Configuration for more details. It can be changed from the initial
value.

Boolean

Inductive Automation

SPC Quality

653

Shift 2
Start Time

The current Shift 2 Start Time time for the production line. If the
associated Shift 2 Start Time property for the line in the designer is
set to Inherit From Parent, this be the time defined for the parent
production area. See Line Configuration for more details.

DateTime
Read Only

Shift 3
Enabled

The current Shift 3 enabled state for the production line. It reflects
the Shift 3 Enabled property for the line in the designer. The initial
value of this property is determined by the Shift 3 Initial Enabled
State property for the production line in the designer. See Line
Configuration for more details. It can be changed from the initial
value.

Boolean

Shift 3
Start Time

The current Shift 3 Start Time time for the production line. If the
associated Shift 3 Start Time property for the line in the designer is
set to Inherit From Parent, this be the time defined for the parent
production area. See Line Configuration for more details.

DateTime
Read Only

Work Order

The current work order number for the current production run.

String
Read Only

4.5.2.6

Location

Description
The location folder contains properties associated with the production location. The production location
can reside under a production line or directly under a production area. The name is the same as the
location name that is configured in the designer. The image below represents the Line 1 Quality location
of the QualityDemo project.

Inductive Automation

SPC Quality

654

Location

Inductive Automation

SPC Quality

655

Child Folders
Additional Factors
SQLTag Collectors

Contains all of the additional factor entries that have been configured for the
production location.
Contains all of the tag collector entries that have been configured for the
production location.

Properties
Description

Optionally, this property can be set to a description

for the location. It is not used by the SPC Module
other than for reference.

String

Enabled

If Enabled is set to true, then the SPC module will

perform calculations and enable tag collectors for
the location.

Boolean

Name

String
Read Only
String
Read Only
String
Read Only

Sample Coming Due

This reflects the name of the location that is set in

the designer.
This reflects the product code currently assigned to
this location.
This reflects the reference number currently
assigned to this location. The reference number is
optional and can represent anything that samples
will be tracked by except for the product code.
If true, a sample is coming due for this location.

Sample Due

If true, a sample is due for this location.

Sample Overdue

If true, a sample is overdue for this location.

Sample Waiting Approval

If true, an unapproved sample is waiting to be

approved for this location.
The date and time that the current shift started.
This is used for retrieving results based on a
production day and not days that are split at
midnight.
A number that is 0 at the beginning of a production
run and increments at the beginning of every shift.
The current shift based on the shift start times
configured for the production location.
The current Shift 1 enabled state for the production
location. It reflects the Shift 1 Enabled property for
the location in the designer. The initial value of this
property is determined by the Shift 1 Initial Enabled
State property for the production location in the
designer. It can be changed from the initial value.
The current Shift 1 Start Time time for the
production location. If the associated Shift 1 Start
Time property for the location in the designer is set

Product Code
Reference Number

Sequence Date

Sequence No
Shift
Shift 1
Enabled

Shift 1
Start Time

Inductive Automation

Boolean
Read Only
Boolean
Read Only
Boolean
Read Only
Boolean
Read Only
Date
Read Only
Int4
Read Only
Int4
Read Only
Boolean

DateTime

SPC Quality

Shift 2
Enabled

Shift 2
Start Time

Shift 3
Enabled

Shift 3
Start Time

Signal Out Of Control

Trace Enabled

to Inherit From Parent, this can be the time defined

for the parent production area or line.
The current Shift 2 enabled state for the production
location. It reflects the Shift 2 Enabled property for
the location in the designer. The initial value of this
property is determined by the Shift 2 Initial Enabled
State property for the production location in the
designer. It can be changed from the initial value
The current Shift 2 Start Time time for the
production location. If the associated Shift 2 Start
Time property for the location in the designer is set
to Inherit From Parent, this can be the time defined
for the parent production area or line.
The current Shift 3 enabled state for the production
location. It reflects the Shift 3 Enabled property for
the location in the designer. The initial value of this
property is determined by the Shift 3 Initial Enabled
State property for the production location in the
designer. It can be changed from the initial value.
The current Shift 3 Start Time time for the
production location. If the associated Shift 3 Start
Time property for the location in the designer is set
to Inherit From Parent, this can be the time defined
for the parent production area or line.
If true, at least one signal associated with this
location is out of control.
If true, a product code has been assigned to this
location and is considered as actively processing.

656

Boolean

DateTime

Boolean

DateTime

Boolean
Read Only
Boolean
Read Only

4.5.2.6.1 Additional Factors

Description
The additional factors folder contains a folder for each additional factor within it. The name of each folder
is the same as the additional factor name that is configured in the designer. The image below represents
the "Line 1 Quality" additional factors of the QualityDemo project.

Inductive Automation

SPC Quality

657

Additional Factors

Properties
Factor
Description

Optionally, this property can be set to a

description for the additional factor. It is not used
by the SPC Module other than for reference.

String

Factor
Name

This reflects the name of the additional factor that

is configured in the designer.
This reflects the Factor SQLTag setting that the
additional factor is configured for in the designer.
It is the name of the SQLTag to read the factor
value from.

String
Read Only
String
Read Only

Factor
SQLTag

4.5.2.6.2 Tag Collectors

Description
The SQLTag Collectors folder contains a folder for each tag collector within it. The name of each folder is
the same as the tag collector name that is configured in the designer. The image below represents the
"Line 1 Checkweigher" tag collector of the QualityDemo project.

Inductive Automation

SPC Quality

658

Tag Collectors

Properties
Name

This reflects the name of the tag collector that is

configured in the designer.

String
Read Only

SQLTag Path

This reflects the SQLTag path that is configured

in the designer from which the sample
measurement data is read.

String
Read Only

Enabled

If true, the tag collector will automatically read the

value from the associated tag and create
samples based on the interval.

Boolean

Interval Type

This reflects the sample interval to use with this

tag collector as configured in the designer.

String
Read Only

Interval

This reflects the sample interval value as

configured in the designer. The meaning depends
on the interval type. See Intervals for more
information.
This reflects the control limits that will be
calculated during signal evaluation as configured
in the designer.

Double
Read Only

This reflects the out of control signal(s) to be

evaluated automatically when a new sample is
collected.

String
Read Only

Control Limits

Signals

String
Read Only

Inductive Automation

SPC Quality

4.6

Scripting

4.6.1

Production Location Events

659

The following events are by location, which allows for the changing of default handling samples and
detection of out of control signals by individual location. Individual handling based on the of sample or
other criteria, must be done in the script.
In situations where the default handling does not fit the production environment requirements, these
events are flexible enough to allow a method to implement exactly what is needed.
4.6.1.1

Before Sample Updated Event

Before a new sample is added or an existing sample is updated to the database, any script in this event is
run. This includes samples that have been scheduled with no measurement data. It is provided to allow
for the addition of more information, performing other actions or preventing the saving of the sample.
event properties:
getSample() - Sample
Returns the new or updated sample. (See Sample section more information).
setCancelUpdate(boolean cancelUpdate)
Used to prevent the sample from being added or updated. The default is false, meaning the
sample will be added or updated. It is provided to override the default adding or updating of
samples and should be used with caution.
isCancelUpdate() - boolean
Returns the current state of the cancel update flag.
Example:
#Add 1 to an unrelated SQLTag value
val = system.tag.getTagValue('[Default]Quality\Test\Before Sample Updated')
val = val + 1
system.tag.writeToTag('[Default]Quality\Test\Before Sample Updated', val, 1)
#Get the sample from the event
sample = event.getSample()
#Access the additional factors from the sample
addlFactors = sample.getAllAddlFactors()
if len(addlFactors) > 0:
print "%d additional factors exist." % (len(addlFactors))

4.6.1.2

print "val = %d, sampleUUID = %s" % (val, sample.getSampleUUID())

After Sample Updated Event

After a new sample is added or an existing sample is updated to the database, any script in this event is
run. This includes samples that have been scheduled with no measurement data. It is provided to allow
for the performance of other actions when sample information changes.
event properties:
getSample() - Sample
Inductive Automation

SPC Quality

660

Returns the new or updated sample. (See Sample section more information).
Example:

4.6.1.3

#Add 1 to an unrelated SQLTag value

val = system.tag.getTagValue('[Default]Quality\Test\After Sample Updated')
val = val + 1
system.tag.writeToTag('[Default]Quality\Test\After Sample Updated', val, 1)
Sample Approval Updated Event

After the sample approval state has been updated, any script in this event is run. This includes samples
that are set for automatic approval. It is provided to allow for the performance of other actions when
sample approval state changes.
event properties:
getSample() - Sample
Returns the sample for which the approval state changed. (See Sample section more
information).
isApproval() - boolean
Returns true if the sample has been approved.
isUnapproval() - boolean
Returns true if the sample has been unapproved.
Example:

4.6.1.4

#Add 1 to an unrelated SQLTag value

val = system.tag.getTagValue('[Default]Quality\Test\Sample Approval Updated')
val = val + 1
system.tag.writeToTag('[Default]Quality\Test\Sample Approval Updated', val, 1)
Sample Coming Due Event

When a sample due state changes to COMING_DUE, any script in this event is run. It is provided to allow
for the performance of other actions, such as alerts, when sample is coming due.
event properties:
getSample() - Sample
Returns the sample that just became due. (See Sample section more information).
getState() - SampleDueStateTypes
Returns the current sample due state (See Sample Due State Types for more information).
Example:
4.6.1.5

Sample Due Event

When a sample due state changes to DUE, any script in this event is run. It is provided to allow for the
performance of other actions, such as alerts, when sample is due.
event properties:
getSample() - String
Returns the sample that just became due. (See Sample section more information).
getState() - SampleDueStateTypes
Returns the current sample due state (See Sample Due State Types for more information).
Inductive Automation

SPC Quality

Example:
4.6.1.6

Sample Interval Event

Evaluates the sample interval and determines when to create a new sample.
event properties:
getDefUUID() - String
Returns the definition UUID for this sample.
getInterval() - Double
Returns the defined interval of this sample .
getDuration() - Double
Returns the number of minutes needed to take a sample.
getTag() - String
Returns the tag associated with this sample.
getComingDueMin() - Double
getOverDueMin() - Double
getSecSinceLastSampleScheduled() - Integer
Returns the seconds since the last sample was scheduled .
getSecSinceLastSampleTaken() - Integer
Returns the seconds since the last sample was taken.
getProductCode() - String
Returns the product code associated with this sample.
getRefNo() - String
Returns the reference number associated with this sample.
getTraceEnabled() - Boolean
getTraceStartedAt() - Date
getElapsedSeconds() - Integer
Returns the .
getTraceEndedAt() - Date
getSequenceDate() - Date
Inductive Automation

661

SPC Quality

662

Returns the sequence date of the sample. Sequence date is the date representing the start of the
current shift.
getSequenceNo() - Integer
Returns the sequence number of the sample. Sequence number is the sequential number of
shifts from the start of the production run.
getShift() - Integer
Returns the shift number.
getValueChangeCount() - Integer
Returns the number of time the associated value has changed.
getValueChangedTimeStamp() - Date
Returns the date time the value changed.
getValue() - Object
Returns the value of the sample.

isTracedStartedEvent() - Boolean
isTracedEndedEvent() - Boolean
isShiftChangeEvent() - Boolean
getCreateSample() - Boolean
setCreateSample(createSample Boolean)
getScheduleStart() - Date
setScheduleStart(Date)
getScheduleFinish() - Date
setScheduleFinish(Date)
getRefresh() - Boolean

Inductive Automation

SPC Quality

663

setRefresh(refresh Boolean)
4.6.1.7

Sample Overdue Event

When a sample due state changes to OVERDUE, any script in this event is run. It is provided to allow for
the performance other actions, such as alerts, when sample is overdue.
event properties:
getSample() - Sample
Returns the sample that just became due. (See Sample section more information).
getState() - SampleDueStateTypes
Returns the current sample due state (See Sample Due State Types for more information).
Example:
4.6.1.8

Sample Waiting Approval Event

When a sample due state changes to WAITING_APPROVAL, any script in this event is run. It is provided
to allow for the performance of other actions, such as alerts, when sample is awaiting approval.
event properties:
getSample() - Sample
Returns the sample that just became due. (See Sample section more information).
getState() - SampleDueStateTypes
Returns the current sample due state (See Sample Due State Types for more information).
Example:
4.6.1.9

Signals Evaluated Event

When sample data changes, all of the out of control signals associated with it will be evaluated. After
each attribute for each definition has been evaluated, any script in this event is run. It is provided to allow
for special handling to override out of control conditions as described below. A preferred alternative is to
implement the desired results in a Interval (See Intervals for more information).
event properties:
getDefUUID() - String
Returns the definition UUID that was evaluated.. (See Sample Definition section more
information).
setIgnoreOutOfControl(boolean ignoreOutOfControl)
Used to override and ignore an out of control condition.
setForceOutOfControl(boolean forceOutOfControl)
Used to force an out of control condition.
getEvaluationResults() - List<SignalEvaluationResults>
Returns a list of evaluation results. When sample data is updated for a location - sample
definition combination, all of the selected signals are evaluated. This occurs for each attribute
within the sample definition.

Inductive Automation

SPC Quality

664

Example:
If sample definition viscosity has an allowable location processing, has two attributes of cold
viscosity and temperature, and signal rule 1 and signal rule 2 are selected, then when a sample is
added or updated, cold viscosity for signal rule 1, cold viscosity for signal rule 2, temperature for
signal rule 1 and temperature for signal rule 2 are all evaluated. The outcome for each combination
is a item within the evaluation results returned from the getEvaluationResults() function.
4.6.1.10 Signal Evaluation Results

This object holds the evaluation results for a attribute signal combination.
event properties:
getSignalName() - String
Returns the name of the signal associated with this result.
getAttributeName() - String
Returns the name of the attribute associated with this result.
getViolatingSampleDate() - Date
Returns the date of the most recent sample that is in violation of the signal.
getLastSampleDate() - Date
Returns the date of the last approved sample. This can be used in combination to determine if
the last approved sample caused the signal violation.
isSignalViolation() - boolean
Returns true if the signal - attribute combination are in violation.
isEvaluationError() - boolean
Returns true if a error occurred during the signal evaluation.
hasMessage() - boolean
Returns true if a message exists.
getMessage() - String
Returns textual description of error encountered during the signal evaluation.
Example:
4.6.1.11 Signal Out of Control Event

When sample data changes, all of the out of control signals associated with it will be evaluated. If an out
of control signal changes from In Control to Out of Control, any script in this event is run. It is provided
to allow for the performance of other actions, such as alerts, when an out of control condition occurs.
event properties:
getDefUUID() - String
Returns the definition UUID associated with this out of control event. (See Sample Definition
section more information).
getEvaluationResults() -SignalEvaluationResults
Returns a single evaluation result of the signal - attribute combination that transitioned from in
control to out of control.
Inductive Automation

SPC Quality

665

4.6.1.12 Signal in Control Event

When sample data changes, all of the out of control signals associated with it will be evaluated. If an out
of control signal changes from Out of Control to In Control, any script in this event is run. It is provided
to allow for the performance of other actions, such as alerts, when an out of control condition no longer
exists.
event properties:
getDefUUID() - String
Returns the definition UUID associated with this in control event. (See Sample Definition section
more information).
getEvaluationResults() -SignalEvaluationResults
Returns a single evaluation result of the signal - attribute combination that transitioned from out
of control to in control.
4.6.1.13 Sample Due State Types

UNKNOWN
COMING_DUE
DUE
OVERDUE
WAITING_APPROVAL:

4.6.2

Object Reference

4.6.2.1

Sample

The sample object holds all of the information associated with one sample.
properties:
getDefUUID() - String
Returns the definition UUID associated with this sample. (See Sample Definition object for more
information).
getSampleUUID() - String
Returns the UUID assigned to this sample. A UUID is a universally unique identifier that, once
assigned to a sample, will never change. It is also unique in that no two samples will have the
same UUID.
getEnterprise() - String
Returns the enterprise associated with this sample.
setEnterprise(String enterprise)
Sets the enterprise associated with this sample.
getSite() - String
Returns the physical production facility associated with this sample.
setSite(String site)
Sets the physical production site associated with this sample.
getArea() - String
Returns the production area associated with this sample.
Inductive Automation

SPC Quality

666

setArea(String area)
Sets the production area associated with this sample.
getLine() - String
Returns the production line associated with this sample. This will be blank if the location the
sample is taken is in a production area and not on a production line.
setLine(String line)
Sets the production line associated with this sample.
getLocation() - String
Returns the location associated with this sample.
setLocation(String location)
Sets the production location associated with this sample.
getLocationPath() - String
Returns the full location path, including enterprise, site, area, line and location, associated with
this sample.
setLocationPath(String locationPath)
Sets the enterprise, site, area, line and location from the locationPath parameter.
getProductCode() - String
Returns the product code associated with this sample. This is optional and may not apply if
tracking quality by product code is not being used for the associated sample definition.
setProductCode(String productCode)
Sets the product code associated with this sample.
getRefNo() - String
Returns the reference number associated with this sample. This is optional and can be used to
track information like batch number, lot number, etc. Additional factors can also be used to
track information.
setRefNo(String refNo)
Sets the reference number associated with this sample.
getScheduledStart() - Calendar
Returns the date and time that this sample is scheduled to be taken. For automatic samplings,
this value does not apply and will be equal to None.
setScheduledStart(Calendar scheduleStart)\
Sets the date and time that this sample is scheduled to be taken.
calcScheduledFinish()
Based on the scheduled start date and time and the duration of time to take this sample,
calculates the date and time this sample is scheduled to be complete. The getScheduledFinish
() value is updated after calling this function. The duration of time required to take a sample is
defined in the sample definition. For automatic samplings, this value does not apply.
Inductive Automation

SPC Quality

667

getScheduledFinish() - Calendar
Returns the date and time that taking this sample is scheduled to be complete. For automatic
samplings, this value does not apply and will be equal to None.
setScheduledFinished(Calendar scheduleFinish)
Sets the date and time that this sample is scheduled to be completed.
getSampleTakenDateTime() - Calendar
Returns the date and time that this sample was taken.
setSampleTakenDateTime(Calendar sampleTakenDateTime)
Sets the date and time that this sample was taken.
getEntryDateTime() - Calendar
Returns the date and time that this sample was entered.
setEntryDateTime(Calendar entryDateTime)
Sets the date and time that this sample was entered.
getShift() - int
Returns the shift the sample was taken.
setShift(int shift)
Sets the shift the sample was taken.
getSequenceDate() - Calendar
Returns the date and time that the shift the sample was taken during started.
setSequenceDate(Calendar sequenceDate)
Sets the date and time that the shift the sample was taken during started.
getApproved() - boolean
Returns true if this sample has been approved. Depending on the settings in the sample
definition, samples may be automatically or manually approved.
setApproved(boolean approved)
Set to true to approve this sample.
getSampleTakenBy() - String
Returns the persons name who was responsible for taking the sample. By default, this is the
person who is logged in when the sample is entered. For automatically recorded samples, this
will be Auto.
setSampleTakenBy(String sampleTakenBy)
Sets the persons name who was responsible for taking the sample.
getApprovedBy() - String
Returns the persons name who approved this sample. For automatically recorded samples,
this will be Auto.
Inductive Automation

SPC Quality

668

setApprovedBy(String approvedBy)
Sets the persons name who approved this sample.
getApprovedDateTime() - Calendar
Returns the date and time that this sample was approved. For automatically approved samples,
this will be the same as the getEntryDateTime() value.
setApprovedDateTime(Calendar approvedDateTime)
Sets the date and time that this sample was approved.
getTag() - String
Returns the optional tag value. This is typically used to assign ownership of which department
has the responsibility to take this sample.
setTag(String tag)
Sets the tag value. This is typically used to assign ownership of which department has the
responsibility to take this sample.
getNote() - String
Returns the note associated with this sample. This is the note that may have been entered
when the sample was entered. Even though this note can be viewed on the control charts or in
analysis, it is not the same as the attribute note entered on the control charts.
setNote(String note)
Sets the note associated with this sample.
getSampleDefinition() - SampleDefinition
Returns the sample definition associated with this sample. (See Sample Definition object for
more information.)
setSampleDefinition(SampleDefinition definition)
Sets the sample definition associated with this sample. (See Sample Definition object for more
information.)
isNew() - boolean
Returns true if this is a newly created sample.
isModified() - boolean
Returns true if any properties of this sample have been modified.
attribute properties:
getAttributeDataType(String attrName) - AttributeDataType
Returns the attribute data type object for the specified attribute name. The attribute data type
information is contained in the sample definition and cannot be changed directly in the sample
object.
getAttributeDefaultValue(String attrName) - Object
Returns the default value for the specified attribute name. The attribute default value is
contained in the sample definition and cannot be changed directly in the sample object.
getAttributeMinValue(String attrName) - Object
Inductive Automation

SPC Quality

669

Returns the minimum value for the specified attribute name. The attribute minimum value is
contained in the sample definition and cannot be changed directly in the sample object.
getAttributeMaxValue(String attrName) - Object
Returns the maximum value for the specified attribute name. The attribute maximum value is
contained in the sample definition and cannot be changed directly in the sample object.
measurement properties:
getAllMeasurements() - List<SampleData>
Returns the measurements associated with this sample. If a sample has been scheduled but
the measurement data has not been recorded, the measurement entries will still exist. In this
case, use the sampleDataExists() property to determine if the measurement data has been
entered.
isDataModified() - boolean
Returns true if any measurement values have been modified.
isSampleDataValid() - boolean
Returns true if all of the measurement values are valid.
sampleDataExists() - boolean
Returns true if sample data has been entered.
getSampleData(int measNo, String attrName) - SampleData
Returns SampleData item for the specified measurement number and attribute.
getSampleDataValue(int measNo, String attrName) - String
Returns a measurement value as a string for the specified measurement number and attribute
name.
setSampleData(int measNo, String attrName, String value) - boolean
Sets a measurement value as a string for the specified measurement number and attribute
name. Returns true if successful, otherwise returns false.
isSampleDataValid() - boolean
Returns true if the measurements have been entered and are valid.
additional factor properties:
getAllAddlFactors() - List<SampleAdditionalFactor>
Returns the list of additional factor values associated with this sample.
getAddlFactor(String factorName) - SampleAdditionalFactor
Returns the additional factor object specified by the factorName parameter and associated with
this sample. Use this function to get the SampleAdditionalFactor object that can be used to
change the value of the additional factor.
4.6.2.2

Sample Data

The sample object holds a sample data object for each attribute and measurement. When a sample
object is created, it automatically creates a sample data object based on the sample definition.
For example: If sample definition viscosity has two attributes of cold viscosity and temperature and is
Inductive Automation

SPC Quality

670

configured for 5 measurements, then the sample will contain 10 sample data objects. Five
measurements for cold viscosity and five measurements for temperature.
properties:
getSampleUUID() - String
Returns the sample UUID that this sample data object belongs to.
getAttributeName() - String
Returns the attribute name this sample data object is associated with.
getMeasNo() - int
Returns the measurement number this sample data object is associated with.
getAttrDataType() - AttributeDataType
Returns attribute data type of this sample data object. This is automatically set when the
sample is created and is based on the sample definition.
getDefaultValue() - Object
Returns the default value based on the attribute this sample data object is associated with. This
is automatically set when the sample is created and is based on the sample definition.
getMinValue() - Object
Returns the minimum value based on the attribute this sample data object is associated with.
This is automatically set when the sample is created and is based on the sample definition.
getMaxValue() - Object
Returns the maximum value based on the attribute this sample data object is associated with.
This is automatically set when the sample is created and is based on the sample definition.
getAttrValue() - Object
Returns the data value for this sample data object.
getAttrValueAsString() - String
Returns the value for this sample data object as a string.
setAttrValue(Object attrValue)
Sets the value for this sample data object. If the attrValue parameter is not the correct data
type, an attempt to convert it to the correct data type is performed before it is set.
isValueValid() - boolean
Returns true if the value of this sample data object has been set and is between minimum and
maximum values.
isModified() - boolean
Returns true if the value of this sample data object has been modified.
4.6.2.3

Attribute Data Type

The attribute data type object contains the available data types of a sample attribute.
Available data types:
INTEGER
Inductive Automation

SPC Quality

671

Attribute can contain positive or negative numeric values with no fractions. It has a
minimum value of -2,147,483,648 and a maximum value of 2,147,483,647 (inclusive).
REAL
Attribute can contain double-precision 64-bit IEEE 754 floating point values.
BOOLEAN
Attribute can contain a true or false value.
INSPECTED_COUNT
Attribute can contain a counting number (1, 2, 3, 4, ) and represents a number of items
inspected for a attribute samples. This attribute data type is recognized and required by the
p, np, c and u control charts.
NONCONFORMING_COUNT
Attribute can contain a counting number (1, 2, 3, 4, ) and represents a number of
nonconforming items (defective items) for a attribute samples. This attribute data type is
recognized and required by the p and np control charts.
NONCONFORMITY_COUNT
Attribute can contain a counting number (1, 2, 3, 4, ) and represents the number of
nonconformities items that have (deformities) for a attribute samples. This attribute data
type is recognized and required by the c and u control charts.
properties:
getText() - String
Returns the user friendly localized text for the attribute data type.
intToType(int ordinal) - AttributeDataType
Returns the attribute data type object for the ordinal value specified.
dataTypeToType(DataType dataType) - AttributeDataType
Returns the attribute data type object for the Ignition data type specified. For more information
about DataType, see the Ignition documentation.
getJavaType() - Class
Returns the java data type.
isNumeric() - boolean
Returns true if the attribute data type handles numbers.
isLogical() - boolean
Returns true if the attribute data type is boolean.
convert(Object attrValue) - Object
Returns value in the true java data type for the type of data this attribute data type represents.
4.6.2.4

Sample Additional Factor

The sample additional factor object holds all of the information associated with one sample.
properties:
getName() - String
Inductive Automation

SPC Quality

672

Returns the name of this additional factor.

getDataType() - DataType
Returns the data type of this additional factor. See DataType in the Ignition documentation for
more information.
getValue() - Object
Returns the value for this additional factor.
updateValue(Object value, Date recordDateTime)
Updates the value and the required date and time that is being record for this additional factor.
getRecordDateTime() - Date
Returns the date and time the value was recorded for this additional factor.
isModified() - boolean
Returns true if this additional factor has been modified.
4.6.2.5

Sample Definition

The sample definition object holds all of the information defining a type of sample. A sample definition
specifies the attributes to collect, the locations where sample data is collected from, the control limits that
apply, and the signals that apply.
When samples are created, they are based on a sample definition. And when sample measurement
values are recorded, the sample definition is used to validate the measurement values. Other operations
also refer back to the sample definition such as automatic scheduling of samples, auto evaluation of
signals, etc.
properties:
getDefUUID() - String
Returns the UUID assigned to this sample definition. A UUID is a universally unique identifier
that, once assigned to a sample definition, will never change. It is automatically generated
when a sample definition is created and is unique in that no two samples definitions will have
the same UUID.
getName() - String
Returns the name of this sample definition.
setName(String name)
Sets the name used for this sample definition. It is recommended that once samples have
been created using this name, it should not be changed.
getDescription() - String
Returns the description of this sample definition.
setDescription() - String
Sets the description of this sample definition.
getEnabled() - boolean
Returns true if sample definition is enabled.
setEnabled(boolean enabled)
Inductive Automation

SPC Quality

673

Sets sample definition enabled state.

getMeasurementCount() - int
Returns the number of measurements that this sample definition is configured for.
setMeasurementCount(int measurementCount)
Sets this number of measurement to be used when creating samples based on the sample
definition.
getIntervalType() - String
Returns the default interval type for automatically scheduled samples based on this sample
definition. Allowed locations that belong to this sample definition are initialized with this default
interval type. The return value must match those configured on the Quality tab for the
enterprise in the Sample Interval list.
setIntervalType(String intervalType)
Sets the default interval type for automatically scheduled samples. Allowed locations that
belong to this sample definition are initialized with this default interval type. The return value
must match those configured on the Quality tab for the enterprise in the Sample Interval list.
getInterval() - double
Returns the default interval for automatically scheduled samples based on this sample
definition. Allowed locations that belong to this sample definition are initialized with this default
interval. The units are defined by the Interval type defined for this sample definition.
setInterval(double interval)
Sets the default interval for automatically scheduled samples. Allowed locations that belong to
this sample definition are initialized with this default interval. The units are defined by the
Interval type defined for this sample definition.
getAutoApprove() - boolean
Returns the default auto approve samples setting for this sample definition. Allowed locations
that belong to this sample definition are initialized with this default setting.
setAutoApprove(boolean autoApprove)
Sets the default auto approve samples setting for this sample definition. Allowed locations that
belong to this sample definition are initialized with this default setting.
getComingDueMin() - double
Returns the default coming due minutes setting for this sample definition. Allowed locations
that belong to this sample definition are initialized with this default setting. The value represents
the number of minutes required before a sample is due until the sample is considered coming
due. For automatically scheduled samples, they are created prior to actual due time by the
number of minutes of this setting.
setComingDueMin(double comingDueMin)
Sets the default coming due minutes setting for this sample definition. Allowed locations that
belong to this sample definition are initialized with this default setting. The value represents the
number of minutes required before a sample is due until the sample is considered coming due.
For automatically scheduled samples, they are created prior to actual due time by the number
of minutes of this setting.
Inductive Automation

SPC Quality

674

getOverdueMin() - double
Returns the default overdue minutes setting for this sample definition. Allowed locations that
belong to this sample definition are initialized with this default setting. The value represents the
number of minutes required after a sample is due until the sample is considered overdue.
setOverdueMin(double overdueMinutes)
Sets the default overdue minutes setting for this sample definition. Allowed locations that
belong to this sample definition are initialized with this default setting. The value represents the
number of minutes required after a sample is due until the sample is considered overdue.
isModified()
Returns true if this sample definition has been modified.
isNew()
Returns true if this sample definition is new.
attribute properties:
addAttribute(SampleDefinitionAttribute attribute) - String
Adds a new attribute defined in the attribute parameter. Any error messages are returned,
otherwise an empty string is returned.
removeAttribute(SampleDefinitionAttribute attribute) - String
Removes the attribute defined in the attribute parameter. Instead of attributes being
permanently removed, thier enabled flag is set to false. Any error messages are returned,
otherwise an empty string is returned.
removeAttribute(int index) - String
Removes the attribute defined in the index parameter. Instead of attributes being permanently
removed, thier enabled flag is set to false. Any error messages are returned, otherwise an
empty string is returned.
removeAttribute(String name) - String
Removes the attribute defined in the name parameter. Instead of attributes being permanently
removed, thier enabled flag is set to false. Any error messages are returned, otherwise an
empty string is returned.
clearAttributes()
All attributes contained in this sample definition are removed. Instead of the attributes being
permanently removed, thier enabled flag is set to false.
getAttribute(String name) - SampleDefinitionAttribute
Returns the attribute with the same name as the name parameter.
getAllAttribute() - List<SampleDefinitionAttribute>
Returns a list of all attributes associated with this sample definition. This function will return
enabled and disabled attributes.
getEnabledAttributes() - List<SampleDefinitionAttribute>
Returns a list of all attributes associated with this sample definition. This function will return
only enabled attributes.
Inductive Automation

SPC Quality

675

attributeExists(SampleDefinitionAttribute attribute) - boolean

Returns true if the attribute specified in the parameter already exists for this sample definition.
True will also be returned for disabled attributes.
allowed location properties:
addAllowedLocation(SampleDefinitionLocation location) - String
Adds a new allowed location defined in the location parameter. By adding an allowed location
to this sample definition, this type of sample will appear as a option for the location and the real
time location will be saved along with associated samples. For example, shift, product code,
ref No and additional factor information is saved along with the sample data. Any error
messages are returned, otherwise an empty string is returned.
removeAllowedLocation(SampleDefinitionLocation location) - String
Removes the allowed location defined in the location parameter. Allowed locations are
permanently removed but can be added back. SPC data is not lost and will appear in the
control charts and analysis. Any error messages are returned, otherwise an empty string is
returned.
removeAllowedLocation(int index) - String
Removes the allowed location defined in the index parameter. Allowed locations are
permanently removed but can be added back. SPC data is not lost and will appear in the
control charts and analysis. Any error messages are returned, otherwise an empty string is
returned.
removeAllowedLocation(String locationName) - String
Removes the allowed location defined in the locationName parameter. Allowed locations are
permanently removed but can be added back. SPC data is not lost and will appear in the
control charts and analysis. Any error messages are returned, otherwise an empty string is
returned.
clearAllowedLocations()
All allowed locations contained in this sample definition are removed. Allowed locations are
permanently removed but can be added back. SPC data is not lost and will appear in the
control charts and analysis.
getAllowedLocation(String name) - SampleDefinitionLocation
Returns the allowed location with the same name as the name parameter.
getAllAllowedLocations(boolean includeRemoved) - List<SampleDefinitionLocation>
Returns a list of all allowed locations associated with this sample definition. If the
includeRemoved parameter is true, the results will include removed allowed locations that
have not been committed by saving the sample definition.
allowedLocationExists(SampleDefinitionLocation location) - boolean
Returns true if the allowed location specified in the parameter already exists for this sample
definition. True will also be returned for allowed locations that have been removed, but not
committed by saving the sample definition.
control limit properties:
addControlLimit(SampleDefinitionControlLimit controlLimit) - String
Inductive Automation

SPC Quality

676

Adds a new control limit defined in the controlLimit parameter. By adding a control limit to this
sample definition, it will show as an option in the control charts and may also be used when
evaluating signals. The controlLimit parameter must be a valid control limit that appears in the
enterprise production item. Any error messages are returned, otherwise an empty string is
returned.
removeControlLimit(SampleDefinitionControlLimit controlLimit) - String
Removes the control limit defined in the controlLimit parameter. Any error messages are
returned, otherwise an empty string is returned.
removeControlLimit(int index) - String
Removes the control limit defined in the index parameter. Any error messages are returned,
otherwise an empty string is returned.
removeControlLimit(String controlLimitName) - String
Removes the control limit defined in the controlLimitName parameter. Any error messages are
returned, otherwise an empty string is returned.
clearControlLimits()
All control limits contained in this sample definition are removed.
getControlLimit(String name) -SampleDefinitionControlLimit
Returns the control limit that has the same name as the name parameter.
getAllControlLimits() - List<SampleDefinitionControlLimit>
Returns all control limits that have been selected for this sample definition.
getAllAllowedLocations(boolean includeRemoved) - List<SampleDefinitionLocation>
Returns a list of all allowed locations associated with this sample definition. If the
includeRemoved parameter is true the results will include removed allowed locations that have
not been committed by saving the sample definition.
controlLimitExists(SampleDefinitionControlLimit controlLimit) - boolean
Returns true if the control limit specified in the parameter already exists for this sample
definition.
signal properties:
addSignal(SampleDefinitionSignal signal) - String
Adds a new signal defined in the signal parameter. By adding a signal to this sample definition,
it will show as an option in the control charts and may also be automatically evaluated. The
signalparameter must be a valid signal that appears in the enterprise production item. Any
error messages are returned, otherwise an empty string is returned.
removeSignal(SampleDefinitionSignal signal) - String
Removes the signal defined in the signal parameter. Any error messages are returned,
otherwise an empty string is returned.
removeSignal(int index) - String
Removes the signal defined in the index parameter. Any error messages are returned,
otherwise an empty string is returned.
Inductive Automation

SPC Quality

677

removeSignal(String signalName) - String

Removes the signal defined in the signalNameparameter. Any error messages are returned,
otherwise an empty string is returned.
clearSignals()
All signals contained in this sample definition are removed.
getSignal(String name) - SampleDefinitionSignal
Returns the signal that has the same name as the name parameter.
getAllSignals() - List<SampleDefinitionSignal>
Returns all signals that have been selected for this sample definition.
signalExists(SampleDefinitionSignal signal) - boolean
Returns true if the signal specified in the parameter already exists for this sample definition.
4.6.2.6

Sample Definition Attribute

The sample definition attribute object holds all of the information defining an attribute used in samples. A
sample definition attribute specifies the name, data type, default value and more for a single attribute that
resides in a sample definition.
properties:
getID() - int
Returns the database created ID for this attribute.
getParent() - SampleDefinition
Returns the sample definition that this attribute is a child of.
getNew() - SampleDefinitionAttribute
Returns a new sample definition attribute instance.
getName() - String
Returns the name of this attribute.
setName(String name)
Sets the name used for this attribute. It is recommended that once samples have been created
using this name, it should not be changed.
getDescription() - String
Returns the description of this attribute.
setDescription() - String
Sets the description of this attribute.
getEnabled() - boolean
Returns true if this attribute is enabled. If an attribute is disabled, it will not appear during
sample entry. Based on the value of the included disabled attributes property on the SPC
Selector component, disabled attributes will not show on the control charts.
setEnabled(boolean enabled)
Inductive Automation

SPC Quality

678

Sets sample definition enabled state.

getRequired() - boolean
Returns true if this attribute is required while entering samples. If an attribute is required, a
value must be entered before the sample will be saved.
setRequired(boolean enabled)
Sets this attribute required state. If an attribute is required, a value must be entered before the
sample will be saved.
getDatatype() - AttributeDataType
Returns the attribute data type for this attribute. See Attribute Data Type for more information.
setDatatype(AttributeDataType dataType)
Sets this attributes data type. See Attribute Data Type for more information.
getFormat() - String
Returns the format for this attribute. The format is used to verify formatting values on the
control charts and that entered data is correctly formatted. See Attribute Data Type for more
information.
setFormat(String format)
Sets this attributes format. The format is used to verify formatting values on the control charts
and that entered data is correctly formatted.
Format strings consist of one or more of the characters shown in the table below. For
example: the format string ##.0 will round to show one decimal place. Search java
DecimalFormat for more information.
Symbol

Description

A digit. absent digits show as zero

A digit, zero shows as absent

Placeholder for decimal separator

Placeholder for grouping separator

Separates mantissa and exponent for exponential formats

Separates formats

Default negative prefix

Multiply by 100 and show as percentage

Multiply by 1000 and show as per mille

Currency sign; replaced by currency symbol; if doubled,

replaced by international currency symbol; if present in a
pattern, the monetary decimal separator is used instead of
the decimal separator

Any other characters can be used in the prefix or suffix

'

Used to quote special characters in a prefix or suffix

Inductive Automation

SPC Quality

Example format strings:

Value

Pattern

Output

123456.789

###,###.###

123,456.789

123456.789

###.##

123456.79

123.78

000000.000

000123.780

12345.67

$###,###.###

$12,345.67

12345.67

\u00A5###,###.###

12,345.67

679

getDefaultValue() - Object
Returns the default value for this attribute. If this optional default value exists, the samples
measurement values associated with this attribute are automatically set to this value when a
sample is created.
setDefaultValue(Object defaultValue)
Sets the default value for this attribute. If this optional default value exists, the samples
measurement values associated with this attribute are automatically set to this value when a
sample is created.
getMinValue() - Object
Returns the minimum value for this attribute. If this optional minimum value exists, the
samples measurement values associated with this attribute are required to be greater than or
equal to this value.
setMinValue(Object minValue)
Sets the minimum value for this attribute. If this optional minimum value exists, the samples
measurement values associated with this attribute are required to be greater than or equal to
this value.
getMaxValue() - Object
Sets the maximum value for this attribute. If this optional maximum value exists, the samples
measurement values associated with this attribute are required to be less than or equal to this
value.
setMaxValue(Object maxValue)
Sets the maximum value for this attribute. If this optional maximum value exists, the samples
measurement values associated with this attribute are required to be less than or equal to this
value.
isModified()
Returns true if this attribute definition has been modified.
isNew()
Returns true if this attribute definition is new.

Inductive Automation

SPC Quality
4.6.2.7

680

Sample Definition Location

The sample definition location object holds all of the information defining a location that samples are taken
from. A sample definition location may specify the interval to schedule samples and various due time
values. Be sure not to confuse a production location with the sample definition location object. The
sample definition location object defines a production location that samples for a sample definition can be
taken from.
When using the term Location within the SPC module, it refers to a virtual location where actual samples
are taken. For example, if a sample bottle is taken from packaging line 1 and is tested in the lab for color,
then the location is packaging line 1. In addition the the lab taking samples from this location, the operator
can take samples to test labels. The tag property is used to define the ownership of who is responsible to
take a sample.
properties:
getID() - int
Returns the database created ID for this sample definition location. Note, this is not the same
as the production location ID.
getNew(int locationID, String name) - SampleDefinitionLocation
Returns a new sample definition location instance for the production location specified by the
locationID parameter. The new instance name is specified by the name parameter.
getLocationID() - int
Returns the database created ID for the production location that this sample definition location
is associated with. Note, this is the same as the production location ID.
getParent() - SampleDefinition
Returns the sample definition that this location is a child of.
getName(String name)
Returns the name of the production location associated with this sample definition location.
This name also appears as the name for this sample definition location.
getEnabled() - boolean
Returns true if this sample definition location is enabled. If disabled, samples will not be
automatically scheduled or appear in sample definition selection lists for the production
location.
setEnabled(boolean enabled)
Sets sample definition location enabled state. If disabled, samples will not be automatically
scheduled or appear in sample definition selection lists for the production location.
getIntervalType() - String
Returns the interval type for automatically scheduling samples for this location. The return
value must match those configured on the Quality tab for the enterprise in the Sample Interval
list.
setIntervalType(String intervalType)
Sets the interval type for automatically scheduling samples for this location. The intervalType
value must match those configured on the Quality tab for the enterprise in the Sample Interval
list.
Inductive Automation

SPC Quality

681

getInterval() - double
Returns the interval for automatically scheduling samples for this location. The units are
defined by the Interval type defined for this sample definition.
setInterval(double interval)
Sets the interval for automatically scheduling samples for this location. The units are defined by
the Interval type defined for this sample definition.
getAutoApprove() - boolean
Returns the auto approve setting for this location. If true, samples will be automatically
approved when they are recorded. If false, they have to be manually approved.
setAutoApprove(boolean autoApprove)
Sets the auto approve setting for this location. If true, samples will be automatically approved
when they are recorded. If false, they have to be manually approved.
getComingDueMin() - double
Returns the coming due minutes setting for this location. The value represents the number of
minutes required before a sample is due until the sample is considered coming due. For
automatically scheduled samples, they are created prior to actual due time by the number of
minutes of this setting.
setComingDueMin(double comingDueMin)
Sets the coming due minutes setting for this location. The value represents the number of
minutes required before a sample is due until the sample is considered coming due. For
automatically scheduled samples, they are created prior to actual due time by the number of
minutes of this setting.
getOverdueMin() - double
Returns the overdue minutes setting for this location. The value represents the number of
minutes required before a sample is due until the sample is considered overdue.
setOverdueMin(double overdueMinutes)
Sets the overdue minutes setting for this location. The value represents the number of minutes
required before a sample is due until the sample is considered overdue.
getDuration() - double
Returns the number of minutes needed to take a sample for this location.
setDuration(double duration)
Sets the number of minutes needed to take a sample for this location.
getTag() - String
Returns the tag setting for this location.
setTag(String tag)
Sets the tag setting for this location. The tag is used to assign ownership of who is responsible
to take samples. For example, set to Lab" if the lab is responsible or Operator if the operator
is responsible.
Inductive Automation

SPC Quality

682

isModified()
Returns true if this sample definition has been modified.
isNew()
Returns true if this sample definition is new.
4.6.2.8

Sample Definition Control Limit

The sample definition control limit object holds all of the information defining a control limit that is applied
to a sample definition. Be sure not to confuse a control limit defined in the Ignition designer with the
sample definition control limit object. The sample definition control limit object connects a control limit
defined in the Ignition designer with a sample definition.
Once a control limit is associated with a sample definition, it will appear as an option in the SPC Selector
and can appear on control charts. It will also be included during automatic signal evaluations that require
the control limit.
properties:
getID() - int
Returns the database created ID for this sample definition control limit.
getParent() - SampleDefinition
Returns the sample definition that this control limit is a child of.
getName() - String
Returns the name of this control limit as defined in the Ignition designer.
setName(String name)
Sets the name of this control limit as defined in the Ignition designer.
getKind() - ControlLimitKindTypes
Returns the the kind of control limit. There are different types of control limits and calculations
for each type of chart category and this property makes this association between the two.
setKind(ControlLimitKindTypes kind)
Sets the the kind of control limit. There are different types of control limits and calculations for
each type of chart category and this property makes this association between the two.
setKind(int ordinal)
Set the the kind of control limit based on a ControlLimitKindTypes ordinal value. There are
different types of control limits and calculations for each type of chart category and this
property makes this association between the two.
getEnabled() - boolean
Returns true if this sample definition control limit is enabled. If disabled, it will not show as an
option on the control charts.
setEnabled(boolean enabled)
Sets this sample sample definition control limit enabled state. If disabled, it will not show as an
option on the control charts.
isModified()
Inductive Automation

SPC Quality

683

Returns true if this sample definition control limit has been modified.
isNew()
Returns true if this sample definition control limit is new.
4.6.2.9

Sample Definition Signal

The sample definition signal object holds all of the information defining a signal that will be applied to a
sample definition. Be sure not to confuse a signal defined in the Ignition designer with the sample
definition signal object. The sample definition signal object connects a signal defined in the Ignition
designer with a sample definition.
Once a signal is associated with a sample definition, it will appear as an option in the SPC Selector and
can appear on control charts. It will also be included during automatic signal evaluations.
properties:
getID() - int
Returns the database created ID for this sample definition signal.
getParent() - SampleDefinition
Returns the sample definition that this signal is a child of.
getName() - String
Returns the name of this signal as defined in the Ignition designer.
setName(String name)
Sets the name of this signal as defined in the Ignition designer.
getKind() - SignalKindTypes
Returns the the kind of signal. There are different types of signals and calculations for each
type of chart category and this property makes this association between the two.
setKind(SignalKindTypes kind)
Sets the the kind of signal. There are different types of signals and calculations for each type of
chart category and this property makes this association between the two.
setKind(int ordinal)
Sets the the kind of signal based on a SignalKindTypesordinal value. There are different types
of signals and calculations for each type of chart category and this property makes this
association between the two.
getEnabled() - boolean
Returns true if this sample definition signal is enabled. If disabled, it will not show as an option
on the control charts.
setEnabled(boolean enabled)
Sets this sample sample definition signal enabled state. If disabled, it will not show as an option
on the control charts.
isModified()
Returns true if this sample definition signal has been modified.

Inductive Automation

SPC Quality

684

isNew()
Returns true if this sample definition signal is new.
4.6.2.10 Control Limit Kind Type

The control limit kind type object contains the available types of control limits. In all cases, the ending of
the name specifies how it is used in control charts and automatic signal evaluation. An ending of _UCL is
handled as a upper control limit, for _LCL it is handled as lower control limit and _OTHER is a general
control limit.
Available data types:
XBAR_UCL
XBAR_LCL
XBAR_OTHER
Used for the XBar control chart.
RANGE_UCL
RANGE_LCL
RANGE_OTHER
Used for the Range control chart.
STDDEV_UCL
STDDEV_LCL
STDDEV_OTHER
Used for the s (standard deviation) control chart.
INDV_UCL
INDV_LCL
INDV_OTHER
Used for the Individual control chart.
MEDIAN_UCL
MEDIAN_LCL
MEDIAN_OTHER
Used for the Median control chart.
P_UCL
P_LCL
P_OTHER
Used for the p control chart.
NP_UCL
NP_LCL
NP_OTHER
Used for the np control chart.
C_UCL
C_LCL
C_OTHER
Used for the c control chart.
U_UCL
Inductive Automation

SPC Quality

685

U_LCL
U_OTHER
Used for the u control chart.
HISTOGRAM_UCL
HISTOGRAM_LCL
HISTOGRAM_OTHER
Used for the Histogram chart.
MOVING_RANGE_UCL
MOVING_RANGE_LCL
MOVING_RANGE_OTHER
Used for the MA (moving average) control chart.
properties:
getText() - String
Returns the user friendly localized text for the control limit kind.
intToType(int ordinal) - ControlLimitKindTypes
Returns the control limit kind type object for the ordinal value specified.
getTypeFromName(String name) - ControlLimitKindTypes
Returns the control limit kind type object for the name value specified
getCategory() - SPCCategoryTypes
Returns the category of chart. See SPC Category Types for more information.
4.6.2.11 SPC Category Types

The SPC category type defines the possible types of charts currently supported by the SPC module.
Available data types:
XBAR
RANGE
SBAR
INDIVIDUAL
MEDIAN
P
NP
U
C
HISTOGRAM
PARETO
MR
4.6.2.12 Signal Kind Types

The signal kind type object contains the available types that a signal can be.
Available data types:
XBAR
RANGE
SBAR
INDIVIDUAL
Inductive Automation

SPC Quality

686

MEDIAN
P
NP
U
C
HISTOGRAM
PARETO
MR
properties:
getText() - String
Returns the user friendly localized text for the signal kind.
intToType(int ordinal) - SignalKindTypes
Returns the signal kind type object for the ordinal value specified.
getTypeFromName(String name) - SignalKindTypes
Returns the signal kind type object for the name value specified
getCategory() - SPCCategoryTypes
Returns the category of chart. See SPC Category Types for more information.
4.6.2.13 Control Limit Calculated Value

When using the calcControlLimitValue functions, the new calculated control limit value and any
messages are returned in this object. Most control limits are a single value across all samples. The p and
u chart control limits can have different values for each sample. In this case, the results are returned in a
Dataset that is also in this object.
properties:
getCalculatedValue() - double
Returns the new single control limit value.
getData() - Dataset
Returns multiple control limit value that vary for each sample.
hasMessage() - boolean
True is returned if a message exists.
getMessage() - String
Message of why the control limit cannot be calculated.

4.6.3

Scripting Functions

4.6.3.1

sample.production

4.6.3.1.1 sample.production.utils

Inductive Automation

SPC Quality

687

4.6.3.1.1.1 cancelLocationProductCode

system.production.utils.cancelLocationProductCode- Cancel Product Code

Description
Cancel the current product code for a production location. This is provided to handle no production
being run at a production location.
Syntax
Client
cancelLocationProductCode(String locationPath)

Gateway
cancelLocationProductCode(String projectName, String locationPath)

Parameters
String locationPath - The full path of the location to set the product code.
String productCode - The new product code.
String refNo - Optional reference number.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
Example
#This is a sample gateway script to change a locations product code based on a
SQLTag value.
pc = system.tag.getTagValue('[Default]Quality/Test/ProductCodeTest')
if pc == '':
system.production.utils.cancelLocationProductCode('QualityDemo',
'QualityDemo\New Enterprise\New Site\Packaging\Line 1\Line 1 Quality')
else:
system.production.utils.setLocationProductCode('QualityDemo', 'QualityDemo\New
Enterprise\New Site\Packaging\Line 1\Line 1 Quality', pc, '')
4.6.3.1.1.2 setLocationProductCode

system.production.utils.setLocationProductCode- Set Product Code

Description
Set the product code and optional reference number for a production location. If the production
location is already assigned a product code, then it will be canceled and the new product code will be
set.
Note that this scripting function will not immediately change the product code. This is because if a
production location is already assigned a product code, it requires two steps to change the current
product code. The current product code must be canceled before the new product code is made
active. This can be an issue if using this script function in the Before Sample Update Event. The
product code will not be updated until after the sample is updated. Instead use get the sample from
current event object and set the product code directly in the sample.
Syntax
Client
setLocationProductCode(String locationPath, String productCode, String refNo)
Inductive Automation

SPC Quality

688

Gateway
setLocationProductCode(String projectName, String locationPath, String
productCode, String refNo)

Parameters
String locationPath - The full path of the location to set the product code.
String productCode - The new product code.
String refNo - Optional reference number.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
Example
#This is a sample gateway script to change a locations product code based on a
SQLTag value.
pc = system.tag.getTagValue('[Default]Quality/Test/ProductCodeTest')
if pc == '':
system.production.utils.cancelLocationProductCode('QualityDemo',
'QualityDemo\New Enterprise\New Site\Packaging\Line 1\Line 1 Quality')
else:
system.production.utils.setLocationProductCode('QualityDemo', 'QualityDemo\New
Enterprise\New Site\Packaging\Line 1\Line 1 Quality', pc, '')

4.6.3.2

sample.quality

4.6.3.2.1 sample.quality.definition
4.6.3.2.1.1 getNew

system.quality.definition.getNew
Description
Creates and returns a new instance of a SampleDefinition object.
Syntax
Client
system.quality.definition.getNew()

Gateway
system.quality.definition.getNew()

Parameters
none
Returns
SampleDefinition - new sample definition instance
Scope
client, gateway
4.6.3.2.1.2 getSampleDefinition

system.quality.definition.getSampleDefinition- by definition ID
Description
Inductive Automation

SPC Quality

689

Returns a reference to the sample definition with a matching ID. The ID is generated by the database
when the sample definition was first saved.
Syntax
Client
system.quality.definition.getSampleDefinition(int sampleDefID)

Gateway
system.quality.definition.getSampleDefinition(String projectName, int
sampleDefID)

Parameters
int sampleDefID - Database created ID for the sample definition.
String projectName - Name of the Ignition SPC project.
Returns
SampleDefinition - A reference to the matching sample definition
Scope
client, gateway

system.quality.definition.getSampleDefinition- by definition name

Description
Returns a reference to the sample definition with a matching name.
Syntax
Client
system.quality.definition.getSampleDefinition(String sampleDefName)

Gateway
system.quality.definition.getSampleDefinition(String projectName, String
sampleDefName)

Parameters
String sampleDefName - The name given to the sample definition when it was created.
String projectName - Name of the Ignition SPC project.
Returns
SampleDefinition - A reference to the matching sample definition
Scope
client, gateway
4.6.3.2.1.3 addSampleDefinition

system.quality.definition.addSampleDefinition
Description
Adds the sample definition passed in the parameter to the SPC system. After it has been added it will
become available to record samples and for selection on the control charts. Attributes, locations,
control limits and signals must be added to the sample definition prior to calling this function. See
Sample Definition for more information.
Syntax
Client
system.quality.definition.addSampleDefinition(SampleDefinition
sampleDefinition)

Gateway
Inductive Automation

SPC Quality

690

system.quality.definition.addSampleDefinition(String projectName,
SampleDefinition sampleDefinition)

Parameters
String sampleDefinition - New sample definition that previously was created in script.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
4.6.3.2.1.4 updateSampleDefinition

system.quality.definition.updateSampleDefinition
Description
Updates an existing sample definition passed in the parameter. After it has been updated, the
changes will be reflected during recording samples and on the control charts.
Syntax
Client
system.quality.definition.updateSampleDefinition(SampleDefinition
sampleDefinition)

Gateway
system.quality.definition.updateSampleDefinition(String projectName,
SampleDefinition sampleDefinition)

Parameters
String sampleDefinition - Existing sample definition.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
4.6.3.2.2 sample.quality.sample.data
4.6.3.2.2.1 getNewByDefUUID

system.quality.sample.data.getNewByDefUUID
Description
Creates and returns a new sample based on the sample definition that matches the defUUID
parameter. The newly created sample will also be initialized for the location specified by the
locationPath parameter.
Syntax
Client
system.quality.sample.data.getNewByDefUUID(String defUUID, String locationPath)

Gateway
system.quality.sample.data.getNewByDefUUID(String projectName, String defUUID,
String locationPath)

Parameters
String defUUID - Existing sample definition UUID to base this sample on.
Inductive Automation

SPC Quality

691

String locationPath - A valid path to a location.

String projectName - Name of the Ignition SPC project.
Returns
Sample - A reference to the newly created sample.
Scope
client, gateway
Example
locationPath = event.source.parent.LocationPath
defUUID = event.newValue
sample = system.quality.sample.data.getNewByDefUUID(defUUID , locationPath)
4.6.3.2.2.2 getNewByName

system.quality.sample.data.getNewByName
Description
Creates and returns a new sample based on the sample definition that matches the definitionName
parameter. The newly created sample will also be initialized for the location specified by the
locationPath parameter.
Syntax
Client
system.quality.sample.data.getNewByDefName(String defName, String locationPath)

Gateway
system.quality.sample.data.getNewByDefName(String projectName, String defName,
String locationPath)

Parameters
String defName - Existing sample definition name to base this sample on.
String locationPath - A valid path to a location.
String projectName - Name of the Ignition SPC project.
Returns
Sample - A reference to the newly created sample.
Scope
client, gateway
Example
locationPath = event.source.parent.LocationPath
sampleDefName = event.newValue
sample = system.quality.sample.data.getNewByDefName(sampleDefName, locationPath)

4.6.3.2.2.3 getCreateSampleByDefUUID

system.quality.sample.data.getCreateSampleByDefUUID
Description
Return a sample that matches the sampleUUID parameter. If not found, create and return a new
sample based on the sample definition that matches the definitionUUID parameter. The newly created
sample will also be initialized for the location specified by the locationPath parameter.

Inductive Automation

SPC Quality

692

Syntax
Client
system.quality.sample.data.getCreateSampleByDefUUID(String sampleUUID, String
defUUID, String locationPath)

Gateway
system.quality.sample.data.getCreateSampleByDefUUID(String projectName, String
sampleUUID, String defUUID, String locationPath)

Parameters
String sampleUUID - Sample UUID to lookup.
String defUUID - Existing sample definition UUID to base the new sample on.
String locationPath - A valid path to a location to base the new sample for.
String projectName - Name of the Ignition SPC project.
Returns
Sample - A reference to the existing sample or the newly created sample.
Scope
client, gateway
Example
sampleUUID = system.gui.getParentWindow(event).getComponentForPath('Root
Container').SampleUUID
locationPath = system.gui.getParentWindow(event).getComponentForPath('Root
Container').LocationPath
#This will return a sample for the sampleUUID. If the sampleUUID is blank, it will
return a new sample
sample = system.quality.sample.data.getCreateSampleByName(sampleUUID, sampleDef.
getDefUUID(), locationPath)
4.6.3.2.2.4 getCreateSampleByName

system.quality.sample.data.getCreateSampleByName
Description
Return a sample that matches the sampleUUID parameter. If not found, create and return a new
sample based on the sample definition that matches the definitionName parameter. The newly
created sample will also be initialized for the location specified by the locationPath parameter.
Syntax
Client
system.quality.sample.data.getCreateSampleByName(String sampleUUID, String
defName, String locationPath)

Gateway
system.quality.sample.data.getCreateSampleByName(String projectName, String
sampleUUID, String defName, String locationPath)

Parameters
String sampleUUID - Sample UUID to lookup.
String defName - Existing sample definition name to base the new sample on.
String locationPath - A valid path to a location to base the new sample for.
String projectName - Name of the Ignition SPC project.
Returns
Sample - A reference to the existing sample or the newly created sample.
Scope
client, gateway
Example
Inductive Automation

SPC Quality

693

sampleUUID = system.gui.getParentWindow(event).getComponentForPath('Root
Container').SampleUUID
locationPath = system.gui.getParentWindow(event).getComponentForPath('Root
Container').LocationPath
#This will return a sample for the sampleUUID. If the sampleUUID is blank, it
will return a new sample
sample = system.quality.sample.data.getCreateSampleByName(sampleUUID,
'Viscosity', locationPath)
4.6.3.2.2.5 getSample

system.quality.sample.data.getSample
Description
Return a sample that matches the sampleUUID parameter.
Syntax
Client
system.quality.sample.data.getSample(String sampleUUID)

Gateway
system.quality.sample.data.getSample(String projectName, String sampleUUID)

Parameters
String sampleUUID - Sample UUID to lookup.
String projectName - Name of the Ignition SPC project.
Returns
Sample - A reference to the existing sample.
Scope
client, gateway
Example
sampleUUID = system.gui.getParentWindow(event).getComponentForPath('Root
Container').SampleUUID
sample = system.quality.sample.data.getSample(sampleUUID)
4.6.3.2.2.6 updateSample

system.quality.sample.data.updateSample
Description
Update an existing or new sample. If the valuesRecorded parameter is true, current shift, product
code and additional factor information will be recorded along with the measurement values. Because
sample are scheduled, they can be created and updated with no measurement values. This allow for
coming due, due and overdue functionality to be tracked.
Syntax
Client
system.quality.sample.data.updateSample(String locationPath, Sample sample,
Boolean valuesRecorded)

Gateway
system.quality.sample.data.updateSample(String projectName, String
locationPath, Sample sample, Boolean valuesRecorded)

Parameters
String locationPath - A valid path to a location to record this sample for.
Sample sample - Sample to update.
Inductive Automation

SPC Quality

694

Boolean valuesRecorded - If true, record the values along with the other sample information.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
Example
system.quality.sample.data.updateSample(QualityDemo\New Enterprise\New
Site\Packaging\Line 1\Line 1 Quality, currentSample, Boolean 1)
4.6.3.2.2.7 approveSample

system.quality.sample.data.approveSample
Description
Approve an existing sample. If the associated sample definition for the specified sample is not set for
auto approval, it will have to approved. This can be done using various methods of which this is one
of them.
Syntax
Client
system.quality.sample.data.approveSample(String sampleUUID, String approvedBy)

Gateway
system.quality.sample.data.approveSample(String projectName, String
sampleUUID, String approvedBy)

Parameters
String sampleUUID - The UUID to an existing sample to approve.
String approvedBy - The name of the person who is approving the sample.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
Example
system.quality.sample.data.approveSample(currentSample.getSampleUUID, system.
security.getUsername())
4.6.3.2.2.8 unapproveSample

system.quality.sample.data.unapproveSample
Description
Unapprove a previously approved sample. When a sample is unapproved it will not be shown in the
control charts or included in the data during automatic signal evaluation.
Syntax
Client
system.quality.sample.data.unapproveSample(String sampleUUID)

Gateway
system.quality.sample.data.unapproveSample(String projectName, String
sampleUUID)

Parameters
Inductive Automation

SPC Quality

695

String sampleUUID - The UUID to an existing sample to approve.

String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
Example
system.quality.sample.data.unapproveSample(currentSample.getSampleUUID)
4.6.3.2.2.9 removeSample

system.quality.sample.data.removeSample
Description
Remove a single sample. This function should be used with caution because it permanently
removes the data from the database. A sample can be removed at any point in its life cycle. Meaning
it can be removed after it has been scheduled but before measurements are recorded and after
measurements have been recorded.
Syntax
Client
system.quality.sample.data.removeSample(String sampleUUID)

Gateway
system.quality.sample.data.removeSample(String projectName, String sampleUUID)

Parameters
String sampleUUID - The UUID to an existing sample to approve.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
Example
system.quality.sample.data.removeSample(event.getSampleUUID())
4.6.3.2.3 sample.quality.spc.controllimit
Enter topic text here.
4.6.3.2.3.1 setControlLimitValue

system.quality.spc.controllimit.setControlLimitValue
Description
Control limits normally are set using the control charts components and when the process is
determined to be stable. In cases where additional flexibility is required, this scripting function is
provided. New control limit values for a specified location, sample definition (test), attribute and
control limit can be set by calling this function
Syntax
Client
setControlLimitValue(String locationPath, SampleDefinition definition, String
attributeName, String limitName, double value)
Inductive Automation

SPC Quality

696

Gateway
setControlLimitValue(String projectName, String locationPath, SampleDefinition
definition, String attributeName, String limitName, double value)

Parameters
String locationPath - The full path of the location to set the control limit. Optionally, it can be left
blank to set the default control limit value that is not tied to any location.
SampleDefinition definition - Sample definition to the control limit for.
String attributeName - Name of the attribute within the definition to set the control limit for.
String limitName - Name of the control limit to set.
double value - New control limit value.
String projectName - Name of the Ignition SPC project.
Returns
none
Scope
client, gateway
Example
#This is a sample client script to change a control limit to a fixed value.
system.quality.spc.controllimit.setControlLimitValue('New Enterprise\New
Site\Packaging\Line 1\Line 1 Quality', sampleDef, 'Weight', 'Individual LCL',
100.0)
4.6.3.2.3.2 calcControlLimitValue

system.quality.spc.controllimit.calcControlLimitValue
Description
Control limits normally are calculated using the control charts components and when the process is
determined to be stable. In cases where additional flexibility is required, this scripting function is
provided to calculate control limits from data provided in the parameters. Control limit values for a
specified location, sample definition (test), attribute and control limit can be calculated by calling this
function. The control limit will be calculated using the the control limit configured in the designer and
the data specified in the parameters. To set the actual control limit value use the
setControlLimitValue function with the result from this function.
Syntax
Client
calcControlLimitValue(String locationPath, SampleDefinition definition, String
attributeName, String limitName, Dataset data)

Gateway
calcControlLimitValue(String projectName, String locationPath,
SampleDefinition definition, String attributeName, String limitName, Dataset
data)

Parameters
String locationPath - The full path of the location to set the control limit. Optionally, it can be left
blank to set the default control limit value that is not tied to any location.
SampleDefinition definition - Sample definition to the control limit for.
String attributeName - Name of the attribute within the definition to set the control limit for.
String limitName - Name of the control limit to set.
Dataset data - A dataset containing SPC results to calculate the control limit from.
String projectName - Name of the Ignition SPC project.
Returns
ControlLimitCalculatedValue - A reference to the results containing the calculated control limit
and any messages. See Control Limit Calculated Value for more information.
Inductive Automation

SPC Quality

697

Scope
client, gateway

system.quality.spc.controllimit.calcControlLimitValue
Description
Control limits normally are calculated using the control charts components and when the process is
determined to be stable. In cases where additional flexibility is required, this scripting function is
provided to calculate control limits from a date range provided in the parameters. This function will
collect data within the from and end dates specified in the parameters. It calculates a control limit for
the specified location, sample definition (test), attribute and control limit. The control limit will be
calculated using the the control limit configured in the designer. To set the actual control limit value
use the setControlLimitValue function with the result from this function.
Syntax
Client
calcControlLimitValue(String locationPath, SampleDefinition definition, String
attributeName, String limitName, Date from, Date to)

Gateway
calcControlLimitValue(String projectName, String locationPath,
SampleDefinition definition, String attributeName, String limitName, Date
from, Date to)

Parameters
String locationPath - The full path of the location to set the control limit. Optionally, it can be left
blank to set the default control limit value that is not tied to any location.
SampleDefinition definition - Sample definition to the control limit for.
String attributeName - Name of the attribute within the definition to set the control limit for.
String limitName - Name of the control limit to set.
Date from - Calculate the control with data starting with this date.
Date to - Calculate the control with data ending with this date.
String projectName - Name of the Ignition SPC project.
Returns
ControlLimitCalculatedValue - A reference to the results containing the calculated control limit
and any messages. See Control Limit Calculated Value for more information.
Scope
client, gateway
Example
#This is a sample client script to change a control limit to a fixed value.
#Define the starting date to calculate the control limit
from java.util import Calendar
fromDate = Calendar.getInstance();
fromDate.add(Calendar.DAY_OF_MONTH, -1)
#Define the endingdate to calculate the control limit
toDate = Calendar.getInstance();
#Get the sample definition based on its name
sampleDef = system.quality.definition.getSampleDefinition('SQLTag-Line 1
Checkweigher')
#Calculate the new control limit value
result = system.quality.spc.controllimit.calcControlLimitValue('New
Inductive Automation

SPC Quality

698

Enterprise\New Site\Packaging\Line 1\Line 1 Quality', sampleDef, 'Weight',

'Individual LCL', fromDate.getTime(), toDate.getTime())
#Check the results to make sure there are no messages
if result != None and result.hasMessage() == 0:
#Set the actual control limit to the new calculated value
system.quality.spc.controllimit.setControlLimitValue('New Enterprise\New
Site\Packaging\Line 1\Line 1 Quality', sampleDef, 'Weight', 'Individual
LCL', result.getCalculatedValue())

Inductive Automation

SPC Quality

4.7

699

Analysis Providers

Analysis providers determine which information will be viewed on a graph or pie chart. Based on which
Analysis Provider is selected, some filter, compare by, and data point options may or may not be visible.
This section covers only the Quality Analysis Provider that is available with the SPC module.

Quality Analysis Provider

4.7.1

Quality

Description
The Quality Analysis Provider is used to query SPC information that is beyond what can be shown on
control charts. For example, to determine the number of samples taken by user or the number of times a
process was out of control over the last month cannot easily be shown in a control chart.
Provider Name
Quality
Filters
These are the filters that are available in the SPC Module. However, in addition to these filters, additional
factors may be available if they are string data type. All additional factors start with "Factor:". For example,
"Factor:Operator". A filter will allow the user to see all of the data points in the analysis provider as it
pertains to a specific area, shift, etc. For more information on filters, see the Filter By paragraph in the
Analysis Screen section.
Area
Attribute Name
Definition Name
Enterprise
Include
Line
Location
Product Code
Reference Number
Sample Note
Shift
Shift Sync
Site
Tag

Inductive Automation

SPC Quality

700

Compare By
These are the comparisons that are available in the SPC Module. However, in addition to these
comparisons, additional factors may be available if they are string data type. All additional factors start
with "Factor:". For example, "Factor:Operator". A comparison allows one data point to be compared
between all areas, days, etc. For more information on comparisons, see the Compare By paragraph in
the Analysis Screen section.
Approved By
Area
Attribute Name
Day
Definition Name
Enterprise
Line
Location
Month
Note Entered By
Product Code
Reference Number
Sample Entered At
Sample Taken By
Shift
Site
Tag
Week
Year

Data Points
These are the data points that are available in the SPC Module. However, in addition to these
comparisons, additional factors may be available if they are string data type. All additional factors start
with "Factor:". For example, "Factor:Operator". Data points are the different values that will be presented
or compared on a graph or chart. For more information on data points, see the Data Point paragraph in
the Analysis Screen section.
Approved At
Approved By
Approved Count
Area
Attribute Name
Attribute Note
Inductive Automation

SPC Quality
Day
Definition Name
Enterprise
Line
Location
Month
Note Entered By
Product Code
Reference Number
Sample Count
Sample Entered At
Sample Note
Sample Taken At
Sample Taken By
Scheduled Finish
Schedule Start
Shift
Site
Tag
Week
Year

Inductive Automation

701

Instrument Interface
Part V

Instrument Interface

Instrument Interface

5.1

Instrument Interface Module

5.1.1

Introduction

704

The Instrument Interface module is used to define communication settings and data parsing templates to
an instrument. These settings and parsing templates are then used to read data from a instrument and
parse the raw data to extract desired values. The data from an instrument can come from a file, serial
communication port, TCP or UDP connection, OPC device such as a PLC, external data or web service.
The image below show the typical flow of data when reading instrument values through a serial
communications port. Note that the Client Serial Support Module is required to read serial data on a client
computer. The Instrument Interface Module includes a component to make configuring and control of
serial port communications easier than using the script only support of the Client Serial Support Module. If
reading data from a serial communication port on the Ignition server is needed, then the Serial Server
Support Module is needed.

Typical Serial Com m unications Flow

Some Instruments write their results to a disk file. The image below shows the typical flow when reading
data from a file and using the File Monitor component or parsing script functions that are available on both
the client and the gateway to parse the raw data in the file.

Inductive Automation

Instrument Interface

705

Typical File Flow

5.1.2

File Monitor Settings

This page configures the file monitor settings of this Instrument Interface. It provides a configuration area
by instrument type that use file method of handing off data.

File Monitor Settings

General
Enable File
Monitoring

If checked, these file monitoring settings will be applied to File Monitor component when
this Instrument Interface is assigned to its Instrument Interface Name property.

File Monitor
Settings
Auto Monitor If true automatically detects and processes file(s) contained with the File Path
F
property
of the File Monitor component. If false, the read() of the component must
beicalled to process file(s).
l
e
s
Inductive Automation

Instrument Interface
Monitoring

706

The milliseconds between each check for new files. Any files that are found during a
R will be processed. Processing of file will not overlap. If the time it takes to
check
a
process
the files exceeds the value of this property, then the next check will be at
thet next interval.
e

File

This property defines the priority to process multiple file. It is inapplicable when a
P file is selected in the File Path property. If Alpha Numeric is selected, the files
single
arer processed in alphabetical order. If Date is selected, the file names are
o
converted
to date values using the pattern defined in the File Name Date Format
c
property
and then processed in chronological order. If File Timestamp is selected,
thee files are processed in chronological order of the file modified date. Select from
thes following:
s
i
n
g
O
r
d
e
r

File Name

Alpha Numeric = 0
Date = 1
File Timestamp = 2

This property is only applicable if the File Processing Priority property is set to Date.
D property defines the parsing pattern to use when converting the file name to a
This
a value when determining the processing order of the files. The patterns can
date
t
contain
both date and time format designators. See the File Name Date Format
e
property
description of the File Monitor component for more details.
F
o
r
m
a
t

After

This setting defines how files are handled after processing them. Select from the
P
following:
r
o
c
e
s
s
i
n
g
H
a
n
d
l
i
n
g

Character
Encoding

Delete File = 0
Move File = 1

Character encoding of the data

Inductive Automation

Instrument Interface

5.1.3

707

Serial Settings

This page configures the serial port communications settings of this Instrument Interface.

Serial Settings Configuration

General
Enable Serial

Port Settings
Baud Rate

If checked, these port settings will be applied to the Serial Controller component
when this Instrument Interface is assigned to its Instrument Interface Name
property.
Serial Communication baud rate. Select from the following:
Baud 110
Baud 150
Baud 300
Baud 600
Baud 1200

Inductive Automation

Instrument Interface

708

Baud 2400
Baud 4800
Baud 9600
Baud 19200
Baud 38400
Baud 57600
Baud 115200
Baud 230400
Baud 460800
Baud 921600
Data Bits

Serial communication data bits. Select from the following:

DATA
DATA
DATA
DATA

Parity

BITS
BITS
BITS
BITS

5
6
7
8

Serial communication parity. Select from the following:

NONE
EVEN
ODD
MARK
SPACE

Stop Bits

Serial communication number of stop bits. Select from the following:

Stop Bits 1
Stop Bits 2

Hand Shaking

Serial communication flow control methods. Select from the following:

NONE
CTS DTR
CTS RTS
DSR DTR
XON XOFF

Timeout

The default number of milliseconds to wait while reading data.

Character Encoding

Character encoding of the data

Clear Buffer Before

Sending

If checked, clears the receive buffer before sending data.

Correct CRLF

If checked, corrects any combination of end of line characters to carriage

return (CR) and line feed (LF).

Request Handling
Enable Polled
Requests

If checked, the port will be polled at the requested rate.

Request Polling Rate The rate in milliseconds to poll the port

Solicited Request
Script

The script to run for each polled request.

When writing scripts you can use the "event" object to reference methods in the
Serial Controller component that this Instrument Interface is assigned.
Example:
import time
port = event.getSerialController()
port.clearBuffer()
port.writeString("Ar")
Inductive Automation

Instrument Interface

709

time.sleep(0.5)
port.writeString("As")
time.sleep(0.5)
event.setReceivedData(port.readString())
Accept Unsolicited
Request

5.1.4

If checked, the port will can accept requests without being solicited

Parse Template

This page configures a parsing template of this instrument interface configuration. It allows a visual way to
define the individual data points to extract from the raw text returned from the instrument. The text
represents what is returned from a instrument and is displayed in a fixed character width. Multiple parsing
boxes can then be added to define areas to extract meaningful values from.

Parse Tem plate configuration screen

Parse Template Tools

The Parse Template configuration screen contains a toolbar palette with tools that allow interaction with
the current parse template..

Inductive Automation

Instrument Interface

710

Parse Tem plate tool palette

Parsing Box Selector

Allows the user to select any existing parsing boxes in the template. The selected parsing box
will be displayed with sizing arrows on all corners.

Edit Content Text

Allows editing of the actual template text that the parsing operations will be apply to. New
templates are blank and the user will need to add text representing the output received from
the instrument here so that parsing boxes can be applied. This can also be populated by using
the "Send to Template" menu option of the Serial Controller and File Monitor Components.
Refer to the the documentation for these components for more information.

Find Label Parsing Box

The parsed data will be linked to a label on the template so that the position of the label/value
pair can appear at any location.

Inductive Automation

Instrument Interface

711

Find Label Parsing Box Properties

Fixed Position Parsing Box

The parsed data will be read from the template at the exact position the box is placed.

Inductive Automation

Instrument Interface

712

Fixed Position Parsing Box Properties

CSV Column Parsing Box

Will parse all data in the columns in a fashion similar to a CSV file. Rows of data contain
repeating items.
For example:
date,time,sample no.
2011-10-27,11:24:50,23
2011-10-27,11:34:50,33

Inductive Automation

Instrument Interface

713

CSV Row Parsing Box

Will parse all data in the rows in a fashion similar to a CSV file. A group of rows will be
repeated.
For example:
date,2011-10-27
time,11:24:50
sample no.,31
date,2011-10-27
time,11:34:50
sample no.,32
date,2011-10-27
time,11:44:50
sample no.,33

Inductive Automation

Instrument Interface

714

Edit Parsing Box Properties

This will bring up the appropriate editor for the selected parsing box.

Remove Parsing Box

The selected parsing box will be removed.
Toggle Character Grid
A visible grid can be displayed to show the position of all characters.
Parse and Preview Template
This will display a window showing the actual output of the template text after it has been
parsed.

Inductive Automation

Instrument Interface

5.1.5

715

Component Reference

This section is a reference for all of the components that come with the Instrument Interface Module.
5.1.5.1

File Monitor

Description
An invisible component that handles detecting, reading and parsing functions to provide reading data in
files. The term invisible component means that this component appears during design time, but is not
visible during runtime.
In design time, the last raw data read from a file can be sent to the selected template defined by the
Instrument Interface Name by right clicking on the component in the Ignition designer and selecting the
Send to Template menu item. This will also select and display the template and replace the existing
textual data with the last raw data read.
If the Enable Monitoring property is selected and the designer is preview mode or client has the window
open that contains a file monitor component, this component will actively look for files to process. The
files that it will process are specified by the File Path property and can contain wildcard characters.
This component will perform a test lock on the file prior to processing to insure that writing to the file is
complete. This prevents processing a file before it is ready. This is a important feature If processing of a
file starts and data is still being written to the file it will wither cause errors or incomplete data will be
Inductive Automation

Instrument Interface

716

processed.
Properties
This component has standard Ignition properties with the addition of the following properties:
Instrument Interface Name

The name of the Instrument Interface configuration to use. The available

configurations may be selected by clicking on the pencil icon and
selecting from the list or typed in manually.
Scripting name
Data Type

File Path

instrumentInterfaceName
String

The file path to monitor for file(s) to process. This can be a path to a single file or it
can contain wildcard characters to include multiple files.
By including the "*" or "?" wildcard characters in the file name or even the directory
name will switch from single file mode to multi file mode.
The "?" wildcard character represents a single character where the "*" wildcard
character represents multiple characters. The sequence "*?" or "?*" is not needed
and may not work correctly depending on your operating system.
Examples:
c:\temp\import.csv
c:\temp\*.csv
c:\temp\Data*.csv
c:\temp\Data?.csv

c:\temp\*\*.*
Scripting name
Data Type

Will only process a single file named import.csv

Will process all files with the csv file extension.
Will process all files starting with "Data" and have the
csv file extension.
Will process all files starting with "Data" folled by a
single character and have the csv file extension. The
file name c:\temp\Data10.csv will not be processes
but c:\temp\Data1.csv will because the "?" wildcard
character is for a single character.
Will process all files contained in directories below the
temp directory.
filePath
String

Move To
If the After Processing Handling property is set to "Move File", this is the file path
Directory Path location to move processed files.

Scripting name
Data Type
After Processing
Handling

moveToDirectoryPath
String

This setting of this property defines how files are handled after processing them.
Scripting name
Data Type
Values

afterProcessingHandling
Integer
Delete File = 0
Move File = 1

Inductive Automation

Instrument Interface
File

717

This property defines the priority to process multiple file. It is inapplicable when a
P
single
file is selected in the File Path property. If Alpha Numeric is selected, the files
r
are processed in alphabetical order. If Date is selected, the file names are converted
too date values using the pattern defined in the File Name Date Format property and
c
then
processed in chronological order. If File Timestamp is selected, the files are
e
processed
in chronological order of the file modified date.
s
s
i
n
g

Priority

Scripting name
Data Type
Values

File Name
Date Format

fileProcessingPriority
Integer
Alpha Numeric = 0
Date = 1
File Timestamp = 2

This property is only applicable if the File Processing Priority property is set to Date.
This property defines the parsing pattern to use when converting the file name to a
date value when determining the processing order of the files. The patterns can
contain both date and time format designators.
Scripting name
fileNameDateFormat
Data Type
String
Example
Pattern
Example File Name
yyyy-MM-dd
2012-08-15 13:10:00.csv
HH:mm:ss
yyyy-MMMMM- 2012-July-04.txt
dd
MM-dd-yy
10-31-12.log
Letter
G
y
M
w
W
D
d
F
E
a
H
k
K
h
m
s
S
z
Z
'

Inductive Automation

Date or Time Component

Era designator
Year
Month in year
Week in year (1-53)
Week in month (1-5)
Day in year (1-365)
Day in month
Day of week in month
Day in week
AM / PM marker
Hour in day (0-23)
Hour in day (1-24)
Hour in AM / PM (0-11)
Hour in AM / PM (1-12)
Minute in hour
Second in minute
Millisecond
Time zone (general)
Time zone (RFC 822)
Escape for text

Example
AD
yyyy = 1996 or yy = 96
MMMM = July, MMM = Jul, MM = 07 or M = 7
27
2
DDD = 065 or D = 65
dd = 05 or d = 5
2
EEEE = Tuesday or EEE = Tue
AM
HH = 00 or H = 0
kk = 08 or k = 8
KK = 05 or K = 5
hh = 01 or h = 1
mm = 09 or m = 9
ss = 01 or s = 1
SSS = 890
zzzz = Pacific Standard Time or zzz = PST
-0800
hour' h = hour 9

Instrument Interface

718

Enable Monitoring

If true automatically detects and processes file(s) contained with the File
Path property.
Scripting name
enableMonitoring
Data Type
Boolean

Monitor Rate

The milliseconds between each check for new files. Any files that are found
during a check will be processed. Processing of file will not overlap. If the
time it takes to process the files exceeds the value of this property, then the
next check will be at the next interval.
Scripting name
monitorRate
Data Type
Integer

Encoding

Character encoding.
Scripting name
Data Type

encoding
String

NOTE: The following properties are not visible in the property editor. They are available for binding and in scripting and
expressions.
Last File
Processed

This property contains the name of the last file processed.

Scripting name
Data Type

Last File
Read At

The date/time the contents of last file was read.

Scripting name
Data Type

Error
Message

lastFileProcessed
String

lastFileReadAt
DateTime

The current error message or blank if there are no errors.

Scripting name
Data Type

errorMessage
String

Events
parse - onBeforeParse

Event Properties
event.getData()
event.setData(data)

Is fired before raw data is sent to the parsing engine to be parsed. This
provides an method for the raw data to be modified before being parsed. It
can be useful to remove unwanted characters or merging more data into
the raw data before parsing.
Returns the raw data
Data Type

String

param eters

data
Data Type

Modified data to send to the parsing engine.

Data Type
String

returns
Inductive Automation

Instrument Interface

719

If data is modified in this event, use this function to write it back to the
serial controller component before it is send to the parsing engine.
Data Type
String
event.hasData()

Returns true if raw data exists.

Data Type

Boolean

parse - onAfterParse
Is fired after the raw data has been parsed.
Event Properties
event.getParseResults() Returns a ParseResults object containing all the values that were parsed
from the raw data. See ParseResults object reference for more information
about reading values from the ParseResults object.
Data Type
ParseResults
The following script will get results and read a value:
results = event.getParseResults()
if results != None:
if results.isRequiredValid():
sampleNo = results.getValue("sampleno")

event.hasParseResults() Returns true if a ParseResults object exists.

Data Type
Boolean

monitorFile - onError

Is fired when an error occurs during reading file contents. The

errorMessage property can be read to get the error message.

Event Properties
none

Methods
read()
Check existence of and process one files. If multiple files exist only one file is processed because the
ParseResults are returned.
parameters

(none)

returns

Returns a ParseResults object containing all the values that were parsed
from the raw data. See ParseResults object reference for more information
about reading values from the ParseResults object.
Data Type
ParseResults

read(fileName)
Check existence of and process one files. If multiple files exist only one file is processed because the
ParseResults are returned.
parameters

fileName

Inductive Automation

File path to file to process if it

exists.

Instrument Interface

Data Type
returns

720

String

Returns a ParseResults object containing all the values that were parsed
from the raw data. See ParseResults object reference for more information
about reading values from the ParseResults object.
Data Type
ParseResults

parseText(template, text)
Parses the given text by using the template of templateName
parameters

returns

templateName

The template to use for parsing

the text.
Data Type
String

text

The text to be parsed.

Data Type
String

A ParseResults object (see ParseResults object for information about

accessing parsed values contained in the parse results.)
Data Type
ParseResults

Sample script for the onAfterParse event. Is demonstrates displaying each parsed value in a label
component.
parseResults = event.getParseResults()
if parseResults.isValid():
event.source.parent.getComponent('LabelDate').text = str(parseResults.getValue("Date"))
event.source.parent.getComponent('LabelTime').text = str(parseResults.getValue("Time"))
event.source.parent.getComponent('LabelSampleNo').text = str(parseResults.getValue("Sample No"))
event.source.parent.getComponent('LabelAlcohol').text = str(parseResults.getValue("Alcohol"))
event.source.parent.getComponent('LabelDensity').text = str(parseResults.getValue("Density"))
event.source.parent.getComponent('LabelCalories').text = str(parseResults.getValue("Calories"))

5.1.5.2

Serial Controller

Description
An invisible component that handles serial communications and parsing functions to provide instrument
device communications. The term invisible component means that this component appears during
design time, but is not visible during runtime.
In design time, the last raw data received from the communication port can be sent to the selected
template defined by the Instrument Interface Name by right clicking on the component in the Ignition
designer and selecting the Send to Template menu item. This will also select and display the template
and replace the existing textual data with the last raw data received.
In run time, if the Instrument Interface Name property is set, raw data received from the serial
communications port will be sent to the parsing engine on the gateway to be parsed. The template used
to parse the raw data is named the same as the value of the Instrument Interface Name property.
Inductive Automation

Instrument Interface

721

Properties
This component has standard Ignition properties with the addition of the following properties:
Instrument
Interface Name

The name of the Instrument Interface configuration to use. The available

configurations may be selected by clicking on the pencil icon and
selecting from the list or typed in manually.
Scripting name
Data Type

instrumentInterfaceName
String

Port

The name of the serial port. The available com ports may be selected by
clicking on the pencil icon and selecting from the list or typed in manually.
Scripting name
portName
Data Type
String

Baud Rate

Serial Communication baud rate.

Scripting name
Data Type
Values

Data Bits

Baud 110 = 0
Baud 150 = 1
Baud 300 = 2
Baud 600 = 3
Baud 1200 = 4
Baud 2400 = 5
Baud 4800 = 6
Baud 9600 = 7
Baud 19200 = 8
Baud 38400 = 9
Baud 57600 = 10
Baud 115200 = 11
Baud 230400 = 12
Baud 460800 = 13
Baud 921600 = 14

Serial communication data bits.

Scripting name
Data Type
Values

Inductive Automation

baudRate
Integer

dataBits
Integer
DATA
DATA
DATA
DATA

BITS
BITS
BITS
BITS

5=
6=
7=
8=

0
1
2
3

Instrument Interface
Hand Shake

Serial communication flow control methods.

Scripting name
Data Type
Values

Parity

parity
Integer
NONE = 0
EVEN = 1
ODD = 2
MARK = 3
SPACE = 4

stopBits
Integer
Stop Bits 1 = 0
Stop Bits 2 = 1

If true automatically opens the port.

Scripting name
Data Type

Clear Buffer
Before Send

NONE = 0
CTS DTR = 1
CTS RTS = 2
DSR DTR = 3
XON XOFF = 4

Serial communication number of stop bits.

Scripting name
Data Type
Values

Auto Open Port

handShake
Integer

Serial communication parity.

Scripting name
Data Type
Values

Stop Bits

722

autoOpen
Boolean

Clears the receive buffer before sending data.

Scripting name
Data Type

clearBufferBeforeSend
Boolean

Correct CRLF

Corrects any combination of end of line characters to carriage return (CR)

and line feed (LF).
Scripting name
correctCRLF
Data Type
Boolean

Default Read
Timeout

The default number of milliseconds to wait while reading data.

Scripting name
Data Type

defaultReadTimeout
Integer

Inductive Automation

Instrument Interface
Enable Capture

Write all sent and received data to the capture file path.
Scripting name
Data Type

Capture
File Path

unsolicitedRequests
Boolean

If true, requests are made at a fixed interval of the Polling Rate property.
Scripting name
Data Type

Polling Rate

encoding
String

If true, accepts unsolicited requests from the device.

Scripting name
Data Type

Enable Polled
Requests

captureFilePath
String

Character encoding.
Scripting name
Data Type

Unsolicited
Requests

enableCapture
Boolean

The file path on the local computer to create the capture file.
Scripting name
Data Type

Encoding

723

enablePolledRequests
Boolean

Interval in milliseconds to issue poll requests.

Scripting name
Data Type

pollingRate
Integer

NOTE: The following properties are not visible in the property editor. They are available for binding and in scripting and
expressions.
Serial Module
Loaded

If true, the serial module has been installed and is loaded.

Scripting name
Data Type

Serial
Port Open

serialModuleLoaded
Boolean

If true, the serial port is open

The following example is the expression binding on a Label component Text
property:
if({Root Container.Serial Controller.serialPortOpen}, "Ready",
"Not Ready")

Scripting name
Data Type

Inductive Automation

serialPortOpen
Boolean

Instrument Interface
Last Data
Sent At

The date/time the the latest data has been sent.

Scripting name
Data Type

Last Data
Received At

lastDataSentAt
DateTime

The date/time the latest data has been received.

Scripting name
Data Type

Error
Message

724

lastDataReceivedAt
DateTime

The current error message or blank if there are no errors.

Scripting name
Data Type

errorMessage
String

Events
parse - onBeforeParse

Event Properties
event.getData()
event.setData(data)

Is fired before raw data is sent to the parsing engine to be parsed. This
provides an method for the raw data to be modified before being parsed. It
can be useful to remove unwanted characters or merging more data into
the raw data before parsing.
Returns the raw data
Data Type

String

param eters

data
Data Type

Modified data to send to the parsing engine.

Data Type
String

returns

If data is modified in this event, use this function to write it back to the
serial controller component before it is send to the parsing engine.
Data Type
String
event.hasData()

Returns true if raw data exists.

Data Type

Boolean

parse - onAfterParse
Is fired after the raw data has been parsed.
Event Properties
event.getParseResults() Returns a ParseResults object containing all the values that were parsed
from the raw data. See ParseResults object reference for more information
about reading values from the ParseResults object.
Data Type
ParseResults
The following script will get results and read a value:
results = event.getParseResults()
if results != None:
if results.isRequiredValid():
sampleNo = results.getValue("sampleno")

event.hasParseResults()

Returns true if a ParseResults object exists.

Inductive Automation

Instrument Interface

Data Type

725

Boolean

serialPort - onOpen
Event Properties

Is fired when the serial communication port is opened.

serialPort - onClose
Event Properties

Is fired when the serial communication port is closed.

serialPort - onSend
Event Properties
event.getData()

Is fired when data has been sent to the port.

serialPort - onReceive
Event Properties
event.getData()

Is fired when data has been received from the serial communication port.

serialPort - onPoll
Event Properties

Is fired when the serial communications port has been polled for data.

Returns the data that was sent to the serial communication port.
Data Type char[]

Returns the dat that was received from the serial communications port.
Data Type String if readString() or readUntil() initiated the read, byte[] if
readBytes() initiated the read

none

serialPort - onError

Is fired when an error occurs on the the serial communication port. The
errorMessage property can be read to get the error message.

Event Properties
none

Methods
openPort()
Attempts to open the port. If an error occurs the errorMessage property will be set and an exception will
be thrown.
parameters

(none)

returns

(nothing)

closePort()
Attempts to close the port. If an error occurs the errorMessage property will be set and an exception will
be thrown.
parameters

(none)

returns

(nothing)

Inductive Automation

Instrument Interface

726

writeString(text)
Write value of the text parameter to the communication port. If an error occurs the errorMessage property
will be set and an exception will be thrown.
parameters

text

returns

The text to write to the port.

Data Type
String

(nothing)

writeBytes(data)
Write value of the data parameter to the communication port. If an error occurs the errorMessage
property will be set and an exception will be thrown.
parameters

byte []

returns

The byte array to write to the port.

Data Type
byte[]

(nothing)

readString()
Reads and returns string data from the communication port. If an error occurs the errorMessage property
will be set and an exception will be thrown. If no data is received within the default timeout setting, then an
empty string will be returned.
parameters

(none)
returns

The data read from the port.

Data Type
String

readString(timeout)
Reads and returns string data from the communication port. If an error occurs the errorMessage property
will be set and an exception will be thrown. If no data is received within the value specified in the timeout
parameter, then an empty string will be returned.
parameters

timeout

returns

The time in milliseconds to wait

for a response from the port
Data Type
Integer

The data read from the port.

Data Type
String

readBytes(count)
Reads and returns byte array data from the communication port. If an error occurs the errorMessage
Inductive Automation

Instrument Interface

727

property will be set and an exception will be thrown. If the number of characters specified by the count
parameter are not received within the default timeout setting, then any characters received will be
returned.
parameters

count

returns

The number of bytes to read from

the port.
Data Type
Integer

The data read from the port.

Data Type
byte[ ]

readBytes(count, timeout)
Reads and returns byte array data from the communication port. If an error occurs the errorMessage
property will be set and an exception will be thrown. If the number of characters specified by the count
parameter are not received within the value specified in the timeout parameter, then any characters
received will be returned.
parameters

returns

count

The number of bytes to read from

the port.
Data Type
Integer

timeout

The time in milliseconds to wait

for a response from the port
Data Type
Integer

The data read from the port.

Data Type
byte[ ]

readUntil(delimiter, includeDelimiter)
Reads and returns string data from the communication port up until the character specified by the
delimiter parameter. If an error occurs the errorMessage property will be set and an exception will be
thrown. If the delimiter character is not received within the default timeout setting, then any characters
received will be returned.
parameters

returns

Inductive Automation

delimiter

The delimiter to read until.

Data Type
Char

includeDelimiter

If true the delimiter will be included

in the return value.
Data Type
Boolean

The data read from the port.

Data Type
String

Instrument Interface

728

readUntil(delimiter, includeDelimiter, timeout)

Reads and returns string data from the communication port up until the character specified by the
delimiter parameter. If an error occurs the errorMessage property will be set and an exception will be
thrown. If the delimiter character is not received within the value specified in the timeout parameter, then
any characters received will be returned.
parameters

returns

delimiter

The delimiter to read until.

Data Type
Char

includeDelimiter

If true the delimiter will be included

in the return.
Data Type
Boolean

timeout

The time in milliseconds to wait

for a response from the port
Data Type
Integer

The data read from the port.

Data Type
byte[ ]

clearBuffer()
Clear all data existing in the communication port receive buffer. If an error occurs the errorMessage
property will be set and an exception will be thrown.
parameters

(none)
returns

(nothing)

isSerialSupported()
Determines if the client serial module is loaded and available to be used with this component.
parameters

(none)
returns

True if serial support is available

Data Type
Boolean

parseText(template, text)
Parses the given text by using the template of templateName
parameters

templateName

The template to use for parsing

the text.
Data Type
String

Inductive Automation

Instrument Interface

text

729

The text to be parsed.

Data Type
String

A ParseResults object (see ParseResults object for information about

accessing parsed values contained in the parse results.)
Data Type
ParseResults

returns

Sample script for the onAfterParse event. Line 4 shows how to populate measurement values of the SPC
module's Sample Entry component.
results = event.getParseResults()
if results != None and results.isRequiredValid():
reading = results.getValue("reading")
event.source.parent.getComponent('Numeric Text Field').doubleValue = reading.getValue()
event.source.parent.getComponent('Sample Entry').populateMeasurement("Viscosity", reading.getValue(),
else:
system.gui.messageBox("Error reading value from instrument.")

5.1.6

Scripting

This section is a reference for scripting functions provided by the Instrument Interface Module. It also has
a reference for any objects that are used by or returned by the scripting functions.
5.1.6.1

Object Reference

The Instrument Interface Module has a parsing engine that takes raw data received from an instrument
and from it, extract the desired values. The extracted values can be used to set tags, populate SPC
sample measurement values, populate tables, written to database tables and more. Because the
extracted values come in various flavors and have various uses, the paring engine returns the extracted
values in a ParseResults object.
This section defines the ParseResults object and how to access the extracted values.
5.1.6.1.1 Parse Results

A ParseResult object is available from the call to getParseResults() on the Serial Controller component.
properties:
isValid() - Boolean
If true indicates that all parse values exist and are valid.
isRequiredValid() - Boolean
If true indicates the all required parse values exist and are valid.
get(parseValueType) - List
Returns a list ParseValue objects of type specified by the parseValueType parameter.
Available parseValueType options:
A single, discreet value.
system.instrument.parse.types.SingleValue

A collections of ParseRow objects.

system.instrument.parse.types.RowCollection

getAll() - List
Returns a list of all ParseValue objects.
Inductive Automation

Instrument Interface

730

getValue(name) - ParseValue
Returns a ParseValue object for the parsed value specified by the name parameter. The name
must match one of the names assigned to a parsing box defined in the parsing template.
getRowCollection(name) - ParseRowCollection
Returns a ParseRowCollection object for the name specified by the name parameter. The
name must match one of the names assigned to a parsing box defined in the parsing template.
createDataset(name) - Dataset
Returns a Dataset object for the parsed value specified by the name parameter. The name
must match one of the names assigned to a parsing box defined in the parsing template. This
supports converting a ParseRowCollection that is a result of either a CSV Column Parsing Box
or a CSV Row Parsing Box into a Dataset. Dataset can be used to display the data in Table or
other components in Ignition.
createValueMap() - Map of name, value pairs.
Returns a Map object containing name value pairs for all parsed values. The Map can be sent to
the SPC module's Sample Entry component to automate populating sample measurement
values from an instrument. The Map can also be accessed using scripting.
createValueMap() - Map of name, value pairs.
Returns a Map object containing name value pairs for the parsed value specified by the name
parameter. The Map can be sent to the SPC module's Sample Entry component to automate
populating sample measurement values from an instrument. The Map can also be accessed
using scripting.
5.1.6.1.2 Parse Value

A ParseValue object is available from the get method of the ParseResults object. Because parse values
contain additional information such as units, data type, if it is required, etc, the value is contained in this
object. The read the true value form the parse value use the getValue() function.
properties:
isValid() - Boolean
If true indicates that this parse values is valid.
isRequiredValid() - Boolean
If true indicates this parse value is required and is valid.
isRequired() - Boolean
If true indicates this parse value is required.
getName() - String
Returns name of this parse value.
getUnits() - String
Returns the units extracted during parsing for this parse value. The Include Units option must be
selected in the parse box options for the units to be extracted.
getDataType() - DataType
Returns the DataType object of this parse value.

Inductive Automation

Instrument Interface

731

getValue() - Object
Returns the true value of this parse value. For example, if the data type defined in the parse box
options is a Float8, then a double will be retuned.
5.1.6.1.3 Parse Row Collection

The Parse Row Collection object contains one or more ParseRow objects. Each ParseRow object
contains one or more ParseValue objects. When results contain values from a CSV source, there are
rows and columns. As the image below depicts, CSV data is transformed into a ParseResults object.

properties:
isValid() - Boolean
If true indicates that all parse values within all parse rows are valid.
isRequiredValid() - Boolean
If true indicates that all parse values within all parse rows are required and are valid.
isRequired() - Boolean
If true indicates that at least one parse values within all parse rows is required.
getParseRows() - List of ParseRow objects
Inductive Automation

Instrument Interface

732

Returns a list of all parse rows contained in this collection.

Sample script to cycle though all parse value contained in parse rows:
from org.apache.log4j import Logger
log = Logger.getLogger("ParseResult")
fileStr = system.file.readFileAsString("C:\\Temp\\Test.csv")
parseResults = system.instrument.parse.parseText("CSV Test Column", fileStr)
if parseResults.isValid():
rowCollection = parseResults.getRowCollection("CSV Results")
parseRowList = rowCollection.getParseRows()
for parseRow in parseRowList:
parseValueList = parseRow.getParseValues()
for parseValue in parseValueList:
log.info("%s = %s" % (parseValue.getName(), str(parseValue.getValue())))

5.1.6.1.4 Parse Row

A ParseRow object is available from the getParseRows() funtion of the ParseRowCollection object.
properties:
isValid() - Boolean
If true indicates that all parse value objects are valid.
isRequiredValid() - Boolean
If true indicates that all parse values objects that are required are valid.
isRequired() - Boolean
If true indicates that at least one parse value object is required.
getParseValues() - List of ParseValue objects
Results all of the parse values contained in the row.

Inductive Automation

Instrument Interface
5.1.6.2

733

Gateway Scripts

Methods
system.instrument.parse.parseText(projectName, templateName, text)

Parses the given text by using the template of templateName

parameters
projectName

The project name where this template is defined.

Data Type
String

templateName

The template to use for parsing the text

Data Type
String

text

The text to be parsed.

Data Type

String

Data Type

ParseResults

returns
result
5.1.6.3

Client/Designer Scripts

Methods
system.instrument.parse.parseText(templateName, text)

Parses the given text by using the template of templateName

parameters
templateName

text

The template to use for parsing the text

Data Type

String

The text to be parsed.

Data Type

String

Data Type

ParseResults

returns
result

Sample script to read and parse a CSV file then convert the parse results to a dataset and display in a
table component:
fileStr = system.file.readFileAsString("C:\\Temp\\Test.csv")
parseResults = system.instrument.parse.parseText("CSV Test Column", fileStr)
if parseResults.isValid():
dataset = parseResults.createDataset("CSV Results")
event.source.parent.getComponent('Table').data = dataset

Inductive Automation

Recipe / Changeover
Part VI

Recipe / Changeover

736

Recipe / Changeover

Inductive Automation

Recipe / Changeover

6.1

737

Introduction

The Recipe module extends Ignition to manage and monitor recipes. It is ideal for quickly and accurately
changing machine, process or system recipes. Powerful master recipe and sub-recipe management,
recipe security, change log tracking, variance tracking and more empower you to improve efficiency and
quality, and take more control of your manufacturing facility.

6.1.1

Recipe Types

Batch Recipes
We commonly think of recipes as making a batch of product. An analogy to this is a batch of cookies
where many ingredients are added in sequence along with mixing. It is important to understand that a
batch system is different from a recipe. It is true that batch systems use recipes, but a batch system has
equipment definitions that are combined with the recipe to control the machinery to make a batch of
product.
Batch Management Systems handle many other functions including inventory checks before starting a
batch, alarm detection, machine control and more.
The Recipe / Changeover Module does not do the functions of a Batch Management System. This being
said, you can add multiple steps as child recipes to a master recipe and then step or sequence through
the steps. The sequencing through the steps must be done in Ignition script or the PLC.

Batch System

Machine Recipes
Machine recipes are used for setup equipment to run a given product or to put it in a given mode. If a
machine can run 20 different products and each product has different settings, then the need to manage
recipes is essential. Commonly, machines have some sort of operator interface that will allow the
operator to change settings and in some cases, have a very basic recipe system. This can work okay for
a single machine but with production lines where there are several machines, it becomes more of a task
to go to each machine and make sure it is setup to run the next product on the schedule. This requires
time and is prone to mistakes during changeover between products.
When a recipe (product code) is selected for a machine, the recipe values are written to Ignition tags,
some or all of the Ignition tags can be mapped to memory locations in a PLC. In the image below, all the
recipe values except for the Barcode are mapped to a PLC through OPC. The Barcode recipe value is
Inductive Automation

Recipe / Changeover

738

just mapped to an Ignition memory tag and can be displayed on a screen for the operator to verify the
barcode number or it can be sent to a printer through serial or TCP/IP.
If the Almonds recipe is selected, the recipe value will be written to the Ignition tags. If the Ignition tags are
tied to PLC memory addresses, they will end up in the PLC and the machine will be ready to run
almonds.

Single Machine Recipe Value Tag Mapping

When a production line contains production cells, cell groups or locations as children, the recipes can be
managed, selected and reported on by the production line. The image below depicts this where Line 1
has two machines as children. These children can be production cells, cell groups or locations. If the
machines are being tracked with the OEE Downtime Module, then the existing production cells or cell
groups should be reused. However, if the machines are not being tracked with the OEE Downtime
Module, then locations can be used. See Production Model for more information.

Inductive Automation

Recipe / Changeover

739

Multiple Machine Recipe Value Tag Mapping

This is a brief overview of the types of recipes that are commonly used in manufacturing. There is a lot
more functionality such as scaling, variance monitoring, change logs, master recipes, sub recipes,
reporting capabilities, etc. that comes along with the Recipe / Changeover Module that is covered in the
following sections of this manual.

6.1.2

Production Model

To start out, it is important to define what the production model is, which is heavily referred to when
dealing with recipe values. Recipe values are defined by machine, or in some cases a virtual location.
Once recipe values are defined for a machine, they can be added to recipes. After which, the recipe can
be selected for the machine.
A production model defines your manufacturing or process in tree view form. It provides an organized way
to easily configure, control and analyze your facility.

Production Model Tree

Inductive Automation

Recipe / Changeover

740

Inductive Automation

Recipe / Changeover

741

Enterprise
The enterprise is the highest level of the production model and typically represents a manufacturing
company. A company may have one or more production facilities (sites).
Site
A site is a geographical production location and is part of an enterprise.
Area
An area is a physical or logical grouping of production lines.
Line
A line is a collection of one or more cells and/or cell groups and/or locations that run a single product at
any given time.

Cell Group Tree

Location
A location is the space where a sample is collected, product is tracked through or recipes are selected
for. This can be placed under an area or a line.
Cell Group
A cell group contains two or more cells. Typically, these cells occur at the same time in the sequence of
the line instead of one after another, causing the cell group to act as a single sub process or step within
the production.
Cell
The cell is a single machine, sub process or step required in the manufacturing of a product. Cells are
used for tracking OEE and downtime but can also have recipe values added to them and can be used for
track and trace. The product may be a hard product such as used in packaging, liquid, powder, etc.
Packaging machines are a common example, but a cell applies to processes also.

Recipe Value Propagation

Recipe values that are added to a production item are propagated down to the child production items. For
example, if LineSpeed recipe value is added to a production line, then all cells, cell groups and locations
that are children of the production line, will also have the LineSpeed recipe value. The Ignition tag
associated with the recipe value is not propagated to the child recipe value.

Inductive Automation

Recipe / Changeover

742

Recipe Value Propagation

Only the recipe values that have Ignition tags assigned to them will appear in the recipe editor. So, if a
propagated recipe value is not relevant to the child production item, the recipe value Tag property can be
left blank.

6.1.3

Default Values

Default Values
When a new recipe is created, it is initialized with a default value. If the recipe value is assigned to an
Ignition tag that is tied to a PLC memory address, then the default value should be what is normal and
default for the machine. However, it can be any value you want as long as it is within the range of the data
type for the tag the recipe value is associated with and is within the security settings for the recipe value.
See Recipe Security for more information.
Inside a recipe, a recipe value can use the default value or it can be overridden in the recipe as shown in
the image below. Notice the Agitator Speed and Ingredient 2 of the Thick Blend recipe have been
overridden. If it uses the default value, it will be updated when the default value is changed. Once a recipe
value has been overridden in a recipe, it can then be reverted back to the default value.

Inductive Automation

Recipe / Changeover

743

Recipe Default Values

All of this is done in the recipe editor or by using script functions. The image below shows the default
values in the recipe editor where the default values can be edited. Also see Sub Recipes for more details
of how default values are use with sub recipes. The section on Recipe Security provides more detail on
changing the security for recipe values that are accessed in the default values.

Default Values in the Recipe Editor

Inductive Automation

Recipe / Changeover

6.1.4

744

Master Recipes

Master Recipes
Making a change to a recipe value that is used in numerous recipes is a daunting task and is prone to
mistakes. To address this problem the Recipe / Changeover Module uses master recipes. The image
below shows two recipes that are derived from, or descendents of, the Master Blend recipe. When the
descendant recipe is added, all recipe values will be inherited from the master recipe. When a value is
changed in a descendant recipe, it will override the value from the master recipe with the new value as
shown in the image below for the Agitator Speed and Ingredient 2 recipe values.
The image below just shows one master recipe and two descendant recipes. In actual fact, there can be
any number of levels of master recipes and any number of descendants of a master recipe. Any recipe
that has descendants is considered a master recipe. Consider a master recipe called Master 1 that has a
descendant that is called Master 1-A that has a descendant called Final 1-A-A. Then recipes Master 1 and
Master 1-A are both master recipes and recipe Final 1-A-A is a final recipe. Only final recipes can be
selected for a production line, cell, cell group or location. See Selecting Recipes for more information.
One aspect that is not shown in the image below is that the master recipe can inherit its values from the
default values of the associated production item. So the production item has its defaults values, which is
added to a recipe so the recipe inherits from the default values, then the descendant recipes inherit from
the master recipe and so on. That is until a recipe value is overridden somewhere along the inheritance
chain. See Default Values for more information.

Master Recipe

When a value is changed in the master recipe, it is propagated down to the descendant recipes. As
shown in the image below, the Mix Time recipe value is changed to 21 and the Creamy Blend and Thick
Blend recipes also reflect the new value.
Inductive Automation

Recipe / Changeover

745

Master Recipe Value Change

6.1.5

Sub Recipes

Sub Recipes
Sub Recipes are convenient when a machine's recipe can be determined from digits within a product
code. When the product code is used as the recipe, a portion of the product code can be extracted and
used to determine the machine's recipe. For example, you may have a tape machine that recipe values
only change based on the case size. If there are only two different case sizes and there is a digit in the
product code that specifies the case size, then sub recipes can be used for the tape machine. All other
machines can use the normal recipe functionality.
Sub recipes are derived from the product code and the sub recipe mask. The sub recipe mask specifies
the digits to extract from the product code to determine the sub recipe. Once the sub recipe value is
determined like the 76 in the image below, the recipe values are looked up in the sub recipes for the
production line, cell, cell group or location and are written to tags. See Sub Recipe Mask for more
information on how to configure production items to use sub recipes.

Inductive Automation

Recipe / Changeover

746

Sub Recipe Mask

There are two different mask characters that should be used in the Sub Recipe Mask. The first is just a
placeholder and any characters that exist in the corresponding digit position of the product code will be
ignored. The other mask character is the asterisk and any characters that exist in the corresponding digit
position of the product code will be used in the sub recipe value. The asterisk characters in the Sub
Recipe Mask do not need to be in consecutive digit positions as shown in the image below.

Sub Recipe Mask w ith Non-Consecutive Asterisk Mask Characters

The image below steps through the flow of selecting sub recipes and setting the associated tag values
and is based on the determining of the sub recipe as described above. The product code can be selected
using various methods. It can be selected using the Recipe Selector List component, but is can also be
selected by starting a production run for the OEE Module or by using one of the script functions. In fact, it
can be selected using a combination of methods.
The Recipe Editor component is used to edit both normal recipes and sub recipes. See sub recipes in
the Editing Recipes more details. In general, the recipe editor is used to manage sub recipes for a line,
cell, cell group or location. New sub recipes can be created and the recipe values for each can be edited.

Inductive Automation

Recipe / Changeover

747

If a sub recipe is not found, the default will be used.

6.1.6

Editing Recipes

There are multiple methods that values of a recipe can be changed. Depending on the functionality that
you are looking for, recipe values can be changed using the recipe editor, by importing or from script.
Recipe Editor
The recipe editor component provides a visual and interactive method to allow end users to manage
recipes. It handle all of the details and is as easy as adding the component to any Ignition window. It also
provides the ability to manage sub-product codes, recipe value security, master recipes and add MES
production items to recipes.
To add a new recipe, right click on the root Recipes item in the recipe editor and select Add Recipe menu
item. The new recipe will be added and will be ready to enter the name of the new recipe. Commonly, the
Inductive Automation

Recipe / Changeover

748

name of the recipe will be the same as a product code, but it does not have to be. It can represent a
mode of the machine such as Cleaning Mode.

Add Recipe

Type in the name of the new recipe which for this example it is My Recipe. Next, right click on the new My
Recipe and click on the Select Production Items menu item. Please note, that you must first add
production items in the designer before they appear as options to be added to a menu. Because not all
machinery is used in every recipe, this step is used so that only the machinery that is appropriate for a
recipe appears in the recipe editor and recipe selector components. For this example, Line 1 and all of the
cells (machines) beneath it are added to the recipe.

Select Production Item s to Add to Recipe

After clicking the Ok button, expand the production item to view and edit the recipe values. Notice the
Assigned By column. When the new recipe was first added, all of the recipe values show a assigned by
of Enterprise\Site\Area 1\Line 1\Capper - Default for the capper. This is because the initial values of a new
recipe are inherited from the default values for the capper production item. See Default Values for more
information. When a recipe value is changed, the assigned by changes to My Recipe. This is because the
value is no longer that from the default values and is now from the recipe. In simpler terms, it tells you
where the value has been changed in the inheritance tree.
Inductive Automation

Recipe / Changeover

749

Edit Recipe Values

My Recipe will now appear in the Recipe Selection List component and can be selected for any of the
production items that were added to the recipe. But, My Recipe can also be made into a master recipe
simply be add descendant recipes to it. See Master Recipes for more information. This is done by right
clicking on the Descendants item beneath the My Recipe recipe in the recipe editor, and clicking on the
Add Recipe menu item. Type in the name of the new recipe which for this example it is My Recipe 1.
There is no limit to the number of descendants recipes you can add to a master recipe. There is also no
limit to the number of levels deep of master recipes. After My Recipe 1 is added to My Recipe, My Recipe
will no longer show as a option in the recipe selection list component but My Recipe 1 will. In general, if a
recipe has descendants, it becomes a master recipe and will no longer show in the recipe selection list
component. Only final recipes with no descendant will show in the recipe selection list component.
However, master recipes can be selected for production items by using script functions.
Import / Export
Recipes values can be imported and exported into the recipe management system. Note that only the
actual value of the recipe value item can be imported and not the recipe value definition. Recipe value
definitions can be imported in the designer. See Recipe Value Import / Export for more information. This is
because the recipe value definitions are tightly tied to production items (equipment) and tags, both of
which cannot be created in the client.
To export the recipe values in the client, right click on a line, cell, cell group or location underneath the line
and select the export menu item. A file chooser dialog will appear to select or enter a file name to export
to. The file format is a comma separated values (CSV) and contains the following columns:
Recipe_Name
Value_Name
Item_Path
Description
Units
Data_Type
Format
Recipe_Value
Assigned_By

Inductive Automation

Recipe / Changeover

750

To import recipe values in the client, right click on a line, cell, cell group or location underneath the line
and select the import menu item. A file chooser dialog will appear to select or enter a file name to import
to. The file format is a comma separated values (CSV) and must contain the following columns:
Recipe_Name
Value_Name
Item_Path
Recipe_Value

All other columns will be ignored during the import. Also, all values must be surrounded with quotes
including the recipe value. During importing, the recipe value will be converted to the appropriate data type
that the recipe value is defined as, which is based on the tag it is associated.
Recipe values can be imported for multiple recipes and production items combinations in one import
operation as defined with the Recipe_Name and Item_Path columns of the CSV file. This supports bulk
import operations instead of only being limited to one recipe at a time.
Recipe values can also be imported and exported using script either at the client or in the gateway. See
exportRecipe and importRecipe script functions for more information. The following is an example
statement that will import recipe values on the gateway. The project name is required because recipe
values are managed by project. The csvData parameter is a string of csv data that can be read in from a
file, web service, etc. And last, the note is what will show in the recipe change log.
system.recipe.importRecipe("RecipeProject", csvData, note)

This functionality supports reading recipe values from ERP or other systems that are currently being used
to manage recipes. Once the recipe values are in Ignition they can be selected, monitored for variances,
analysis, etc.
Script
In addition to importing and exporting recipe values there are scripts to add recipes, rename recipes,
delete recipes and much more. See Client / Gateway Scripts for documentation of all script functions.
Because the built-in functionality will not fit the requirements in every situation, the scripting functions
provide the built-in functionality to be extended to accommodate the requirements.

6.1.7

Recipe Change Log

Keeping an audit log of when recipes are changed, by who and why can be important. Especially in some
industries where regulatory compliance are in force. The Recipe / Changeover Module records all
changes to recipes wether the changes were made from the recipe editor, importing or script. The only
changes not automatically detected are changes made directly to the database and proper database
security should be implemented if this is a risk.
Below are the methods that the change log history can be examined.
Recipe Change Log Viewer
There is a component that will easily show recipe change log history on screens. It has properties to
narrow in on what production item and recipes to show the change log for. The columns that are shown
are configurable through the table customizer. See Recipe Change Log Viewer component for more
information. The image below depicts the change log viewer.

Inductive Automation

Recipe / Changeover

751

Recipe Change Log View er

Recipe Change Log Analysis Provider

The core production module common to all MES modules has a analysis engine. Each MES module
provides a analysis provider to work with the data collected for the specific module. In the case of the
Recipe / Changeover Module, there are 4 different analysis providers of which one of them is the Recipe
Change Log provider. It is used to query change log history information based on your selections. See
Recipe Analysis Provider for more information.
The image below shows the interactive Recipe Change Log Analysis Provider using the core analysis
components, but it can also be used to provide data to the Ignition Reporting Module.

Recipe Change Log Analysis

Script
Script functions can also be used to read the recipe change log history. This is useful if the recipe change
log history is needed for reasons other than displaying or reporting. The recipe change log history is
returned as a dataset from the script and the rows can be iterated through.
Inductive Automation

Recipe / Changeover

752

See getChangelogHistory script function for more information.

6.1.8

Recipe Security

Recipe Value Security

The recipe value security uses Ignition's authentication roles to limit who can change what recipe values
by how much. Each recipe value can be set to specific security settings or it can inherit from its parent.
Like other recipes value settings, the security settings can propagate down multiple levels of inheritance.
Referring to the image below, the Inherit Security check box determines if the recipe value should use its
parent's security settings or break the inheritance. By unselecting the Inherit Security check box, the
settings for each authentication role can be made. Initially when doing so, the inherited security settings
will remain that of the parent until they are edited.

Recipe Value Security Settings

The recipe value security is verified when changing values using the recipe editor component, importing
recipes or changing values using script.
When changing a recipe value using the recipe editor component, importing recipe values or from client
script, the authentication role applied comes from the roles the currently logged in user belongs to. If the
user belongs to multiple roles then the role with the least security will be applied. For example, if a user
belongs to both the Operator and Maintenance authentication roles, then the least secure one will be
applied. If the Operator role can change the Product Pressure recipe value from 10 to 15 and the
Maintenance role can change it from 5 to 20, then the Maintenance role will apply.
When changing a recipe value from gateway script, the Administrator authentication role is always
applied.
The only place the recipe value security can be changed is by using the recipe editor component. Also, it
can only be changed in the default values area and not in the actual recipes. Wether or not the logged in
user can change the security settings can be controlled with the Enable Security Editing property of the
recipe editor component. This property can be bound to an expression to determine if the currently logged
in user belongs to authentication roles that are allow to edit security. Another approach is to create a
window that allows the recipe value security editing and restrict opening the windows based on
authentication roles the currently logged in user belongs to.

Inductive Automation

Recipe / Changeover

6.1.9

753

Recipe Scaling

Recipe Scaling
When using recipes for batch or other processes that can change based on the amount that is produced,
recipe scaling will adjust recipe values based on a recipe scale value. In the recipe value configuration,
there is an Enable Scaling setting that can be selected. If the Enable Scaling setting is selected for a
recipe value, then whenever a recipe is selected for a production line, cell, cell group or location, the value
from the recipe will be scaled by the value in the RecipeScale tag as shown in the image below.
Enabling recipe scaling is done for each individual recipe value. This supports scaling some of the recipe
values while not scaling others as might be the case in the example shown below. By default, each
production item's Enable Scaling setting is false and must be selected before the RecipeScale value will
be applied.

Recipe Scaling

The RecipeScale is a production OPC item that exists for each production line, cell, cell group or location.
By default, the RecipeScale is 1.0 and recipe values will not change when recipes are selected. When
selecting a recipe for a line, all of the cells, cell groups and locations beneath the line will also be set to
the same recipe provided they are enabled. Also, each cell, cell group and location RecipeScale value will
be set to match that of the line. This enables simple recipe selection for a line without the tedious task of
selecting each machine underneath the line.

6.1.10 Variance Monitoring

Variance Monitoring
In most manufacturing systems it is important to know if the live production values match the recipe
values. There are two cases where this is important. The first is when the recipe values are first written to
verify that they match. The second is during production in the event the live production values changed
from an outside source.
Recipe values are written once when the recipe is first selected. It is very important to confirm that the
values were successfully set. In the case of the Recipe / Changeover Module, when a recipe is selected,
the values are written to the Ignition tags. This should happen successfully, but there can be expressions,
scripts, etc. that prevent the value from being written correctly. This is more of an issue when the Ignition
tag is configured as a OPC item connecting it to the PLC or other device. If a communication error occurs
Inductive Automation

Recipe / Changeover

754

when the new recipe value was being written to the PLC or device, then it is very useful to know this
before machinery is started.
It is very common to have operator interface terminals (OIT) or a standalone human machine interface
(HMI) local to a machine that settings can be changed locally. Settings can also be changed from other
sources besides the local OIT, and it is important to detect and log when any setting varies from the
recipe value.

Recipe Variance Detection

Recipe Value Variance Options

There are cases where it is normal for a live production value to vary after the initial recipe value has been
written to the Ignition tag. In other cases, it might be okay for the live production value to change within a
range. Recipe values in the Recipe / Changeover Module can be configured to not monitor variances or to
have a variance window that the live production value must fall outside of before the variance is logged.
By default the variance monitoring is enabled for each recipe value but it can be disabled by recipe value
in the designer. This allows for a mix of recipe values that variances will be monitored and other that will
not to prevent irrelevant variances from being logged.
The configuration for the variance window is also done by recipe value in the designer. Both the upper and
Inductive Automation

Recipe / Changeover

755

lower variance thresholds can be defined by percentage of the recipe value or a fixed offset around the
recipe value or just fixed values. The image below is showing the Fill Weight recipe value with an upper
variance threshold of +10%. The upper threshold value is calculated by starting with the recipe value of
50.2 and adding 10%. The lower threshold is calculated in the same manner. When the Ignition tag value
changes, a check is done to see if the current value is between the upper and lower threshold values and
in this case as shown in the image below, we see that the current value of 51.0 is between 55.22 and
47.69. As a result, no variance will be logged.

Recipe Value Inside Range

Now lets take a look at a case where the current value is 46.0 as shown in the image below. The value
46.0 is less than the lower threshold and a variance will be logged.

Inductive Automation

Recipe / Changeover

756

Recipe Value Outside Range

The example above shows the upper and lower threshold values being calculated as a percentage of the
recipe value, but they can also be a fixed offset around the recipe value. To configure a recipe value for a
fixed offset around the recipe value a upper variance threshold setting of +<offset> is used. An example is
a variance threshold offset of +7.5 were the upper threshold is calculated by adding 7.5 to the recipe
value. Using the recipe value from above of 50.2 and adding 7.5 to it will give us a upper threshold of 57.7.
The lower variance threshold works the same way.
Instead of the thresholds being calculated as a percentage or fixed offset around the recipe value, fixed
values can also be used. For example, a recipe value can be configured with a upper variance threshold
of 52.0. In this case, the upper threshold will always be 52.0 irregardless of the recipe value.
Lastly, the upper and / or lower threshold can be calculated using Python script. This is configured in the
designer and a recipe value variance range can refer to other tag values, values from databases and
much more when calculating the upper or lower threshold values.
Example Evaluate Variance Script
upperValue = system.tag.read("[Default]SomeOtherTag")
recipeValue = event.getRecipeTag().getCurrentValue()
if recipeValue > upperValue.value:
event.setLogVariance(True)
else:
Inductive Automation

Recipe / Changeover

757

event.setLogVariance(False)

The script is passed an Evaluate Variance Script object that allows accessing the current tag information
and also allows setting the log variance flag. In the script above, a tag called SomeOtherTag is read and
compared to the current value of the tag associated with the recipe value where this script was defined. If
the current value is greater than the value of the SomeOtherTag, then the setLogVariance method is
called with True meaning the recipe value is in a variance state. Otherwise, false is returned.
See Adding a Recipe Value section for details about configuring recipe values.
Variance Status
As mentioned above, variances are logged to the database and can be viewed in the Recipe Variance
Viewer component, analysis and reports. But, having a tag that indicates if any recipe values are in
variance for a machine is useful. The Ignition MES Modules exposes current status and allows some
control through the Production OPC Server. One of the status values provided by the Recipe /
Changeover Module is the RecipeVarianceExists value. Each production line, cell, cell group and location
has an associated RecipeVarianceExists value. If the value is false, then all live production values are
within variance for the production item. If the value is true, then at least one recipe value of the production
item is outside of its variance range. See Production OPC Server and Production OPC Values sections
for available values the Recipe / Changeover Module provides.

6.1.11 Selecting Recipes

There are different methods of selecting a recipe for production items. Production items that support
recipe selection are lines, cells, cell groups and locations. When a production line recipe is selected, it will
also select the same recipe for all of the cells, cell groups or locations that are children of the line. This
can be disabled by setting the EnableRecipe tag for the child production item to false. This is a feature
that makes day-to-day selection of line recipes easier and mistake free.
Recipes can also be canceled that simply turns off variance tracking. This will keep recipe value variance
reporting clean with only data from actual production runs.
Components
After the Recipe / Changeover Module is installed, a Recipe tab will be added to component pallet in the
Ignition designer. There are two components that allow selection of recipes for a production item. Below
is what the Recipe Selection List component looks like.

Recipe Selection List Com ponent

Only final recipes for the production item that is specified by the Item Path property will be displayed. See
Master Recipes for more information about final recipes versus master recipes. The list can be limited to
only show a subset of recipes by using the Recipe Name Filter property.
End users can select and cancel recipes using this component by right clicking on a recipe and selecting
the desired menu item. If this functionality is not desired, then the Read Only property can be set to True
to prevent the select popup menu from showing. See Recipe Selection List for more information about the
Inductive Automation

Recipe / Changeover

758

component.
Starting an OEE Production Run
When a production run is started for the OEE Downtime Module, a product code is selected (or a work
order that is associated with a product code). If a recipe that is named exactly the same as the product
code exists, and the production line that is being started for the OEE Downtime Module has been
previously added to that recipe, then the recipe will be selected at the same time.
In the image below the Mixed Nuts production run started at 12:00 and at the same time the Mixed Nuts
recipe was selected. This greatly simplifies setup of new production runs because only one selection of
the product has to be made. This also eliminates mistakes of selecting different products for the
production run and the recipe. OEE production runs can be started many different ways and using a
production schedule as shown in the image is only one of them. For more information, see the MES OEE
Downtime Module documentation.

Inductive Automation

Recipe / Changeover

759

Recipe Selection w hen OEE Run Started

Starting a Trace
Production locations have the ability to trace product that is being process at them. When a production
location product code is set using the setLocationProductCode script function, the recipe is also selected
for the production location. When this happens the recipe values are written to their associated tags. The
location trace can be turn off using the cancelLocationProductCode function.
Inductive Automation

Recipe / Changeover

760

Currently, scripting is the only method to select a production code for a location, but this will be enhanced
when the traceability module is released.
Example

system.production.utils.setLocationProductCode("RecipeDemo\Enterprise\Site\Area 1\Filler Location", "R

Scripts
Scripts can also be used to directly select and cancel recipes for production items. These scripts
supports selecting and cancelling recipes from external triggers such as when a button is clicked or when
a product code changes.
See setItemRecipe script function to select a recipe for a production item and cancelItemRecipe script
function to cancel the current recipe for a production item for more details.

6.1.12 Production OPC Server

Production OPC Values
The production model is defined in the Ignition designer and contains your production lines, cells, cell
groups and locations. Runtime access into configuration and current state of the production model is
available through the Production OPC Server. It is added automatically when any of the Ignition MES
modules are installed. When the production items are added, removed or modified, the changes will be
reflected in the Production OPC Server when the project is saved and published in the designer.
Below are some of the values available to read, and in some cases write to for the RecipeDemo project.

Inductive Automation

Recipe / Changeover

761

Production Model OPC Values

To use the production OPC values in your projects, Ignition tags have to be created. The easiest method
to do this is drag the production OPC value to the SQLTag Browser. Once the tag has been created, it
can be used to display status on screens, used in expression and any of the other tasks that can be done
with any other Ignition tags. Most of the production OPC values are read only. For example, the
RecipeVarianceExists value is determined by the live production values compared to the values in the
recipe (see Variance Monitoring for more details about the RecipeVarianceExists value). Because it is
reflecting a status, it cannot be written to. However, others do allow writing a value to them.

Inductive Automation

Recipe / Changeover

762

Create Tag from Production OPC Value

Important Note
It is extremely important to understand production OPC values have an OPC item path that matches the
layout of the production model. In the image below, the RecipeVarianceExists tag is shown and includes
the OPC Item Path of RecipeDemo\Enterprise\Site\Area 1\Line 1\Filler.RecipeVarianceExists. If tags have
been previously created and the names are changed in the production model, then the OPC item path will
also have to change.

Tag Configuration
Inductive Automation

Recipe / Changeover

763

For example, if the enterprise name is changed from "Enterprise" to "My Big Company", then the OPC
item path for the tag named RecipeVarianceExists will have to change to RecipeDemo\My Big Company
\Site\Area 1\Line 1\Filler.RecipeVarianceExists. For this reason, it is recommended to first work on laying
out your production model and make sure the names of each of the production items are what you want
before creating Ignition tags.
Important Note
When writing to production OPC values that are related to production model settings, the new value is not
retained upon restarting. This is because production model settings are saved in the Ignition project and is
only written to the project when done so in the designer.

Inductive Automation

Recipe / Changeover

6.2

764

Installation

To install the Recipe module into an existing Ignition system, follow the instructions in the Existing Ignition
System. If you are installing Ignition at the same time, use the instructions in the New Ignition System.

6.2.1

Existing Ignition System

6.2.1.1

Installing Modules

To install the Recipe module onto an existing Ignition server, follow the steps below:
Before installing the Recipe module, it is recommended to first set up the database connection that will be
used to store Recipe data.
1. Download the Recipe-Installer-module.modl module
from the Inductive Automation download website. It will be under the MES modules heading.
2. Install the Recipe-Installer-module.modl module
Navigate to the Modules page of the Ignition gateway. At the bottom of the list of already installed modules,
click the
link. Next, browse to the Recipe-Installer-module.modl file and
click the install button as shown below.

Install Ignition Module

Inductive Automation

Recipe / Changeover

765

The Recipe Installer module will install all required modules. These are the Production and Recipe
modules. It is important to keep in mind not to install or update these modules individually. Instead, it
should be done by updating the Recipe Installer module.

6.2.2

New Ignition System

6.2.2.1

Selecting Install Options

To install the Recipe module at the same time as Ignition, add the following steps to the normal Ignition
installation:
1. Select "Custom Configuration" on the setup step during the Ignition installation.
The following screen will appear. Scroll down to Recipe Module and select it. This will cause the modules
required for recipe functionality to be installed at the same time as Ignition.

.
Ignition Installer

6.2.3

Configure Database

Recipe data is stored in databases external to Ignition. These database(s) are setup in the gateway
configuration section by selecting the Databases> Connections section from the left-hand configuration
menu. See the Ignition documentation for more information on setting up a database connection. Below
shows a typical database connection that is required for the Recipe module.

Inductive Automation

Recipe / Changeover

766

Sam ple Database Connection

6.2.4

MES Module Settings

The MES modules store data in an SQL database. Because Ignition can be configured to multiple
databases, the MES Module Settings configuration page is used to select which databases to store the
data. If only one database has been configured in Ignition, then it will be selected by default.
To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules.
If more than one database connection exists, then the desired database connection can be selected to be
used by the MES modules as shown below.

Inductive Automation

Recipe / Changeover

MES Module Settings Page

Inductive Automation

767

Recipe / Changeover

6.3

768

Configuration

There are two areas to configure the Recipe module. The first area is in the Ignition Gateway and affects
all MES Modules.
The second is in the Ignition Designer and is used to configure production models, user screens and the
like. These settings are saved in an Ignition project and can be backed up and restored using the built-in
project backup and restore features of Ignition.

6.3.1

MES Module Configuration

The Recipe module is just one of the MES (Manufacturing Execution System) modules that has settings
which can be set.
6.3.1.1

Datasource Settings

Recipe data is stored in databases external to Ignition. These database(s) are setup in the gateway
configuration section by selecting the Databases> Connections section from the left-hand configuration
menu. See the Ignition documentation for more information on setting up a database connection. Below
shows a typical database connection that is required for the Recipe module.

Sam ple Database Connection

To change the MES module settings, go to the configuration section in the gateway and select the MES
Modules> Settings section from the left-hand side configuration menu.
Once a database connection is created, and if only one database connection exists, then it will be
automatically selected to be used by the MES modules.
If more than one database connection exists, then the desired database connection can be selected to be
used by the MES modules as shown below.

Inductive Automation

Recipe / Changeover

769

MES Module Settings Page

Runtime Database
The runtime database is where recipe data is stored.
Data Retention Duration
This setting specifies the number of days to retain the data in the runtime database after a production run
has completed and does not apply to the recipe module. Recipes are kept until they are manually
removed by a user.
Analysis Database
The analysis database is where recipe change log and variances are kept.
Analysis Database (Auxiliary)
The MES Modules will mirror the historical analysis data that is written to the local analysis database to
this database. For single site implementations, set this to "-none-". For multi-site implementations, set
this to the datasource for the common remote enterprise database.
Analysis Query Cache Duration
This setting represents the number of seconds to cache analysis results. Analysis is used to compare
recipes, view recipe change logs or view recipe variance logs.

6.3.2

Production Model Configuration

A production model defines your manufacturing or process in tree view form. It provides an organized way
to easily configure, control and analyze your facility. It starts with your enterprise, which represents your
company, and continues down to the site (physical location), area, line and cells.
Recipe values can be added to lines, cell, cell groups or locations. If you are using the OEE Downtime
module and have already purchased cells, you can add recipe values to them. Likewise, if you are using
the SPC module and have already purchased locations, you can add recipe values to them. If you are
Inductive Automation

Recipe / Changeover

770

using only using the Recipe module, then using locations is much more cost effective then using cells.
6.3.2.1

Production Model

The production model is configured within the Ignition designer and is accessed by selecting the
"Production" folder in the project browser. From here your enterprise, site, area(s), line(s) and cell(s) can
be added, renamed and deleted.

Production Model Tree

6.3.2.1.1 Enterprise Configuration

Adding an Enterprise
To add your enterprise, right-click on the "Production" folder in the project browser and select the New
Production Item > New Production Enterprise menu item. An enterprise named "New Enterprise" will
be added to the "Production" folder.
Renaming an Enterprise
To rename it to the name of your enterprise, right-click on it and select Rename, then enter the new
name.
Important Note
It is extremely important to understand that production OPC values have an OPC item path that
matches the layout of the production model and that renaming production items can cause Ignition
tags associated with a production item to stop being updated. See Production OPC Server for more
information.

Inductive Automation

Recipe / Changeover

771

Enterprise Nam e

Deleting an Enterprise
To remove an existing enterprise, right-click on the enterprise item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production enterprise. Please note
that the site, area(s), line(s), cell(s), cell group(s) and location(s) underneath the enterprise will also be
permanently removed.

Inductive Automation

Recipe / Changeover

772

General Enterprise Settings

For the enterprise, there are only general settings. These settings are accessed by selecting the
enterprise item contained in the"Production" folder in the project browser and then selecting the
"General" tab as shown below.

Enterprise General Settings

Enabled

By default, added enterprises are enabled. It can be disabled by un-checking the

Enabled setting and saving the project. This will stop the OEE, downtime and
scheduling module from executing the enterprise, the site and all area(s), line(s) and
cell(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Recipe Values
Recipe values can be added to enterprises but, tags cannot be associated with them. The recipe values
that are added to an enterprise are propagated down to production sites, areas, lines, cells, cell groups
and location beneath the enterprsie. This provides a quick method to add recipe values that are common
to all machines within an enterprise. It also allows for the ability to propagate a value of a recipe value
down to all production items beneath the enterprise. See Production Model for more information on
propagating recipe values to child production items. See Recipe Types for more information about recipe
values and Recipe Values for more information about configuring recipe values.
6.3.2.1.2 Site Configuration

Adding a Site
To add your site, right-click on your enterprise folder in the project browser and select the New
Production Item > New Production Site menu item. A site named "New Site" will be added to the
enterprise folder.
Renaming a Site
To rename it to the name representing the site's physical location, right-click on it and select Rename,
then enter the new name.
Important Note
Inductive Automation

Recipe / Changeover

773

It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Site
To remove an existing site, right-click on the site item and select the Delete menu item. A window will
appear confirming that you permanently want to delete the production site. Please note that the area(s),
line(s), cell(s), cell group(s) and location(s) underneath the site will also be permanently removed.

New Site

General Site Settings

These settings are accessed by selecting the site item contained in the enterprise folder in the project
browser, and then selecting the "General" tab.
Enabled

By default, added sites are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the MES modules from executing the site
and all area(s), line(s), cell(s), cell group(s) and location(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Recipe Values
Recipe values can be added to sites, but tags cannot be associated with them. The recipe values that are
added to a site are propagated down to production areas, lines, cells, cell groups and location beneath the
site. This provides a quick method to add recipe values that are common to all machines beneath a site. It
also allows for the ability to propagate a value of a recipe value down to all production items beneath the
site. See Production Model for more information on propagating recipe values to child production items.
See Recipe Types for more information about recipe values and Recipe Values for more information
about configuring recipe values.
6.3.2.1.3 Area Configuration

Adding an Area
To add a production area, right-click on your site folder in the project browser and select the New
Production Item > New Production Area menu item. An area named "New Area" will be added to the
site folder. Multiple production areas can be added to your production site. Each area can represent a
physical or logical production area within your production site. Some examples of production areas are:
packaging, cracking, filtration, fabrication, etc.
Renaming an Area
To rename it to the name representing the production area, right-click on it and select Rename, then
enter the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
Inductive Automation

Recipe / Changeover

774

associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting an Area
To remove an existing production area, right-click on the area item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production area. Please note that
the line(s), cell(s), cell group(s) and location(s) underneath the area will also be permanently removed.

New Area

Area General Settings

These settings are accessed by selecting the desired area item contained in the site folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added areas are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the MES modules from executing the
area and all line(s), cell(s), cell group(s) and location(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Recipe Values
Recipe values can be added to areas but, tags cannot be associated with them. The recipe values that
are added to an area are propagated down to production lines, cells, cell groups and location beneath the
area. This provides a quick method to add recipe values that are common to all machines beneath an
area. It also allows for the ability to propagate a value of a recipe value down to all production items
beneath the area. See Production Model for more information on propagating recipe values to child
production items. See Recipe Types for more information about recipe values and Recipe Values for
more information about configuring recipe values.
6.3.2.1.4 Line Configuration

Adding a Line
To add a production line, right-click on an area folder in the project browser and select the New
Production Item > New Production Line menu item. A line named "New Line" will be added to the area
folder. Multiple production lines can be added to a production area.
Renaming a Line
To rename it to the name representing the production line, right-click on it and select Rename, then enter
the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
Inductive Automation

Recipe / Changeover

775

associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Line
To remove an existing production line, right-click on the line item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production line. Please note that
the cell(s), cell group(s) and location(s) underneath the line will also be permanently removed.

New Line

Line General Settings

These settings are accessed by selecting the desired line item contained in the area folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added lines are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the MES modules from executing the line
and cell(s), cell group(s) and location(s) that are underneath it.

Description

This is an optional description and is just for your reference.

Sub Recipe Mask

This Sub Recipe Mask is required when using the sub recipe feature. If the sub recipe feature is not being
used for the production item, leave it blank. See Sub Recipes for more information above sub recipes
and Sub Recipe Mask for how to use this setting.
Recipe Values
Recipe values can be added to lines and can represent settings that are written to a PLC or other
controller associated with a machine or be used internally in Ignition.
The recipe values that are added to a line are propagated down to production cells, cell groups and
location beneath the line. This provides a quick method to add recipe values that are common to all
machines beneath a line. It also allows for the ability to propagate a value of a recipe value down to all
production items beneath the area. See Production Model for more information on propagating recipe
values to child production items. See Recipe Types for more information about recipe values and Recipe
Values for more information about configuring recipe values.

Inductive Automation

Recipe / Changeover

776

6.3.2.1.5 Cell Configuration

Adding a Cell
To add a production cell, right-click on a line folder in the project browser and select the New Production
Item > New Production Cell menu item. A cell named "New Cell" will be added to the line folder. Multiple
production cells can be added to a production line.
Renaming a Cell
To rename it to the name representing the production cell, right-click on it and select Rename, then enter
the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Cell
To remove an existing production cell, right-click on the cell item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production cell.

Deleting a Cell

Cell General Settings

These settings are accessed by selecting the desired cell item contained in the line folder in the project
browser and then selecting the "General" tab.
Enabled

By default, added cells are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the MES modules from executing the cell.
Inductive Automation

Recipe / Changeover
Description

777

This is an optional description and is just for your reference.

Sub Recipe Mask

This Sub Recipe Mask is required when using the sub recipe feature. If the sub recipe feature is not being
used for the production item, leave it blank. See Sub Recipes for more information above sub recipes
and Sub Recipe Mask for how to use this setting.
Recipe Values
Recipe values can be added to cells and can represent settings that are written to a PLC or other
controller associated with a machine or be used internally in Ignition. See Recipe Types for more
information about recipe values and Recipe Values for more information about configuring recipe values.
6.3.2.1.6 Cell Group Configuration

Adding a Cell Group

To add a production cell group, right-click on a line folder in the project browser and select the New
Production Item > New Production Cell Group menu item. A cell group named "New Cell Group" will
be added to the line folder. Multiple production cell groups can be added to a production line.
Renaming a Cell Group
To rename it to the name representing the production cell group, right-click on it and select Rename,
then enter the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Cell Group
To remove an existing production cell group, right-click on the cell group item and select the Delete menu
item. A window will appear confirming that you permanently want to delete the production cell group.
Please note that the cell(s) underneath the cell group will also be permanently removed.

Inductive Automation

Recipe / Changeover

778

Adding a Cell Group

Cell Group General Settings

These settings are accessed by selecting the desired cell group item contained in the line folder in the
project browser and then selecting the "General" tab.
Enabled

By default, added cell groups are enabled. It can be disabled by un-checking the
Enabled setting and saving the project. This will stop the OEE, downtime and
scheduling module from executing the cell group.

Description

This is an optional description and is just for your reference.

Sub Recipe Mask

This Sub Recipe Mask is required when using the sub recipe feature. If the sub recipe feature is not being
used for the production item, leave it blank. See Sub Recipes for more information above sub recipes
and Sub Recipe Mask for how to use this setting.
Recipe Values
Recipe values can be added to cell groups and can represent settings that are written to a PLC or other
controller associated with the cell group or be used internally in Ignition.
The recipe values that are added to a cell group are propagated down to production cells beneath the cell
group. This provides a quick method to add recipe values that are common to all machines beneath a cell
group. It also allows for the ability to propagate a value of a recipe value down to all production items
beneath the cell group. See Production Model for more information on propagating recipe values to child
production items. See Recipe Types for more information about recipe values and Recipe Values for
more information about configuring recipe values.

Inductive Automation

Recipe / Changeover

779

6.3.2.1.7 Location Configuration

Adding a Location
To add a production cell, right-click on a line folder in the project browser and select the New Production
Item > New Production Cell menu item. A cell named "New Cell" will be added to the line folder. Multiple
production cells can be added to a production line.
Renaming a Location
To rename it to the name representing the production cell, right-click on it and select Rename, then enter
the new name.
Important Note
It is extremely important to understand production OPC values have an OPC item path that matches
the layout of the production model and that renaming production items can cause Ignition tags
associated with a production item to stop being updated. See Production OPC Server for more
information.
Deleting a Location
To remove an existing production cell, right-click on the cell item and select the Delete menu item. A
window will appear confirming that you permanently want to delete the production cell.

Deleting a Cell

Location General Settings

These settings are accessed by selecting the desired cell item contained in the line folder in the project
browser and then selecting the "General" tab.
Enabled

Inductive Automation

By default, added cells are enabled. It can be disabled by un-checking the Enabled
setting and saving the project. This will stop the OEE, downtime and scheduling
module from executing the cell.

Recipe / Changeover

Description

780

This is an optional description and is just for your reference.

Sub Recipe Mask

This Sub Recipe Mask is required when using the sub recipe feature. If the sub recipe feature is not being
used for the production item, leave it blank. See Sub Recipes for more information above sub recipes
and Sub Recipe Mask for how to use this setting.
Recipe Values
Recipe values can be added to locations and can represent settings that are written to a PLC or other
controller associated with a machine or be used internally in Ignition. See Recipe Types for more
information about recipe values and Recipe Values for more information about configuring recipe values.

6.3.3

Sub Recipe Mask

This Sub Recipe Mask is required when using the sub recipe feature and only apply to line, cell, cell group
or location type of production items. If the sub recipe feature is not being used for the production item,
leave it blank. The sub recipe feature can be used on a production item by production item basis. This
means that standard recipe and sub recipe functionality can be mixed. For example, you may have a tape
machine that recipe values only change based on the case size. If there are only two different case sizes
and there is a digit in the product code that specifies the case size, then sub recipes can be used for the
tape machine. All other machines can use the normal recipe functionality.
6.3.3.1

Sub Recipe Mask Setting

In some situations, a limited number of digits in the product code can specify the recipe to use for a
machine. This is accomplished in the Recipe / Changeover Module by setting a sub recipe mask. See
Sub Recipes for more information.
To set the Sub Recipe Mask for a line, cell, cell group or location, first select the desired production item.
Next, select the Recipe tab and enter the new Sub Recipe Mask value.

Sub Recipe Mask Setting

6.3.4

Recipe Values

Recipe values are defined by production item. Each machine, process or other equipment will have
settings that are unique. For example, a casepacker will not have the same settings as a mixer, so this is
why recipe values are defined by production line, cell, cell group or location.
Inductive Automation

Recipe / Changeover

781

See Recipe Types for more information on how recipe values work. The following sections detail how to
add, edit, delete, export and import recipe values for a production item.
6.3.4.1

Adding a Recipe Value

There is more than one method to add recipe values to a production line, cell (machine), cell group or
location.
Create Recipe Value
To create a new recipe value for a production line, cell, cell group or location, first select the production
item. Next, select the Recipe tab and right click in the recipe value table. A popup menu will appear as
shown in the image below.

Recipe Value Table Popup Menu

Select the New menu item and the Add Recipe Value window will appear. Configure the new recipe value
based on the desired functionality that is described below.

Inductive Automation

Recipe / Changeover

782

Adding a Recipe Value

Name (required)
The required name is used to reference the recipe value. The name must be unique and must not
exist in any of the child production items of the production item that the recipe value is being added to.
The reason for this is that recipe values are propagated down to all of the children, and if the name is
the same, a conflict will occur. Also, some characters are not allowed in recipe value names.
Description
The recipe value description is used to further describe the recipe value. It appears in the recipe editor
component, analysis, reports, and etc.
Tag (required)
This is the path to the Ignition tag that is associated with this recipe value. If a recipe value is added
but a tag is assigned, it will not appear in the recipe editor, and values will not be used when recipes
are selected.
Request Value Script
Optionally, script can be added to calculate or obtain a value to return for a recipe value anytime a
recipe is selected for a production item. This provides flexibility to do just about anything in place of
returning the value stored in the recipe management system. See Request Value Script section for
more information.
Enable Scaling
If this option is checked, the recipe value will be scaled. The recipe value is retrieved out of the recipe
management system and then scaled by the value of the recipe scale tag for the production item.
See Recipe Scaling for more information.
Enable Variance Logging
Inductive Automation

Recipe / Changeover

783

If this option is checked, then the tag will be monitored for changes after a recipe is selected for a
production item. If the value changes more than the window defined in the Low Variance Threshold
and High Variance Threshold, it will be logged to the database, and the recipe variances exists tag for
the production item will be set to true. This prevents values that are know to vary within an allowable
range from being logged to the database and causing the recipe variances exists tag from being set.
If this option is not checked, then the value can change and it will not be logged to the database. Also,
the recipe variances exists tag will not be set as a result of this recipe value.
See Variance Tracking for more information.
Low Variance Threshold
The Low Variance Threshold setting is used to define the lower limit before recipe variances are
triggered for this recipe value. The variance threshold can be defined as a percentage of the recipe
value or a fixed amount.
See Variance Tracking for more information.
High Variance Threshold
The High Variance Threshold setting is used to define the upper limit before recipe variances are
triggered for this recipe value. The variance threshold can be defined as a percentage of the recipe
value or a fixed amount.
See Variance Tracking for more information.
Evaluate Variance Script
Optionally, script can be used instead of using the Low Variance Threshold and High Variance
Threshold settings to determine if the recipe value is outside of an allowable range. When an Ignition
tag value change is detected, the variance state is evaluated using the Low Variance Threshold and
High Variance Threshold settings. Then if an Evaluate Variance Script has been entered for the recipe
value, the script will be executed, and the state can be changed. See Variance Tracking and Evaluate
Variance Script for more information.
Create Recipe Value by Drag and Drop
Recipe values can be added to production items as described above, but the easiest method is to drag
one or more tags from the SQLTags Browser to the recipe value table. Multiple tags can be selected by
holding down the ctrl or shift keys while selecting tags in the SQLTags Browser and dragged to the
Recipe Values table to create multiple recipe values at once. When using this method to add a one or
more recipe values, drag the selected Ignition tags to the open area on the recipe value table.

Inductive Automation

Recipe / Changeover

784

Adding a Recipe Value Using Drag and Drop

Assigning Tags to Recipe Values

In cases where recipe values propagated down from a parent production item or recipe values have been
previously created with no tag assigned to them, tags can be assigned to them using drag and drop. This
can only be done one tag to recipe value at a time.

Inductive Automation

Recipe / Changeover

785

Assigning a Tag to Recipe Value Using Drag and Drop

6.3.4.2

Editing a Recipe Value

To edit a Recipe Value, select the existing Recipe Value you wish to edit, then right-click and select "Edit"
from the menu. The same window used to add recipe values will appear, allowing the information to be
edited.
6.3.4.3

Deleting a Recipe Value

To delete a Recipe Value, select the existing Recipe Value you wish to remove, then right-click and select
"Delete" from the menu. A window will appear confirming that you permanently want to delete the Recipe
Value.
6.3.4.4

Import / Export

To import recipe value configuration entries, right-click anywhere on the recipe values table and select
the Import menu item. A dialog box will appear to allow selection of a comma separated values (csv)
formatted file.
The first line of the file must at least contain the property names separated by commas. If additional
names exist, they will be ignored. The property names can be in any order. Below is a sample csv file
Inductive Automation

Recipe / Changeover

786

showing multiple recipe value configuration entries.

ValueName,ValueDescription,ValueSQLTag,ValueCalcScript,AllowScaling,ValueMonitorEnabled,
ValueMonitorLow,ValueMonitorHigh,ValueMonitorScript
"Line Speed","Description for Line Speed","Recipe/Site/Area 1/Line 1/Line Speed","","false","true","","",""
"Value 1","","","","false","false","","",""
"Value 2","","","","false","false","","",""

To export recipe value configuration entries, right-click anywhere on the table containing recipe value
configuration entries and select the Export menu item. A dialog box will appear to allow selection of an
existing file or the typing in of a name of the new file to save the recipe value configuration entries to. If a
file extension is not entered, then the default .csv will be used.

Inductive Automation

Recipe / Changeover

6.4

787

Component Reference

This section is a reference for all the components that come with the Recipe Module.

6.4.1

Recipe Editor

Description
A component that is added to Ignition windows to manage recipes. This is just one method of managing
recipes and for more information on the other methods see the Editing Recipes section.
It has the capability for end users to do the following recipe related tasks:
Manage recipe value security.
Manage sub product code recipes.
Manage default machine values.
Manage master recipes.
Manage machines that a recipe can be run.
Based on the setting of the properties of the Recipe Editor component, more or less detail can be shown.
This provides a method of displaying the correct amount of information depending on the logged in user's
authentication roles. For example, the image below is very clean only showing limited recipes. This mode
allows changing of recipe values for final recipes (not in master recipes). See Master Recipes for more
information.

Basic Recipe Editor

Where as this image demonstrates a lot of recipe information with many more options, providing much
more configuration of recipes. The Show Master Recipes property will determine if master recipes are
shown. See Master Recipes for more information.
New master recipes can be added by right clicking on the on the root Recipes node and selecting the Add
Recipe menu item.
New descendant recipes can be added by right clicking on the Descendants node and selecting the Add
Recipe menu item. Existing descendant recipes can be renamed, removed or etc. by right clicking on the
Inductive Automation

Recipe / Changeover

788

descendant recipe node and selecting the desired menu item.

Full Recipe Editor

In addition to editing recipes, default values for machines (production lines, cells, cell groups and
locations) can be managed as shown in the image below. The Show Item Defaults property determines if
the default values root item is shown in the recipe editor. See Default Values for more information.

Default Value Editor

Sub recipes can also be managed by setting both the Show Item Defaults and Show Sub Recipes
properties to true. See Sub Recipes for more information. New sub recipes can be added by right clicking
on the Sub Recipes node and selecting Add Sub Recipe menu item. Sub recipes can also be removed,
renamed or etc. by right clicking on the node of a sub recipe and selecting the desired menu item. The
Default sub recipe is always shown and cannot be renamed or deleted. It is reserved for holding the
default values for a machine.
Inductive Automation

Recipe / Changeover

789

Sub Recipe Editor

Based on the setting of the Require Note property, notes are required any time changes are made to a
recipe, sub recipe or default values. The note panels is shown below and the appearance is defined by
several properties. The Popup Panel Font property determines the font of the text, the Note Panel Icon
Path property determines the image on the upper left hand corner and the Note Background Color
property determines the background color. This is just an example of the many properties that change the
appearance of the Recipe Editor component.

Inductive Automation

Recipe / Changeover

790

Recipe Editor Note

The other properties that control what in shown and what operations are allowed are described below.
Properties
This component has standard Ignition properties with the addition of the following properties:
Show Recipes

Set to true to show recipes in the editor. This determines if the

root Recipes node is shown in the recipe editor.
Scripting name
Data Type

Show Master Recipes

Set to true to show master recipes in the editor. The Show

Recipes property must also be set to true.
Scripting name
Data Type

Show Descendants

showItemChildren
Boolean

Set to true to show the recipe value table in the recipe editor.
Scripting name
Data Type

Show Item Defaults

showRecipeItems
Boolean

Set to true to show child production items of the main production

items under the recipe node. For example, if Line 1 is added to a
recipe and the Show Item Children is set to true, then the cells, cell
groups and locations will be shown under Line 1. If the Show Item
Children is set to false, then only Line 1 will be shown.
Scripting name
Data Type

Show Values

showDescendants
Boolean

Set to true to show production items under the recipe node.

Scripting name
Data Type

Show Item Children

showMasterRecipes
Boolean

Set to true to show recipe descendants (or child recipes). It

determines if the Descendants tree node is show in each recipe.
Scripting name
Data Type

Show Recipe Items

showRecipes
Boolean

showValues
Boolean

Set to true to show the item default values and sub recipes in the
recipe editor.
Scripting name
Data Type

showItemDefaults
Boolean

Inductive Automation

Recipe / Changeover
Show Sub Recipes

Set to true to show sub recipes in the recipe editor. The default
values will show up as a sub recipe.
Scripting name
Data Type

Enable Recipe Editing

readOnly
Boolean

Set to true to require a note for any changes. If the user does not
enter a note, then the change they are requesting will be canceled.
Scripting name
Data Type

Item Path Filter

enableSecurityEditing
Boolean

Set to true to disable editing of everything. The recipe editor will be

in view only mode.
Scripting name
Data Type

Require Note

enableRecipeEditing
Boolean

Set to true to enable recipe value security editing.

Scripting name
Data Type

Read Only

showItemDefaults
Boolean

Set to true to enable recipe editing.

Scripting name
Data Type

Enable Security Editing

791

requireNote
Boolean

To limit which production items to show in the recipe editor, this

property can be set. This provides a method to only show
production items that are of interest to the end user. The wildcard
characters "*" or "?" can also be included in the filter value.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type
Recipe Name Filter

itemPathFilter
String

To limit which recipe to show in the recipe editor, this property can
be set. This provides a method to only show recipes that are of
interest to the end user. The wildcard characters "*" or "?" can also
be included in the filter value.
Example
Recipe C*

Scripting name
Data Type

Inductive Automation

recipeNameFilter
String

Recipe / Changeover
Recipe Value Name Filter

792

To limit which recipe values for the recipe to show in the recipe
editor, this property can be set. This provides a method to only
show recipe values that are of interest to the end user. The wildcard
characters "*" or "?" can also be included in the filter value.
Example
Recipe C*

Scripting name
Data Type
Recipe Value Category

Category of recipe values to return. Where 1 is recipe values created by

the recipe module, 2 is recipe values created by the OEE module and 3
is recipe values created by the SPC module. Use blank to include all
categories.
Scripting name
Data Type

Default Row Height

valueTableFont
Font

Set to the font to show text in the recipe value table header.
Scripting name
Data Type

Recipes Icon Path

popupPanelFont
Font

Set to the font to show text in the recipe value table.

Scripting name
Data Type

Value Table Header Font

maxRecipeValueRows
Integer

Set to the font to show text on the note, security and production item
selector popup panels.
Scripting name
Data Type

Value Table Font

defaultRowHeight
Integer

Set to the maximum number of rows to display in the recipe value table
before scrolling.
Scripting name
Data Type

Popup Panel Font

recipeValueCategory
String

Set to the default row height of items in the recipe editor tree.
Scripting name
Data Type

Max Recipe Value Rows

recipeValueNameFilter
String

valueTableHeaderFont
Font

Set to the Ignition image path of the icon to use for the root Recipes
node. If this property is left blank, the default icon will be used.
Scripting name
Data Type

recipesIconPath
String
Inductive Automation

Recipe / Changeover
Recipe Icon Path

793

Set to the Ignition image path of the icon to use for recipe nodes. If
this property is left blank, the default icon will be used.
Scripting name
Data Type

recipeIconPath
String

Recipe Descendants Icon Path Set to the Ignition image path of the icon to use for recipe descendant

nodes. If this property is left blank, the default icon will be used.
Scripting name
Data Type
Default Values Icon Path

Set to the Ignition image path of the icon to use for default values
nodes. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Sub Recipes Icon Path

menuAddIconPath
String

Set to the Ignition image path of the icon to use for rename menu
items. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Inductive Automation

prodItemIconPath
String

Set to the Ignition image path of the icon to use for add menu items. If
this property is left blank, the default icon will be used.
Scripting name
Data Type

Menu Rename Icon Path

defaultSubRecipeIconPath
String

Set to the Ignition image path of the icon to use for production item
nodes. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Menu Add Icon Path

subRecipeIconPath
String

Set to the Ignition image path of the icon to use for default sub recipe
nodes. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Prod Item Icon Path

subRecipesIconPath
String

Set to the Ignition image path of the icon to use for sub recipe nodes.
If this property is left blank, the default icon will be used.
Scripting name
Data Type

Default SubRecipe Icon Path

defaultValuesIconPath
String

Set to the Ignition image path of the icon to use for root sub recipe
nodes. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Sub Recipe Icon Path

recipeDescendantsIconPath
String

menuRenameIconPath
String

Recipe / Changeover

Menu Delete Icon Path

Set to the Ignition image path of the icon to use for delete menu items.
If this property is left blank, the default icon will be used.
Scripting name
Data Type

Menu Revert Icon Path

securityPanelIconPath
String

Set to the Ignition image path of the icon to display on the select
production item slide out panel. If this property is left blank, the default
icon will be used.
Scripting name
Data Type

Note Background Color

notePanelIconPath
String

Set to the Ignition image path of the icon to use display on the recipe
value security slide out panel. If this property is left blank, the default
icon will be used.
Scripting name
Data Type

Item Select Panel Icon Path

menuSelectItemsIconPath
String

Set to the Ignition image path of the icon to use display on the note
slide out panel. If this property is left blank, the default icon will be
used.
Scripting name
Data Type

Security Panel Icon Path

menuSecurityIconPath
String

Set to the Ignition image path of the icon to use for select production
items menu items. If this property is left blank, the default icon will be
used.
Scripting name
Data Type

Note Panel Icon Path

menuRevertIconPath
String

Set to the Ignition image path of the icon to use for security menu
items. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Menu Select Items Icon Path

menuDeleteIconPath
String

Set to the Ignition image path of the icon to use for revert value menu
items. If this property is left blank, the default icon will be used.
Scripting name
Data Type

Menu Security Icon Path

794

itemSelectPanelIconPath
String

Set the background color to use on the note slide out panel.
Scripting name
Data Type

noteBackgroundColor
Color

Inductive Automation

Recipe / Changeover
Security Background Color

795

Set the background color to use on the security slide out panel.
Scripting name
Data Type

securityBackgroundColor
Color

Item Selector Background Color Set the background color to use on the select production item slide

out panel.
Scripting name
Data Type
User Menu Items

itemSelectorBackgroundColo
r
Color

A dataset containing user menu item to show in popup menus within

the recipe editor component.
Scripting name
userMenuItems
Data Type
Dataset
The Dataset must have the following columns that are reference by
column number when building the user menus:
0
String
Node type that determines which popup
menu the user menu item will appear in.
Valid options are:
Root Recipe
Recipe
Descendants
Production Item
Root Sub Recipe
Sub Recipe

String

Text to appear for the user menu item.

This is also used to identify the user menu
item that was clicked in the
userMenuItemClicked event.

String

Ignition image path of the icon to display

in the user menu item.

Events
meunu - userMenuItemClicked
Event Properties
event.getMenuItemName()

Is fired whenever a user menu item is selected.

Returns the name of the user menu item that triggered the event.
Data Type
String

event.getSelectedItemPath()

Returns the item path of the currently selected production item.

Data Type
String

event.getSelectedRecipe()

Returns the name of the currently selected recipe.

Data Type
String

event.getSelectedValueName()

Returns the name of the currently selected recipe value.

Data Type
String

Inductive Automation

Recipe / Changeover

event.getSelectedSubRecipe()

Returns the name of the currently selected sub recipe.

Data Type
String

event.getUser()

Returns the name of the logged in user.

Data Type
String

event.isShowRecipes()

Returns true if Show Recipes property is true.

Data Type
Boolean

event.isShowItemDefaults()

Returns true if Show Item Defaults property is true.

Data Type
Boolean

796

Methods
changeLocalizationString(key, displayText)

Any of the text that is displayed in the recipe editor change be changed. For example, displaying Recipes
for the root recipe node can be replaced with Products. This can be done for any static text in the recipe
editor including menu items.
parameters

The key to the string value to

change.
Data Type
String

key
Recipe Editor component keys:
node.recipes
node.default.values
node.subrecipes
node.subrecipes.default
node.descendants
node.subrecipes.default
menu.recipe.add
menu.recipe.delete
menu.recipe.rename
menu.value.revert
menu.recipe.revertvalues
menu.value.read
menu.recipe.setvalues
menu.value.security
menu.recipe.selectitems
menu.subrecipe.add
menu.subrecipe.delete
menu.subrecipe.rename
menu.recipe.import
menu.recipe.export
panel.item.select.inst
panel.security.inst
panel.note.inst
panel.cancel.desc
panel.ok.desc

displayText

The new text to replace the

existing display text.
Data Type
String
Inductive Automation

Recipe / Changeover

returns

797

nothing

Sample script to change the root Recipes node text to Spanish.

Script from internalFrameActivated event on the window

system.gui.getParentWindow(event).getComponentForPath('Root Container.Recipe TreeView').changeLocalizatio

6.4.2

Recipe Editor Table

Description
A component that is added to Ignition windows to manage a single recipe. This is just one method of
managing recipes and for more information on the other methods see the Editing Recipes section.
To use the recipe table you must supply an item path and recipe name then the table will populate with
the related values.
It has the capability for end users to do the following recipe related tasks:
View the current tag values related to this recipe and equipment path. This can be set to update at a
specific interval.
Manually adjust the recipe value before writing it down to the tags.
Update the selected recipe with the current live values

The table coulmns displayed can be customized by using the standard Ignition table customizer available
by right clicking on the table component in the designer. The available fields are:
Name
The recipe value name
Recipe Setting
The set value assigned in the recipe
Live Value
The current live tag value referenced by this recipe value
Inductive Automation

Recipe / Changeover

798

Manual Value
A value that is manually set by the user. You must call a method of the component in order to have
this value affect the recipe or the tag value.
Description
The description of this recipe value
Units
The units of this recipe value
Assigned By
The assigned by name of this recipe value
Format
The format of this recipe value
dataType
The data type of this recipe value
tagPath
The tag path referenced by this recipe value

The other properties that control what in shown and what operations are allowed are described below.
Properties
This component has standard Ignition properties with the addition of the following properties:
Item Path

This is a required property to specify a single production item to show

recipes for.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type
Recipe Name

itemPath
String

The recipe name of the recipe to view in the table..

Example
Recipe MX142

Scripting name
Data Type
Live Update Interval

recipeName
String

The interval in seconds to update the live values in the table. A value of
0 disables updates.
NOTE: If the Live Value column is not being displayed then the live
values will never be updated regardless of this setting.
Default: 0
Scripting name
Data Type

liveValueUpdateInterval
Integer

Events
Inductive Automation

Recipe / Changeover

799

This component has standard Ignition table events.

Sample script for the Extension Function 'getBackgroundAt' that will highlight the live and manual columns
background if they are not equal to the recipe setting:

import system
backGroundColor = defaultColor
data = self.getData()
recipeValue = data.getValueAt(row, 'Recipe Setting')
if col == data.getColumnIndex('Live Value'):
if value != recipeValue:
backGroundColor = system.gui.color(255,255,204)
if col == data.getColumnIndex('Manual Value'):
if value != recipeValue:
backGroundColor = system.gui.color(204,255,204)
return backGroundColor

Methods
activateRecipe()
This script will activate the current recipe name on the selected item path using the Manual Values
entered in the table.
parameters

none

returns

A String representing any error that was encountered. The string will be blank
if the recipe was successfully activated.

Sample script to activate the currently viewed recipe:

recipeEditorTable = event.source.parent.getComponent('Recipe Editor Table')
result = recipeEditorTable.activateRecipe()
if result != '':
system.gui.messageBox(result, "Recipe activation error")

updateLiveValues()
This script will update the live values of the recipe referenced tags in the table.
parameters

none

returns

A String representing any error that was encountered. The string will be blank
if the recipe was successfully activated.

Inductive Automation

Recipe / Changeover

800

saveRecipe()
This script will update the settings for the recipe with the current live recipe values.
parameters

none

returns

A String representing any error that was encountered. The string will be blank
if the recipe was successfully activated.

reset()
This script will reset the manual values to the recipe settings value.

6.4.3

parameters

none

returns

nothing

Recipe Changelog Viewer

Description
A component that is added to Ignition windows to display recipe change log history in a table. This is just
one method of viewing a recipe change log history and for more information on the other methods see
the Recipe Change Log section.
The Recipe Change Log Viewer component is inherited from the Ignition Table component and many of
the features are carried through to this component. This component simplifies displaying a recipe
changes log by handling all of the backend database queries based on the property settings of the
component. The appearance and columns to display are changed using the table customizer that is
accessed by right clicking on the Recipe Change Log Viewer component and selecting Customizers>Table Customizer.
Properties
This component has standard Ignition properties with the addition of the following properties:
Item Path Filter

To limit which production items to show in the recipe change log

history, this property can be set. This provides a method to only show
production items that are of interest to the end user. The wildcard
characters "*" or "?" can also be included in the filter value.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type

itemPathFilter
String
Inductive Automation

Recipe / Changeover

Recipe Name Filter

801

To limit which recipes to show in the recipe change log history, this
property can be set. This provides a method to only show recipes that
are of interest to the end user. The wildcard characters "*" or "?" can
also be included in the filter value.
Example
Recipe C*

Scripting name
Data Type
Value Name Filter

To limit which recipe values to show in the recipe change log history,
this property can be set. This provides a method to only show recipe
values that are of interest to the end user. The wildcard characters "*"
or "?" can also be included in the filter value.
Scripting name
Data Type

User Filter

userFilter
String

To limit which sub product codes to show in the recipe change log
history, this property can be set. This provides a method to only show
sub product codes that are of interest to the end user. The wildcard
characters "*" or "?" can also be included in the filter value.
Scripting name
Data Type

Show Recipe Changes

valueNameFilter
String

To limit which users to show in the recipe change log history, this
property can be set. This provides a method to only show changes
made by a user. The wildcard characters "*" or "?" can also be
included in the filter value.
Scripting name
Data Type

Sub Product Code Filter

recipeNameFilter
String

subProductCodeFilter
String

If true show recipe changes.

Scripting name
Data Type

showRecipeChanges
Boolean

Show Default Value Changes If true show production item default value and sub recipe changes.

Scripting name
Data Type
Start Date

Starting date of any entries in the recipe change log to include.

Scripting name
Data Type

Inductive Automation

showdefaultValueChanges
Boolean

startDate
Date

Recipe / Changeover
End Date

802

Ending date of any entries in the recipe change log to include.

Scripting name
Data Type

endDate
Date

Change log historical data that can be bound to or used in script.

Date

Scripting name
Data Type

date
Dataset

Events
none

Methods
none

6.4.4

Recipe Variance Viewer

Description
A component that is added to Ignition windows to display recipe variances in a table. This is just one
method of viewing a recipe variances and for more information on the other methods see the Variance
Monitoring section. The Recipe Variance Viewer is automatically updated when live recipe value variances
are detected by the Recipe / Changeover Module. The Show Full Details property will cause the initial
values when the recipe was selected, to also be included.
The Recipe Variance Viewer component is inherited from the Ignition Table component and many of the
features are carried through to this component. This component simplifies displaying recipe variances by
handling all of the backend database queries based on the property settings of the component. The
appearance and columns to display are changed using the table customizer that is accessed by right
clicking on the Recipe Variance Viewer component and selecting Customizers->Table Customizer.
Properties
This component has standard Ignition properties with the addition of the following properties:
Item Path Filter

This is a required property to limit the variances to a single production

item.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type

itemPathFilter
String

Inductive Automation

Recipe / Changeover
Recipe Name Filter

803

To limit which recipes to show in the variances, this property can be

set. This provides a method to only show recipes that are of interest to
the end user. The wildcard characters "*" or "?" can also be included in
the filter value.
Example
Recipe C*

Scripting name
Data Type
Value Name Filter

To limit which recipe values to show in the variances, this property can
be set. This provides a method to only show recipe values that are of
interest to the end user. The wildcard characters "*" or "?" can also be
included in the filter value.
Scripting name
Data Type

Sub Recipe Name Filter

subRecipeNameFilter
String

If true, show recipe values when the recipe was first selected.
Scripting name
Data Type

Display Variance Type

valueNameFilter
String

To limit which sub recipes to show in the variances, this property can
be set. This provides a method to only show sub product codes that
are of interest to the end user. The wildcard characters "*" or "?" can
also be included in the filter value.
Scripting name
Data Type

Show Full Details

recipeNameFilter
String

showFullDetails
Boolean

Set the variance types to include in the results. Valid values are:
RECIPE to return variances that occurred while a production item was
selected to a recipe.
SUB_RECIPE to return variances that occurred while a sub product
code was selected for a production item. See Sub Recipes for more
information.
Scripting name
Data Type

Inductive Automation

showdefaultValueChanges
VarianceEntryTypes

Recipe / Changeover
Display Variance Scope

804

Set the variance scope to include in the results. Valid values are:
LAST to return variances that occurred for the current or last recipe that
a production item was set. This is useful for detecting any variances in
real time for a production run. If the production run has stopped, it will
return the variances as long as a new recipe has not been selected for
the production item.
DATE_RANGE to return variances for the date range specified with the
Start Date and End Date properties.
Scripting name
Data Type

displayVarianceScope
VarianceScopeType

Start Date

Starting date of any entries in the recipe change log to include. The
Display Variance Scope property must be set to DATE_RANGE.
Scripting name
startDate
Data Type
Date

End Date

Ending date of any entries in the recipe change log to include. The
Display Variance Scope property must be set to DATE_RANGE.
Scripting name
endDate
Data Type
Date

Data

Recipe value variances data that can be bound to or used in script.

Scripting name
Data Type

date
Dataset

Events
none

Methods
none

6.4.5

Recipe Selector Combo

Description
A component that is added to Ignition windows to select recipes in a drop down list. This is just one
method of selecting a recipe for a production line, cell, cell group or location. For more information on the
other methods see the Selecting Recipes section. The Recipe Selector Combo component is
automatically updated when recipes are added, removed, etc.
Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

Recipe / Changeover
Item Path

805

This is a required property to specify a single production item to show

recipes for.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type
Recipe Name Filter

itemPath
String

To limit which recipes to show, this property can be set. This provides
a method to only show recipes that are of interest to the end user. The
wildcard characters "*" or "?" can also be included in the filter value.
Example
Recipe C*

Scripting name
Data Type
Selected Recipe Name

recipeNameFilter
String

This will reflect the recipe that the user selected. It can also be set
using script.
Scripting name
Data Type

selectedRecipeName
String

Events
none

Methods
none

6.4.6

Recipe Selector List

Description
A component that is added to Ignition windows to select recipes in a scrollable list. This is just one
method of selecting a recipe for a production line, cell, cell group or location. For more information on the
other methods see the Selecting Recipes section. The Recipe Selector List component is automatically
updated when recipes are added, removed, etc. The current recipe selected is also automatically updated
if the recipe changes from a different source.
To select a recipe for a production item, the user can right click on a recipe then select the Select Recipe
menu item. To cancel a recipe, right click on the selected recipe then select the Cancel Recipe menu
item. This component also supports additional menu item to be added by using the User Menu Items
property and the userMenuItemClicked event.
Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

Recipe / Changeover
Item Path

806

This is a required property to specify a single production item to show

recipes for.
Example
Enterprise\Site\Area 1\Line 1

Scripting name
Data Type
Recipe Name Filter

itemPath
String

To limit which recipes to show, this property can be set. This provides
a method to only show recipes that are of interest to the end user. The
wildcard characters "*" or "?" can also be included in the filter value.
Example
Recipe C*

Scripting name
Data Type
Selected Recipe Name

This will reflect the recipe that the user selected. It can also be set
using script.
Scripting name
Data Type

Selected Icon Path

selectedRecipeName
String

Set to the Ignition image path of the icon to use to indicate the selected
recipe. If this property is left blank, the default icon will be used
Scripting name
Data Type

User Menu Items

recipeNameFilter
String

selectedIconPath
String

A dataset containing user menu item(s) to show in popup menus

within the recipe selector list component.
Scripting name
userMenuItems
Data Type
Dataset
The Dataset must have the following columns that are reference by
column number when building the user menus:
0
String
Text to appear for the user menu item.
This is also used to identify the user menu
item that was clicked in the
userMenuItemClicked event.
1

Events
menu - userMenuItemClicked
Event Properties
event.getMenuItemName()

String

Ignition image path of the icon to display

in the user menu item.

Is fired whenever a user menu item is selected.

Returns the name of the user menu item that triggered the event.
Data Type
String
Inductive Automation

Recipe / Changeover

event.getSelectedItemPath()

Returns the item path of the production item.

Data Type
String

event.getSelectedRecipe()

Returns the name of the currently selected recipe.

Data Type
String

Methods
none

Inductive Automation

807

Recipe / Changeover

6.5

808

Analysis Providers

Each of the MES modules depend on the core Production Module. When any of the MES modules are
purchased, the Production Module is included at no additional cost. The Production Module provides the
production model functionality that is an object oriented hierarchy of production facilities. It also provides
analysis functionality that each specific MES module can extend. The Recipe / Changeover Module
provides four analysis providers to analyze differences between recipes, variances and change logs.
The image below shows the impromptu analysis screen where a Recipe C1 6Pk is being compared to its
parent Master C. Filters and data points can be selected using the Production Analysis Selector
component, but the Analysis Controller will allow requesting comparisons of recipes without the user
interface. The filters and data points are defined through the component properties and is how data for
reports is collected.

Recipe Analysis Provider

Below describes each of the analysis providers included in the Recipe / Changeover Module.

6.5.1

Recipe Analysis Provider

The recipe analysis provider is used to collect recipe values for display or report purposes. By adding
multiple Recipe Name filter values, the values will be returned for each recipe name allowing comparing
of two or more recipes.
Filters
The recipe analysis provider can accept the following filters:

Inductive Automation

Recipe / Changeover
Category

809

This is a required filter to specify the type of recipes to return.

Only one of the valid options are required:
Recipe
Sub Recipe - This includes default values or sub recipes for
production items.
Example when using it with the Analysis Controller:
Category=Recipe

Item Path

This is a required filter to specify the production item to include in

the results. It is the item path for the desired item path(s).
Because analysis is independent of projects, the project name is
required in the item path.
Example when using it with the Analysis Controller:
Item Path=RecipeDemo\Enterprise\Site\Area 1\Line 1, Item
Path=RecipeDemo\Enterprise\Site\Area 1\Line 2

Children

This is a filter to specify if children of the production item(s)

specified in the Item Path filter should be included.
Only one of the valid options are required:
Include
Exclude (Default)
Example when using it with the Analysis Controller:
Children=Include

Format

This is a filter to specify the format of the results.

Only one of the valid options are required:
None - A row in the results will be created for each recipe
included in the Recipe Name filter.
Recipe Comparison (Default) - This format creates a recipe
value column for each recipe included in the Recipe Name filter
and consolidates the item path, value name, etc. columns that
are common.
Example when using it with the Analysis Controller:
Format=None

Inductive Automation

Recipe / Changeover
Column Naming

810

This is a filter to specify how to name the recipe value columns

when the Format filter is set to Recipe Comparison (Default).
When this filter is set to Recipe Name Prefix (Default), it is difficult
to create a recipe comparison report because the column names
change depending on the recipes being compared. Setting this
filter to Number Suffix will cause the recipe value column names
to always be the same, which simplifies reports.
Only one of the valid options are required:
Number Suffix
Recipe Name Prefix (Default)
Example when using it with the Analysis Controller:
Column Naming=Number Suffix

Recipe Name

This is a filter to limit the recipe(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Name=Recipe A, Recipe Name=Recipe B

Recipe Value Name

This is a filter to limit the recipe value(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Value Name=Line Speed, Recipe Value Name=Force

Value Types

This is a filter to specify the type of recipe values to include.

Only one of the valid options are required:
Equal Values - Include only recipe values that match between
two or more recipes.
Not Equal Values - Include only recipe values that do not match
between two or more recipes.
All Values (Default) - Include both values that do not match and
do match between two or more recipes.
Example when using it with the Analysis Controller:
Value Types=Not Equal Values

Compare By
The recipe analysis provider does not allow any comparison statements.
Data Points
The recipe analysis provider can accept the following data points:
Assigned By

This is the recipe or production item that assigned the recipe

value based on inheritance.

Data Type

This is the data type of the recipe value.

Description

This is the description from the recipe value configuration that

was entered in the designer.

Inductive Automation

Recipe / Changeover

811

Format

This is the numeric format from the associated Ignition tag.

Recipe Name

This is the name of the recipe. If the Format filter is set to Recipe
Comparison (Default), then this data point will not be included in
the results. This is because columns are added for each recipe
being compared. For example when comparing Recipe A to
Recipe B, there will be Recipe_A_Recipe_Value and
Recipe_B_Recipe_Value columns.

Units

This is the units from the associated Ignition tag.

6.5.2

Recipe Variance Analysis Provider

The recipe variance analysis provider is used to collect recipe variances for display or report purposes.
This provider can be used to collect variances in real-time or historically for a date range.
Filters
The recipe variance analysis provider can accept the following filters:
Scope

This is a required filter to specify the scope of what to include in

the results:
Date Range
Last Active Recipe - This will look for the last recipe selection
in the variance log and only include the associated variances in
the results. This can be used to monitor active runs or the last
run if the recipe has been canceled.
Example when using it with the Analysis Controller:
Scope=Last Active Recipe

Item Path

This is a required filter to specify the production item to include in

the results. It is the item path for the desired item path(s).
Because analysis is independent of projects, the project name is
required in the item path.
Example when using it with the Analysis Controller:
Item Path=RecipeDemo\Enterprise\Site\Area 1\Line 1, Item
Path=RecipeDemo\Enterprise\Site\Area 1\Line 2

Children

This is a filter to specify if children of the production item(s)

specified in the Item Path filter should be included.
Only one of the valid options are required:
Include
Exclude (Default)
Example when using it with the Analysis Controller:
Children=Include

Inductive Automation

Recipe / Changeover
Recipe Name

812

This is a filter to limit the recipe(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Name=Recipe A, Recipe Name=Recipe B

Recipe Value Name

This is a filter to limit the recipe value(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Value Name=Line Speed, Recipe Value Name=Force

Values

This is a filter to specify the type of recipe values to include.

Only one of the valid options are required:
Initial Values - Include only the initial recipe values when the
recipe was first selected.
Changed Values - Include only recipe values that changed after
the initial values were set.
Both - Include both initial and changed values.
Example when using it with the Analysis Controller:
Values=Both

Compare By
The recipe variance analysis provider does not allow any comparison statements.
Data Points
The recipe variance analysis provider can accept the following data points:
Description

This is the description from the recipe value configuration that

was entered in the designer.

From Value

This is the value of the Ignition tag associated with the recipe
value before it changed

Item Path

This is the item path of the production item for the recipe value.

Recipe Name

This is the name of the recipe at the time when the recipe value
changed.

Recipe Value

The value that is defined in the recipe.

Time Stamp

The date and time the recipe value changed.

To Value

This is the value of the Ignition tag associated with the recipe
value after it changed.

Units

This is the units from the associated Ignition tag.

Inductive Automation

Recipe / Changeover

Value Name

6.5.3

813

This is the name from the recipe value configuration that was
entered in the designer.

Sub Product Code Variance Analysis Provider

The sub product code variance analysis provider is used to collect sub product code variances for display
or report purposes. This provider can be used to collect variances in real-time or historically for a date
range.
Filters
The recipe variance analysis provider can accept the following filters:
Scope

This is a required filter to specify the scope of what to include in

the results:
Date Range
Last Active Sub Recipe - This will look for the last sub product
code selection in the variance log and only include the
associated variances in the results. This can be used to
monitor active runs or the last run if the sub recipe has been
canceled.
Example when using it with the Analysis Controller:
Scope=Last Active Sub Recipe

Item Path

This is a required filter to specify the production item to include in

the results. It is the item path for the desired item path(s).
Because analysis is independent of projects, the project name is
required in the item path.
Example when using it with the Analysis Controller:
Item Path=RecipeDemo\Enterprise\Site\Area 1\Line 1, Item
Path=RecipeDemo\Enterprise\Site\Area 1\Line 2

Children

This is a filter to specify if children of the production item(s)

specified in the Item Path filter should be included.
Only one of the valid options are required:
Include
Exclude (Default)
Example when using it with the Analysis Controller:
Children=Include

Recipe Value Name

This is a filter to limit the recipe value(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Value Name=Line Speed, Recipe Value Name=Force

Inductive Automation

Recipe / Changeover
Sub Recipe Name

814

This is a filter to limit the sub recipe(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Name=1A, Recipe Name=1B

Values

This is a filter to specify the type of recipe values to include.

Only one of the valid options are required:
Initial Values - Include only the initial recipe values when the
recipe was first selected.
Changed Values - Include only recipe values that changed after
the initial values were set.
Both - Include both initial and changed values.
Example when using it with the Analysis Controller:
Values=Both

Compare By
The sub product code variance analysis provider does not allow any comparison statements.
Data Points
The sub product code variance analysis provider can accept the following data points:
Description

This is the description from the recipe value configuration that

was entered in the designer.

From Value

This is the value of the Ignition tag associated with the recipe
value before it changed

Item Path

This is the item path of the production item for the recipe value.

Sub Recipe Name

This is the name of the sub recipe at the time when the recipe
value changed.

Recipe Value

The value that is defined in the recipe.

Recipe Value Name

This is the name from the recipe value configuration that was
entered in the designer.

Time Stamp

The date and time the recipe value changed.

To Value

This is the value of the Ignition tag associated with the recipe
value after it changed.

Units

This is the units from the associated Ignition tag.

Inductive Automation

Recipe / Changeover

6.5.4

815

Recipe Change Log Analysis Provider

The recipe change log analysis provider is used to collect the change log entries for display or report
purposes. All details of changes made to recipes including adding new recipes, adding production items
to recipes and much more can be returned using the recipe change log analysis provider.
Filters
The recipe change log analysis provider can accept the following filters:
Category

This is a required filter to specify the type of recipes to return.

One or more of the valid options are required:
Recipe - This includes all recipe changes excluding value
changes.
Recipe Value - This includes only recipe value changes.
Sub Recipe - This includes default value or sub recipe
changes excluding value changes.
Sub Recipe Value - This includes default value or sub recipe
value changes.
Example when using it with the Analysis Controller:
Category=Recipe, Category=Recipe Value

Item Path

This is a required filter to specify the production item to include in

the results. It is the item path for the desired item path(s).
Because analysis is independent of projects, the project name is
required in the item path.
Example when using it with the Analysis Controller:
Item Path=RecipeDemo\Enterprise\Site\Area 1\Line 1, Item
Path=RecipeDemo\Enterprise\Site\Area 1\Line 2

Children

This is a filter to specify if children of the production item(s)

specified in the Item Path filter should be included.
Only one of the valid options are required:
Include
Exclude (Default)
Example when using it with the Analysis Controller:
Children=Include

Recipe Name

This is a filter to limit the recipe(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Name=Recipe A, Recipe Name=Recipe B

Recipe Value Name

This is a filter to limit the recipe value(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Value Name=Line Speed, Recipe Value Name=Force

Inductive Automation

Recipe / Changeover
Sub Recipe Name

816

This is a filter to limit the sub recipe(s) to include in the results.

Example when using it with the Analysis Controller:
Recipe Name=1A, Recipe Name=1B

Compare By
The recipe analysis provider does not allow any comparison statements.
Data Points
The recipe analysis provider can accept the following data points:
Change Type

This is a description of the type of change. For example: it can be

Recipe value changed or Recipe value reverted.

Changed By

This is the person that made the change.

Description

This is the description from the recipe value configuration that

was entered in the designer.

From Value

This is the value before the change.

Info

This is additional information that further describes the change.

Item Path

This is the item path of the production item that the change was
made for.

Note

This is the note that was entered by the user at the time of the
change.

Recipe Name

This is the name of the recipe the change was made for.

Sub Product Code

This is the sub product code the change was made for.

Time Stamp

The date and time of the changed.

To Value

This is the value after the change.

Units

This is the units from the associated Ignition tag.

Inductive Automation

Recipe / Changeover
Value Name

Inductive Automation

817

This is the name from the recipe value configuration that was
entered in the designer.

Recipe / Changeover

6.6

818

Production OPC Values

This references details the production OPC values that the Recipe / Changeover Module provides. For
each property, the Ignition data type is listed and if it is read only. The Ignition data types correspond to the
data types that are available for SQLTags.
Within this reference, the "Read Only" means that the OPC value cannot be written to through the OPC
Production Server. It can only be set in the designer or it is a calculated value. Trying to write to a read
only property will result in an error message being shown.
Depending on the MES modules that are installed into the Ignition server, more or less production OPC
values will appear when browsing. For example, if only the Recipe / Changeover Module is installed, then
only production OPC values that the core MES or Recipe / Changeover Module provide will appear.

6.6.1

Enterprise

Description
The enterprise folder contains some properties associated with the enterprise and a folder for each
production Site within it. The name is the same as the enterprise name that is configured in the designer.
The image below represents the "Enterprise" of the RecipeDemo project.

Enterprise

Child Folders
Site

One folder will exist for each Site that has been configured in the Ignition Designer.
The folder can be opened to view all values within the site.

Properties

Inductive Automation

Recipe / Changeover
Analysis Auxiliary DB Connection Name

Analysis DB Connection Name

Description

Enabled

Name

Runtime DB Connection Name

6.6.2

The name of the auxiliary

(mirror) analysis database
connection. Can be blank if no
auxiliary DB connection is
configured.
The name of the analysis
database connection.

String
Read Only

Optionally, this property can be

set to a description for the
enterprise. It is not used by the
MES modules other than for
reference.
This reflects the enterprise
Enabled property in the
Designer. If the enterprise
Enabled is set to true, then the
MES production model will
perform calculations for the
enterprise and all sites, areas,
lines, cells, cell groups and
location within it. If this property
is set to false, then none of the
sites, areas, lines, cells, cell
groups and locations will have
calculations performed.
This reflects the name of the
enterprise that is set in the
designer.

String

The name of the runtime

database connection.

String
Read Only

819

String
Read Only

Boolean

String
Read Only

Site

Description
The site folder contains some properties associated with the production site and a folder for each
production area within it. The name is the same as the site name that is configured in the designer. The
image below represents the "Your Site" of the OEEDemo project.

Inductive Automation

Recipe / Changeover

820

Site

Child Folders
Area
RecipeValue

One folder will exist for each area that has been configured in the Ignition Designer.
The folder can be opened to view all values within the area.
Any recipe values that are configured for the production site will appear in this folder.

Properties
Description

Optionally, this property can be set to a description for the

site. It is not used by the OEE Downtime and Scheduling
Module other than for reference.

String

Enabled

This reflects the site Enabled property in the Designer. If the

site Enabled is set to true, then the OEE Downtime and
Scheduling module will perform calculations for the site and
all areas, lines and cells within it. If this property is set to
false, then none of the areas, lines or cells will have
calculations performed.

Boolean

Name

This reflects the name of the site that is set in the designer.

String
Read Only

6.6.3

Area

Description
The area folder contains some properties associated with the production area and a folder for each
production line within it. The name is the same as the area name that is configured in the designer. The
image below represents the "Your Area" of the OEEDemo project.

Inductive Automation

Recipe / Changeover

821

Area

Child Folders
One folder will exist for each Line that has been configured in the Ignition Designer. The
folder can be opened to view all values within the line.
RecipeValue Any recipe values that are configured for the production area will appear in this folder.
Line

Properties
Description

Optionally, this property can be set to a description for the area. It is

not used by the OEE Downtime and Scheduling Module other than for
reference.

String

Enabled

This reflects the site Enabled property in the Designer. If the area
Enabled is set to true, then the OEE Downtime and Scheduling
module will perform calculations for the area and all lines and cell
within it. If this property is set to false, then none of the lines or cells
will have calculations performed.

Boolean

Name

This reflects the name of the area that is set in the designer.

String
Read Only

6.6.4

Line

Description
The line folder contains some properties associated with the production line and a folder for each
production cell within it. The name is the same as the line name that is configured in the designer. The
image below represents the "Line 1" of the OEEDemo project.

Inductive Automation

Recipe / Changeover

822

Line

Child Folders
RecipeValue

Any recipe values that are configured for the production line will appear in this folder.

Cell

One folder will exist for each Cell that has been configured in the Ignition Designer.
The folder can be opened to view all values within the cell.

Inductive Automation

Recipe / Changeover

823

Properties
ActiveRecipeName

If a recipe is active for this production line,

then this is the name of the recipe. If a
recipe is not active, then this is blank.

String
Read Only

RecipeLoading

True if a recipe is currently being loaded

for the production line.

Boolean
Read Only

RecipeActive

Indicates if a recipe is currently active.

Boolean
Read Only

RecipeScale

Set this to the amount to scale a recipe

prior to selecting a recipe for the
production line.
This is a unique value used for tracking
initial recipe values and variances while a
recipe is selected. It can be used when
looking up data directly from the database.

Double

RecipeVariancesExists

If true, then Ignition tags associated with at

least one recipe value for this production
item have changed.

Boolean
Read Only

RecipeWriteError

If true, then at least one recipe value did

not write to the associated Ignition tags
when the recipe was first selected.

Boolean
Read Only

ValueMonitorEnabled

If true, recipe values are being monitored

and recipe value variances will be logged.

Boolean
Read Only

EnableRecipe

Set to true to allow recipes to be selected

for this production item. This is useful
when selecting a recipe for a production
line and preventing selecting the same
recipe for selected child production items.

Boolean

RecipeTrackingUUID

6.6.5

String
Read Only

Cell

Description
The cell folder contains some properties associated with the production cell. The name is the same as
the cell name that is configured in the designer. The image below represents the Filler of the OEEDemo
project.

Inductive Automation

Recipe / Changeover

824

Cell

Child Folders
RecipeValue

Any recipe values that are configured for the production cell will appear in this
folder.

Properties
ActiveRecipeName

If a recipe is active for this production cell,

then this is the name of the recipe. If a
recipe is not active, then this is blank.

String
Read Only

RecipeLoading

True if a recipe is currently being loaded

for the production cell.

Boolean
Read Only

RecipeActive

Indicates if a recipe is currently active.

Boolean
Read Only

RecipeScale

Set this to the amount to scale a recipe

prior to selecting a recipe for the
production cell.
This is a unique value used for tracking
initial recipe values and variances while a
recipe is selected. It can be used when
looking up data directly from the database.

Double

RecipeTrackingUUID

String
Read Only

Inductive Automation

Recipe / Changeover
RecipeVariancesExists

If true, then Ignition tags associated with at

least one recipe value for this production
item have changed.

Boolean
Read Only

RecipeWriteError

If true, then at least one recipe value did

not write to the associated Ignition tags
when the recipe was first selected.

Boolean
Read Only

ValueMonitorEnabled

If true, recipe values are being monitored

and recipe value variances will be logged.

Boolean
Read Only

EnableRecipe

Set to true to allow recipes to be selected

for this production item. This is useful
when selecting a recipe for a production
line and preventing selecting the same
recipe for selected child production items.

Boolean

6.6.6

825

Cell Group

Description
The cell folder contains some properties associated with the production cell. The name is the same as
the cell name that is configured in the designer. The image below represents the Filler of the OEEDemo
project.

Cell

Inductive Automation

Recipe / Changeover

826

Inductive Automation

Recipe / Changeover

827

Child Folders
Cell
RecipeValue

One folder will exist for each Cell that has been configured in the Ignition
Designer. The folder can be opened to view all values within the cell.
Any recipe values that are configured for the production cell group will
appear in this folder.

Properties
ActiveRecipeName

If a recipe is active for this production cell,

then this is the name of the recipe. If a
recipe is not active, then this is blank.

String
Read Only

RecipeLoading

True if a recipe is currently being loaded

for the production cell group.

Boolean
Read Only

RecipeActive

Indicates if a recipe is currently active.

Boolean
Read Only

RecipeScale

Set this to the amount to scale a recipe

prior to selecting a recipe for the
production cell group.
This is a unique value used for tracking
initial recipe values and variances while a
recipe is selected. It can be used when
looking up data directly from the database.

Double

RecipeVariancesExists

If true, then Ignition tags associated with at

least one recipe value for this production
item have changed.

Boolean
Read Only

RecipeWriteError

If true, then at least one recipe value did

not write to the associated Ignition tags
when the recipe was first selected.

Boolean
Read Only

ValueMonitorEnabled

If true, recipe values are being monitored

and recipe value variances will be logged.

Boolean
Read Only

EnableRecipe

Set to true to allow recipes to be selected

for this production item. This is useful
when selecting a recipe for a production
line and preventing selecting the same
recipe for selected child production items.

Boolean

RecipeTrackingUUID

6.6.7

String
Read Only

Location

Description
The cell folder contains some properties associated with the production cell. The name is the same as
the cell name that is configured in the designer. The image below represents the Filler of the OEEDemo
project.

Inductive Automation

Recipe / Changeover

828

Cell

Inductive Automation

Recipe / Changeover

Child Folders
RecipeValue

Any recipe values that are configured for the production location will
appear in this folder.

Properties
ActiveRecipeName

If a recipe is active for this production cell,

then this is the name of the recipe. If a
recipe is not active, then this is blank.

String
Read Only

RecipeLoading

True if a recipe is currently being loaded

for the production location.

Boolean
Read Only

RecipeActive

Indicates if a recipe is currently active.

Boolean
Read Only

RecipeScale

Set this to the amount to scale a recipe

prior to selecting a recipe for the
production location.
This is a unique value used for tracking
initial recipe values and variances while a
recipe is selected. It can be used when
looking up data directly from the database.

Double

RecipeVariancesExists

If true, then Ignition tags associated with at

least one recipe value for this production
item have changed.

Boolean
Read Only

RecipeWriteError

If true, then at least one recipe value did

not write to the associated Ignition tags
when the recipe was first selected.

Boolean
Read Only

ValueMonitorEnabled

If true, recipe values are being monitored

and recipe value variances will be logged.

Boolean
Read Only

EnableRecipe

Set to true to allow recipes to be selected

for this production item. This is useful
when selecting a recipe for a production
line and preventing selecting the same
recipe for selected child production items.

Boolean

RecipeTrackingUUID

Inductive Automation

String
Read Only

829

Recipe / Changeover

6.7

830

Scripting

This section is a reference for scripting functions provided by the Recipe Module. It also has a reference
for any objects that are used by or returned by the scripting functions.

6.7.1

Client / Gateway Scripts

The Recipe / Changeover Module exposes many script functions that support managing recipes. In fact,
the internal functions used by the recipe editor and other recipe components are exposed as script
functions that can be used on the client or the gateway.
6.7.1.1

getDefaultValues

system.recipe.getDefaultValues(projectName, itemPath, category, subProductCode)

Return values for a sub recipe based on a product code or default values for a production item.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the

gateway. When called from the client, the project is the
same as current project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line
1"
Data Type
String

category

Category of recipe values to return. Where 1 is recipe values

created by the recipe module, 2 is recipe values created by
the OEE module and 3 is recipe values created by the SPC
module. Use blank to include all categories.
Data Type
String

subProductCode

Sub product code to return values for, or else leave blank to

read the default values for the production item.
Data Type
String

returns
List< ItemRecipeValue>

A list of ItemRecipeValue objects.

Data Type
String

Example
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
#Request the default values for the selected production item
list = system.recipe.getDefaultValues(itemPath, "1", "")
system.gui.messageBox(str(list.size()))
for rv in list:
system.gui.messageBox("%s = %s" % (rv.getName(), str(rv.getValue())))

Inductive Automation

Recipe / Changeover
6.7.1.2

831

setPathDefaultValue

system.recipe.setPathDefaultValue(projectName, itemPath, subProductCode, valueName, value,

note)

Set a production item sub recipe or default value.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

subProductCode

Sub product code to set value for, or else leave blank to set the
default value for the production item.
Data Type
String

valueName

User name for this comment

Data Type

value

Set the recipe value to this value.

Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

String

Recipe / Changeover
6.7.1.3

832

revertPathDefaultValue

system.recipe.revertPathDefaultValue(projectName, itemPath, subProductCode, valueNames, note)

Revert production item default values back to be inherited from the parent.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

subProductCode

Sub product code to revert value(s) for, or else leave blank to

revert the default value(s) for the production item.
Data Type
String

valueNames

One or more recipe value names separated by commas to revert.

Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

Recipe / Changeover
6.7.1.4

833

createSubProductCode

system.recipe.createSubProductCode(projectName, itemPath, subProductCode, note)

Create a new sub product code (sub recipe).

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

subProductCode

New sub product code.

Data Type

note

returns
none

Inductive Automation

String

Optional note to be stored in the recipe change log.

Data Type
String

Recipe / Changeover
6.7.1.5

834

renameSubProductCode

system.recipe.renameSubProductCode(projectName, itemPath, existingSubProductCode,

newSubProductCode, note)

Adds a comment note to the current run for the selected line.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the

gateway. When called from the client, the project is the
same as current project for the client.
Data Type
String

linePath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line
1"
Data Type
String

existingSubProductCode Existing sub product code name.

newSubProductCode

note

Data Type

String

New sub product code name.

Data Type

String

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

Recipe / Changeover
6.7.1.6

835

deleteSubProductCode

system.recipe.deleteSubProductCode(projectName, itemPath, subProductCode, note)

Delete sub product code.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

subProductCode

Sub product code name.

Data Type

note

returns
none

Inductive Automation

String

Optional note to be stored in the recipe change log.

Data Type
String

Recipe / Changeover
6.7.1.7

836

setPathRecipeValue

system.recipe.setPathRecipeValue(projectName, itemPath, recipeName, valueName, value, note)

Set production item recipe value.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

recipeName

Name of recipe.
Data Type

String

Recipe value name to set.

Data Type

String

valueName

value

New value to assign to recipe value.

Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none
Example:
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
recipe = 'Recipe C1 6Pk'
valueName = 'Line Speed'
value = '99'
system.recipe.setPathRecipeValue(itemPath, recipe, valueName, value, '')

Inductive Automation

Recipe / Changeover
6.7.1.8

837

revertPathRecipeValues

system.recipe.revertPathRecipeValues(projectName, itemPath, recipeName, valueNames, note)

Revert production item recipe values back to the parent production item.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

recipeName

Name of recipe.
Data Type

valueNames

One or more recipe value names separated by commas to revert.

Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

String

Recipe / Changeover
6.7.1.9

838

createRecipe

system.recipe.createRecipe(projectName, recipeName, parentRecipeName, note)

Create new recipe.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

recipeName

Name of new recipe.

Data Type

String

parentRecipeName

Name of parent recipe to base this recipe. Leave blank if new

recipe is not based on any other recipe.
Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

Recipe / Changeover

839

6.7.1.10 renameRecipe
system.recipe.renameRecipe(projectName, existingRecipeName, newRecipeName, note)

Rename specified recipe.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the

gateway. When called from the client, the project is the
same as current project for the client.
Data Type
String

existingRecipeName Name of the existing recipe.

newRecipeName

note

returns
none

Inductive Automation

Data Type

String

New recipe name.

Data Type

String

Optional note to be stored in the recipe change log.

Data Type
String

Recipe / Changeover

840

6.7.1.11 deleteRecipe
system.recipe.deleteRecipe(projectName, recipeName, note)

Delete specified recipe.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

recipeName

Name of the recipe to delete.

Data Type

note

String

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

Recipe / Changeover

841

6.7.1.12 addItemToRecipe
system.recipe.addItemToRecipe(projectName, recipeName, itemPath, note)

Add a production item to a recipe. Once a production item is added to a recipe, the recipe values for the
production item can be managed. Also, the recipe can be selected for the added production item.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

recipeName

Name of the recipe to add the specified production item.

Data Type
String

itemPath

The item path to the production line, cell, cell group or location to
add to the recipe.
For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

Recipe / Changeover

842

6.7.1.13 removeItemFromRecipe
system.recipe.removeItemFromRecipe(projectName, recipeName, itemPath, note)

Remove a production item from a recipe.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

recipeName

Name of the recipe to remove the specified production item.

Data Type
String

linePath

The item path to the production line, cell, cell group or location to
remove from the recipe.
For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

Recipe / Changeover

843

6.7.1.14 getChangelogHistory
system.recipe.getChangelogHistory(projectName, changelogFilters)

Based on the filters set in the changelogFilters parameter, return change log history for recipe. See
Recipe Change Log for more information.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters

returns

projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

changelogFilters

Change log filters (See ChangelogFilters object for more

information).
Data Type
ChangelogFilters

A Dataset object containing rows and columns of change log history.

Dataset

Example
#Collect values we want to filter by
projectName = system.util.getProjectName()
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
fromDate = event.source.parent.getComponent('Date Range').startDate
toDate = event.source.parent.getComponent('Date Range').endDate
#Build the filters object
filters = system.recipe.filter.changelog.createNew()
filters.setProjectName(projectName)
filters.addCategory("Recipe")
filters.setItemPathFilter(itemPath)
filters.setFromDate(fromDate)
filters.setToDate(toDate)
#Request the change log for the given filters
ds = system.recipe.getChangelogHistory(filters)
event.source.parent.getComponent('Table').data = ds

Inductive Automation

Recipe / Changeover

844

6.7.1.15 getRecipeVariances
system.recipe.getRecipeVariances(projectName, varianceFilters)

Based on the filters set in the varianceFilters parameter, return recipe value variances. See Variance
Monitoring for more information.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters

returns

projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

varianceFilters

Change log filters (See VarianceFilters object for more

information).
Data Type
VarianceFilters

A Dataset object containing rows and columns of recipe value variances.

Dataset

Example
#Collection values we want to filter by
projectName = system.util.getProjectName()
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
#Build the filters object
filters = system.recipe.filter.variance.createNew()
filters.setProjectName(projectName)
filters.setVarianceEntryType("Recipe")
filters.setVarianceScopeTypes("Last")
filters.setItemPath(itemPath)
#Request the variances for the given filters
ds = system.recipe.getRecipeVariances(filters)
event.source.parent.getComponent('Table').data = ds

Inductive Automation

Recipe / Changeover

845

6.7.1.16 getItemRecipeList
system.recipe.getItemRecipeList(projectName, itemPath, recipeFilter)

Return the current recipes available for a production item.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

recipeFilter

Optional recipe filter. The filter can contain ? and * wild card
characters.
Data Type
String

returns
List<String>
Example
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
#Request the available recipes for the selected production item.
list = system.recipe.getItemRecipeList(itemPath, "Recipe C*")
for recipeName in list:
system.gui.messageBox(recipeName)

Inductive Automation

Recipe / Changeover

846

6.7.1.17 getCurrentItemRecipe
system.recipe.getCurrentItemRecipe(projectName, itemPath)

Return the current selected recipe name for a production item.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters

returns

projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

Current selected recipe name of specified production item.

String

Inductive Automation

Recipe / Changeover

847

6.7.1.18 getRecipeValues
system.recipe.getRecipeValues(projectName, itemPath, recipeName, category)

Return recipe values for a production item and recipe combination.

This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

recipeName

The recipe name.

Data Type

category

returns

String

Category of recipe values to return. Where 1 is recipe values

created by the recipe module, 2 is recipe values created by the
OEE module and 3 is recipe values created by the SPC module.
Use blank to include all categories.
Data Type
String

A list of ItemRecipeValue objects (See ItemRecipeValue object for more information).

List<ItemRecipeValue>
Data Type

Example
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
#Request the recipe values for production item and recipe combination.
list = system.recipe.getRecipeValues(itemPath, "Recipe C1 6Pk", "1")
system.gui.messageBox(str(list.size()))
for rv in list:
system.gui.messageBox("%s = %s" % (rv.getName(), str(rv.getValue())))

Inductive Automation

Recipe / Changeover

848

6.7.1.19 isItemRecipeMonitoringEnabled
system.recipe.isItemRecipeMonitoringEnabled(projectName, itemPath)

Return recipe value monitoring enabled state. See Variance Monitoring for more information.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters

returns

projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

True, if recipe value monitoring is enabled.

Boolean

Inductive Automation

Recipe / Changeover

849

6.7.1.20 setItemRecipe
system.recipe.setItemRecipe(projectName, itemPath, recipeName, enableValueMonitoring)

Set the recipe for the production item specified by the itemPath parameter. If the production item is a line,
then all children production items of the line will also be set to the same recipe provided they were added
to the recipe.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the

gateway. When called from the client, the project is the
same as current project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line
1"
Data Type
String

recipeName

The name of the recipe.

Data Type

String

enableValueMonitoring If true, turn on recipe value variance monitoring. See Variance

Monitoring for more information.

Data Type
Boolean
returns
none

Inductive Automation

Recipe / Changeover

850

6.7.1.21 cancelItemRecipe
system.recipe.cancelItemRecipe(projectName, itemPath)

Cancel the current recipe for the production item specified by the itemPath parameter. If the production
item is a line, then the recipe for all children production items of the line will also be canceled.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

returns
none

Inductive Automation

Recipe / Changeover

851

6.7.1.22 readItemCurrentValues
system.recipe.readItemCurrentValues(projectName, itemPath, includeChildren, recipeName,
subProductCode, valueNames, note)

Set the recipe values to the current tag value(s) for the production item specified by the itemPath
parameter.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameter
s
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

includeChildren

If true, also set the recipe values for children of the items.
Data Type
Boolean

recipeName

The name of the recipe (only applies for recipes).

Data Type
String

subProductCode

The sub product code (only applies for sub recipes).

Data Type
String

valueNames

The name(s) of the recipe values to set to current tag values.

Separate multiple recipe value names with commas. For all recipe
values of a production item, leave blank.
Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Inductive Automation

Recipe / Changeover

852

6.7.1.23 exportRecipe
system.recipe.exportRecipe(projectName, filters)

Adds a comment note to the current run for the selected line. See the Import / Export section of Editing
Recipes for CSV file format and other information.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters

returns

projectName

The project name. Only include when called from the

gateway. When called from the client, the project is the same
as current project for the client.
Data Type
String

filters

Filter statements separated by commas. See the Recipe Analysis

Provider for more information on the available filters.
Data Type
String

CSV formatted string containing the recipe values.

String

Example
itemPath = event.source.parent.getComponent('Production Line Selector').selectedLinePath
filters = "Children=Include,Recipe Name=Master C,Item Path=%s" % (itemPath)
csv = system.recipe.exportRecipe(filters)
system.file.writeFile("C:\\Temp\\recipe_export.csv", csv, False)

Inductive Automation

Recipe / Changeover

853

6.7.1.24 importRecipe
system.recipe.importRecipe(projectName, csvData, note)

Set the recipe values to the current tag value(s) for the production item specified by the itemPath
parameter. See the Import / Export section of Editing Recipes for CSV file format and other information.
Values that are outside of the range defined in the recipe values security will not be imported. When this
happens, an exception is returned listing all of the values that were not imported. See Recipe Security for
more information.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parameters
projectName

The project name. Only include when called from the gateway.
When called from the client, the project is the same as current
project for the client.
Data Type
String

csvData

String in CSV format containing recipe values. Must be the same

format that is returned by the exportRecipe function.
Data Type
String

note

Optional note to be stored in the recipe change log.

Data Type
String

returns
none

Example
csv = system.file.readFileAsString("C:\\Temp\\recipe_export.csv")
itemPath = event.source.parent.getComponent('Production Line Selector').selectedLinePath
system.recipe.importRecipe(csv, "Values set during import.")

Inductive Automation

Recipe / Changeover

854

6.7.1.25 getRecipeValueSecurity
system.recipe.getRecipeValueSecurity(projectName, itemPath, valueName, inherited)

Returns a RecipeValueSecurityInfo object that contains each security roles settings. Retrieve a role by
using the getSecurityRole method of the object.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parame
t
e
r
s
projectName

The project name. Only include when called from the gateway. When
called from the client, the project is the same as current project for the
client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

valueName

The recipe value name to get the security settings for.

Data Type
String

inherited

Set to 0 to get the value settings. If set to 1, it will return the inherited
settings.
Data Type
Boolean
returns A RecipeValueSecurityInfo object.
Object

Example
# Get a recipe value security and display it in a text area
#
textArea = event.source.parent.getComponent('Text Area')
textArea.text = ''
itemPath = event.source.parent.getComponent('Production Line Selector').
selectedPathWithoutProject
recipeName = event.source.parent.getComponent('Recipe Selector Combo').selectedRecipeName
userRole = 'Operators'
result = ''
secdata = ''
# first, get the list of all recipe value names and cycle thru the list
list = system.recipe.getRecipeValues(itemPath, recipeName,"")
for rv in list:
# get the security object (RecipeValueSecurityInfo) for the recipe value name
recipeValueSecurityInfo = system.recipe.getRecipeValueSecurity(itemPath, rv.getName(), 0)
# get the RecipeValueSecurityRole object for a user role from the security object
recipeValueSecurityRole = recipeValueSecurityInfo.getSecurityRoll(userRole)
if recipeValueSecurityRole != None:
Inductive Automation

Recipe / Changeover

855

secdata = "%s \n %s: userRole=%s min val=%s, max val=%s" % (secdata,rv.getName(),

userRole, str(recipeValueSecurityRole.getMinValue()), str(recipeValueSecurityRole.getMaxValue
()) )
result = "%s\n\nSECURITY values: %s" %(result, secdata)
textArea.text = result

6.7.1.26 getItemLiveRecipeValues
system.recipe.getLiveRecipeValues(projectName, itemPath, valueName, inherited)

Returns a list of recipe value names and their current live values.
This script function can be used in gateway client scripts. When called from the client, omit the
projectName parameter.
parame
t
e
r
s
projectName

The project name. Only include when called from the gateway. When
called from the client, the project is the same as current project for the
client.
Data Type
String

itemPath

The item path to a production line, cell, cell group or location.

For example: "Your Enterprise\Your Site\Your Area\Line 1"
Data Type
String

recipeName

Name of the recipe to remove the specified production item.

Data Type
String

subProductCode

Sub product code to return values for, or else leave blank to read the default
values for the production item.
Data Type
String

valueNames

The recipe value names to get the live values for, or leave blank for all
recipe values.
Data Type
String

returns Returns a list of recipe value names and their current live values.
list

Example
# Get the current live values (tag values) for a recipe
#
textArea = event.source.parent.getComponent('Text Area')
textArea.text = ''
itemPath = event.source.parent.getComponent('Production Line Selector').
selectedPathWithoutProject
Inductive Automation

Recipe / Changeover

856

recipeName = event.source.parent.getComponent('Recipe Selector Combo').selectedRecipeName

userRole = 'Operators'
result = ''
data = ''
# get a map of the recipe value names and the current tag values referenced by the recipe
map = system.recipe.getItemLiveRecipeValues(itemPath, recipeName,"", "")
for rv in map:
data = "%s\n
%s=%s" %(data, rv, map[rv])
result = "%s\n\nLIVE values: %s" %(result, data)
textArea.text = result

6.7.2

Recipe Value Scripts

When recipe values are added to a production item, there are properties that allow script to be entered.
The following sections detail the different events and how they are used. See Adding a Recipe Value for
more information.
6.7.2.1

Evaluate Variance Script

If the Evaluate Variance Script property (see Adding a Recipe Value for more information) of a production
item contains a script, it will be executed every time an Ignition tag associated with a recipe value
changes. Variance monitoring must also be active. When it is executed, the event object provides
information about the recipe value being evaluated. If event.setLogVariance(logVariance) is not called,
then the log variance state determined before this event will be used. See Variance Monitoring for more
information.
Event Properties
event.getRecipeTag()

Returns RecipeTag object associated with recipe value. The

RecipeTag object contains details about the recipe value and
associated Ignition tag. (See RecipeTag object for more
information).
Data Type
RecipeTag

event.getScale()

Returns the recipe scale being used when the recipe was
selected.
Data Type
Double

event.isLogVariance()

Returns the current log variance state for the recipe value. If true,
a variance will be logged.
Data Type
Boolean

event.setLogVariance(logVariance) param eters

logVariance
Data Type

If true a variance will be logged.

Boolean

returns

none

Example
upperLimit = system.tag.read("[Default]UpperLimit")
lowerLimit = system.tag.read("[Default]LowerLimit")
recipeValue = event.getRecipeTag().getCurrentValue()
if recipeValue > upperLimit.value or recipeValue < lowerLimit.value:
Inductive Automation

Recipe / Changeover

857

event.setLogVariance(True)
else:
event.setLogVariance(False)

6.7.2.2

Request Value Script

If the Request Value Script property (see Adding a Recipe Value for more information) of a production
item contains a script, it will be executed every time a recipe is selected. When it is executed, the event
object provides information about the recipe value being read. If event.setRecipeValue(value) is not called,
then the value from the database will be used.
Event Properties
event.getItemPath()

Returns the production item path that recipe value belongs to.
Data Type
String

event.getValueName()

Returns the name of the recipe value being read.

Data Type
String

event.getTagPath()

Returns the Ignition tag path associated with the recipe value.
Data Type
String

event.getScale()

Returns the recipe scale being used while reading the current recipe.
Data Type
Double

event.getRecipeValue()

Returns the recipe value from the database. This is the value that was
set in the recipe editor or from a script function.
Data Type
String

event.setRecipeValue(value)

param eters

value
Data Type

Value to change the current recipe

value.
Data Type
String

returns

none

Example
import math
try:
value = float(event.getRecipeValue())
event.setRecipeValue(str(math.log10(value)))
except:
event.setRecipeValue("0")

6.7.3

Object Reference

The Recipe Module has script functions and events that use various objects. This is because some
recipe information contains more data than can be represented with a single primitive data type. For
example a recipe value has a name, description, units, format and more, and the ItemRecipeValue is
used to hold all of this information when returning back recipe value information from a script function.
The following sections provide documentation of the methods and properties associated with these
various objects.
Inductive Automation

Recipe / Changeover
6.7.3.1

858

ChangelogFilters

A ChangeLogFilters object is used when requesting recipe change logs with the getChangelogHistory
script function to narrow down the results that are returned. For example, if you only want the change log
history for a specific production item (machine) and specific date range, the ChangeLogFilters object
properties are set appropriately and are passed as parameters to the getChangelogHistory script
function.
methods:
createNew() - ChangeLogFilters
Returns a new instance of a ChangeLogFilters object. After setting various filter properties, it is
used with the getChangelogHistory script function.
properties:
setProjectName(String projectName)
Set the project name to read recipe change log history. Recipe change log history is kept by
project, and the project name is required with the getChangelogHistory script function.
addCategory(String category)
Add a category to include in the recipe change log history results. Multiple categories can be
specified to be included in the results. Valid values are
RECIPE to include change log entries dealing with recipe changes. Recipe changes include,
adding new recipes, renaming recipes, deleting recipes, adding production items to recipes,
etc.
RECIPE_VALUE to include change log entries dealing with changes of recipe values. This
includes changing a value, reverting a value back to be inherited, etc.
SUB_PRODUCT_CODE to include change log entries dealing with sub product codes. This
includes adding new sub product codes, renaming sub product codes, deleting sub product
codes, etc.
SUB_PRODUCT_CODE_VALUE to include change log entries dealing with changes of sub
product code values or default values for a production item. This includes changing a value,
reverting a value back to be inherited, etc.
removeCategory(String category)
Remove a category for what has already been added.
setFromDate(Date fromDate)
Set the start of the date range to return change log history for.
setToDate(Date toDate)
Set the end of the date range to return change log history for.
setItemPathFilter(String itemPath)
Set the path of the production item to return change log history for.
For example: "Your Enterprise\Your Site\Your Area\Line 1"
setRecipeNameFilter(String recipeName)
Set an optional recipe filter. The filter can contain ? and * wild card characters.
For example: "Recipe C*" will include all recipes that start with Recipe C. Recipe C1 and
Recipe C21 will be included but Recipe D1 will not.

Inductive Automation

Recipe / Changeover

859

setSubProductCodeFilter(String subProductCode)
Set an optional sub product code filter. The filter can contain ? and * wild card characters.
setUserFilter(String userName)
Set an optional user name filter. The filter can contain ? and * wild card characters.
setValueNameFilter(String recipeValueName)
Set an optional recipe value name filter. The filter can contain ? and * wild card characters.
Example
#Collect values we want to filter by
projectName = system.util.getProjectName()
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
fromDate = event.source.parent.getComponent('Date Range').startDate
toDate = event.source.parent.getComponent('Date Range').endDate
#Build the filters object
filters = system.recipe.filter.changelog.createNew()
filters.setProjectName(projectName)
filters.addCategory("Recipe")
filters.setItemPathFilter(itemPath)
filters.setFromDate(fromDate)
filters.setToDate(toDate)
#Request the change log for the given filters
ds = system.recipe.getChangelogHistory(filters)
event.source.parent.getComponent('Table').data = ds

6.7.3.2

VarianceFilters

A VarianceFilters object is used when requesting variances with the getRecipeVariances script function
to narrow down the results that are returned. For example, if you only want variances for a specific
production item (machine) and specific date range, the VarianceFilters object properties are set
appropriately and are passed as parameters to the getRecipeVariances script function.
methods:
createNew() - VarianceFilters
Returns a new instance of a VarianceFilters object. After setting various filter properties, it is
used with the getRecipeVariances script function.
properties:
setProjectName(String projectName)
Set the project name to read variances. Variances are kept by project, and the project name is
required with the getRecipeVariances script function.
setVarianceEntryType(String varianceType)
Set the variance types to include in the results. Valid values are
Inductive Automation

Recipe / Changeover

860

RECIPE to return variances that occurred while a production item was selected to a recipe.
SUB_RECIPE to return variances that occurred while a sub product code was selected for a
production item. See Sub Recipes for more information.
setVarianceScopeTypes(String varianceScopeType)
Set the variance scope to include in the results. Valid values are
LAST to return variances that occurred for the current or last recipe that a production item
was set. This is useful for detecting any variances in real time for a production run. If the
production run has stopped, it will return the variances as long as a new recipe has not been
selected for the production item.
DATE_RANGE to return variances for the date range specified with the setFromDate() and
setToDate() properties.
setFromDate(Date fromDate)
Set the start of the date range to return variances for if setVarianceScopeTypes
("DATE_RANGE") is called.
setToDate(Date toDate)
Set the end of the date range to return variances for if setVarianceScopeTypes
("DATE_RANGE") is called.
setItemPath(String itemPath)
Set the path of the production item to return variances for.
For example: "Your Enterprise\Your Site\Your Area\Line 1"
setIncludeChildren(Boolean includeChildren)
Set if children production items under the production item specified by the setItemPath()
property, should be included in the variance results.
setIncludeInitialValues(Boolean includeInitialValues)

Set if the initial values (meaning the values when the recipe was first selected) should be
included in the variance results.
setIncludeVarianceValues(Boolean includeVarianceValues)

Set if the variance values (meaning the values that changed after the recipe was first selected)
should be included in the variance results.
setRecipe(String recipeName)

Set an optional recipe filter. The filter can contain ? and * wild card characters.
For example: "Recipe C*" will include all recipes that start with Recipe C. Recipe C1 and
Recipe C21 will be included but Recipe D1 will not.
setSubRecipe(String subRecipeName)

Set an optional sub recipe filter. The filter can contain ? and * wild card characters. See Sub
Recipes for more information.
setRecipeValueName(String recipeValueName)

Set an optional recipe value name filter. The filter can contain ? and * wild card characters.
Example
#Collection values we want to filter by
Inductive Automation

Recipe / Changeover

861

projectName = system.util.getProjectName()
itemPath = event.source.parent.getComponent('Production Line Selector').selectedPathWithoutProject
#Build the filters object
filters = system.recipe.filter.variance.createNew()
filters.setProjectName(projectName)
filters.setVarianceEntryType("Recipe")
filters.setVarianceScopeTypes("Last")
filters.setItemPath(itemPath)
filters.setIncludeChildren(False)
#Request the variances for the given filters
ds = system.recipe.getRecipeVariances(filters)
event.source.parent.getComponent('Table').data = ds

6.7.3.3

ItemRecipeValue

A ItemRecipeValue object is returned by many of the recipe script methods, usually as a list of
ItemRecipeValue. Because a recipe value has several properties such as the name, minimum value,
maximum value, units, etc., the details are returned in this ItemRecipeValue object.
Recipe values also can have varying data types and an ItemRecipeValue object supports reading the
value in its true data type. For example, if a recipe value if of type Float8, then getValue(), getMinValue()
and getMaxValue() all return Float8 values. This cannot be done by returning the recipe values in a
Dataset where each column must be a single data type.
properties:
getName() - String
Returns the name of the recipe value. This is the same name entered in the recipe value entry
in the designer.
hasDescription() - Boolean
Returns True if a description exists for the recipe value.
getDescription - String
Returns the description of the recipe value. This is the description entered in the recipe value
entry in the designer.
hasDataType() - Boolean
Returns True if the recipe value has a data type assigned. Recipe values that do not have a tag
assigned to them will not have a data type. This is because the data type is obtained from the
tag.
getDataType() - DataType
Returns the Ignition DataType for the recipe value.
isValid() - Boolean
Returns True if the value is valid for the data type of the recipe value.
getValue() - Object
Inductive Automation

Recipe / Changeover

862

Returns the value of the recipe value. The data type will be one defined by the Ignition DataType.
If a value has not been assigned to the recipe value, then None will be returned and isValid() will
return false.
getMinValue() - Object
Returns the minimum value that the value can be as defined in the Ignition tag. This is different
from the recipe value security that depends on the authenticated user. See Recipe Security for
more information.
getMaxValue() - Object
Returns the maximum value that the value can be as defined in the Ignition tag. This is different
from the recipe value security that depends on the authenticated user. See Recipe Security for
more information.
getUnits() - Object
Returns the units as defined in the Ignition tag.
getFormat() - Object
Returns the format as defined in the Ignition tag.
getAssignedBy() - Object
Returns the recipe or production item default value where the recipe value is inherited from. If
the recipe value is not inherited, it will be the name of the recipe where it was overridden.
getCategory() - Object
Returns the MES module that created the recipe value. Where 1 is recipe value created by the
recipe module, 2 is recipe value created by the OEE module and 3 is recipe value created by
the SPC module.
Example
itemPath = event.source.parent.getComponent('Production Line Selector').
selectedPathWithoutProject
valueList = system.recipe.getDefaultValueItems(itemPath, "")
if valueList != None:
system.gui.messageBox("Count = %d" % valueList.size())
for itemRecipeValue in valueList:
system.gui.messageBox("%s = %s" % (itemRecipeValue.getName(),
itemRecipeValue.getValue()))

6.7.3.4

RecipeTag

A RecipeTag object contains details about a recipe value. It reflects the properties that are configured in
the designer when the recipe value was added plus some live information such as the current value. See
Adding a Recipe Value for more information.
properties:
getRecipeValueName() - String
Returns the name of the recipe value. This is the same name entered in the recipe value entry
Inductive Automation

Recipe / Changeover

863

in the designer.
getTagPath() - String
Returns the Ignition tag path assigned to the recipe value. This is the tag path entered for the
recipe value.
hasHighVarianceThresholdStatement() - Boolean
Returns True if a high variance threshold statement was entered for the recipe value.
getHighVarianceThresholdStatement() - String
Returns the high variance threshold statement that was entered for the recipe value entry.
getHighVarianceThresholdValue() - String
Returns the high variance threshold value. This is calculated after the tag value change is
detected and is used for default handling for the log variance state. It is provided here as a
convenience.
hasLowVarianceThresholdStatement() - Boolean
Returns True if a low variance threshold statement was entered for the recipe value.
getLowVarianceThresholdStatement() - String
Returns the low variance threshold statement that was entered for the recipe value entry.
getLowVarianceThresholdValue() - String
Returns the low variance threshold value. This is calculated after the tag value change is
detected and is used for default handling for the log variance state. It is provided here as a
convenience.
hasPreviousValue() - Boolean
Returns True if a previous value has been recorded for the recipe value.
getPreviousValue() - Object
Returns the previous value of the recipe value. Anytime the value of a tag associated with a
recipe value changes, the previous value is saved internally. This is used for the changed from
information in variance logging.
hasCurrentValue() - Boolean
Returns True if the recipe value has a value.
getCurrentValue() - Object
Returns the tag value of a tag associated with a recipe value.
isVarianceMonitorEnabled() - Boolean
Returns True if variance monitoring is enabled for the recipe value.
getDataType() - Object
Returns the data type of the tag associated with the recipe value.
getRecipeValue() - Object
Returns the recipe value. This can be the value that was entered in recipe editor, set using
script or inherited from a parent.
Inductive Automation

Recipe / Changeover

864

getRecipeValue(Double scale) - Object

Returns the recipe value adjusted by the scale parameter.
convertValue(String value) - Object
Returns the value passed in the parameter in the correct data type for the recipe value. If the
recipe value is an Int4, then the string value passed in the value parameter will be converted to
an Int4 data type and returned.
convertAndScaleValue(String value, Double scaleFactor) - Object
Returns the value passed in the parameter in the correct data type for the recipe value with
scaling.
scaleValue(Object value, Double scaleFactor) - Object
Scales and returns the value passed in the parameter in the same data type as the value
parameter.
Example
upperLimit = system.tag.read("[Default]UpperLimit")
lowerLimit = system.tag.read("[Default]LowerLimit")
recipeValue = event.getRecipeTag().getCurrentValue()
rt = event.getRecipeTag()
uLimit = rt.scaleValue(upperLimit.value, event.getScale())
lLimit = rt.scaleValue(lowerLimit.value, event.getScale())
if recipeValue > uLimit or recipeValue < lLimit:
event.setLogVariance(True)
else:
event.setLogVariance(False)

6.7.3.5

RecipeValueSecurityInfo

A RecipeValueSecurityInfo object contains the list of security roles for a recipe value.
properties:
getAssignedBy() - String
Returns the description of where this recipe value was assigned by.
getItemPath() - String
Returns the Ignition item path of the recipe value.
getItemRecipeValue() - Object
Returns a ItemRecipeValue object.
getSecurityRole(String roleName) - Object
Returns a RecipeValueSecurityRole object
6.7.3.6

RecipeValueSecurityRole

A RecipeValueSecurityRole object contains the security information for a security role for a recipe value.
properties:
Inductive Automation

Recipe / Changeover

getMaxValue() - Object
Returns the maximum value for this role.
getMinValue() - Object
Returns the minimum value for this role.
isAdministratorRole() - Boolean
Returns true if this role is 'Administrator'.
isAllowEdit() - Boolean
Returns true if this value is editable.

Inductive Automation

865

Web Services
Part VII

Web Services

Web Services

7.1

Introduction

868

The Web Services module extends the Ignition SUDS scripting functions with a visual interface to access
web services provided by other systems. The following sections provide an brief introduction to the
technologies used that make up web services. There are plenty of resources provided by the computing
industry if you wish to continue to learn more.

7.1.1

What Are Web Services

The W3C (World Wide Web Consortium) defines a Web service as a software system designed to
support interoperable machine-to-machine interaction over a network. It has an interface described in a
machine-processable format (specifically WSDL). Other systems interact with the Web service in a
manner prescribed by its description using SOAP messages, typically conveyed using HTTP with an XML
serialization in conjunction with other Web-related standards.
There are two major classes of Web services:
REST (Representational state transfer)-compliant Web services, in which the primary purpose of the
service is to manipulate XML representations of Web resources using a uniform set of stateless
operations.
Arbitrary Web services, in which the service may expose an arbitrary set of operations.
Currently only Arbitrary Web Services implemented via SOAP (Simple Object Access Protocol) are
supported in this release.

7.1.2

Network Communications

A web service is any piece of software that makes itself available over the internet and uses a
standardized XML messaging system. XML is used to encode all communications to a web service. For
example, a client invokes a web service by sending an XML message, then waits for a corresponding
XML response. Because all communication is in XML, web services are not tied to any one operating
system or programming language--Java can talk with Perl; Windows applications can talk with Unix
applications.
Web Services are self-contained, modular, distributed, dynamic applications that can be described,
published, located, or invoked over the network to create products, processes, and supply chains. These
applications can be local, distributed, or Web-based. Web services are built on top of open standards
such as TCP/IP, HTTP, Java, HTML, and XML.
Web services are XML-based information exchange systems that use the Internet for direct applicationto-application interaction. These systems can include programs, objects, messages, or documents.

7.1.3

XML

XML is just a standard to textually represent data and is used for all web services. If two systems are
sending dates values to each other, and one system is using the ISO 8601 standard and the other
system only understands RFC 5322, then the date values will be incorrect. This is like two people talking
to each other and one is speaking English and the other is speaking French. There will be some
misunderstandings.
Inductive Automation

Web Services

869

XML also supports organizing data into records as you can see in the XML sample below. There are
multiple material items each having name, category and allergent values.

HTML
<html>
<div>
Below is my smiley
image.
</div>
<img src=smiley.png/>
</html>

7.1.4

XML
<xml>
<material>
<name>Almond</name>
<category>Nuts</category>
<allergent>no</allergent>
</material>
<material>
<name>Walnut</name>
<category>Nuts</category>
<allergent>yes</allergent>
</material>
</xml>
Name

Category

Allergent

Almond

Nuts

no

Walnut

Nuts

yes

WSDL

WSDL stands for Web Service Description Language and as the name suggests, describes information
about the specific web service. This includes, the operations (functions or methods) that are available and
data types.
It is used by the Web Services Module to find out information about the web service provided by another
system. The only way to know what operations are available and what data types to use is to read the
WSDL file from the other system. Once we have the details, then the Web Services Module can show the
Inductive Automation

Web Services

870

appropriate setting options.

WSDL Contents

The data types can be simple or complex. Simple data types are the basic types like integer, string, float,
etc. Complex data types are just a collection of simple data types or a another complex data type.

7.1.5

SOAP

SOAP, originally defined as Simple Object Access Protocol, is a protocol specification for exchanging
structured information in the implementation of web services in computer networks. It relies on XML
Information Set for its message format, and usually relies on other application layer protocols, most
notably Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP), for message
negotiation and transmission

Inductive Automation

Web Services

7.2

871

Installation

To install the Web Services Module into an existing Ignition system, follow the instructions in the Existing
Ignition System. If you are installing Ignition at the same time, use the instructions in the New Ignition
System.

7.2.1

Existing Ignition System

7.2.1.1

Installing Modules

To install the Web Service Module onto an existing Ignition server, follow the steps below:
PLEASE NOTE:
It is also highly recommended that you do a backup of the Ignition system and database(s) before
upgrading or installing any new modules.
1. Download the Web Service-module.modl module
from the Inductive Automation download website. It will be under the MES modules heading. Note that the
file may be downloaded with a .zip extension, you must rename the file to the modl extension.
2. Install the Web Service-module.modl module
Navigate to the Modules page of the Ignition gateway. At the bottom of the list of already installed modules,
click the
link located at the bottom of the page. Next, browse to the Web
Service-module.modl file and click the install button.

Install Ignition Module

Inductive Automation

Web Services

7.2.2

New Ignition System

7.2.2.1

Selecting Install Options

872

To install the Web Service Module at the same time as Ignition, add the following steps to the normal
Ignition installation:
Select "Custom" on the Installation Mode setup step during the Ignition installation.

Scroll down to Web Service Module and select it. This will cause the module to be installed at the same
time as Ignition.

Inductive Automation

Web Services

7.3

873

Configuration

There are two areas that can be configured for the Web Service Module.
The first area is the Web Service configuration to define such things as the URL for the WSDL and
manage the provided operation(s).
The second is the Web Service Listener that may be applied against a Web Service configuration.

7.3.1

Web Service Configuration

Web Service configuration is where you define such things as the URL for the WSDL and manage the
operation provided by the service.

Web Services Configuration

7.3.1.1

WSDL Settings

This area configures the the URL for a web service.

Web Services WSDL Settings

URL
This is the full URL that is required to access the Web Service WSDL.
Examples:
http://www.w3schools.com/webservices/tempconvert.asmx?WSDL
http://www.webservicex.net/length.asmx?WSDL
Inductive Automation

Web Services

874

Timeout
This is the time the module will wait until a response is received from the URL. If no response is received
then an error is generated.
Refresh button
This will attempt to connect and process the WSDL file from the entered URL
7.3.1.2

Operation Settings

After a valid WSDL Setting has been configured this area allows you to select the available Operations
this service supports. The Web Services module internally processes the WSDL and presents the
possible selections.

Web Services Operation Settings

Port
This is the available address or connection point for the web service. It is normally a simple string. Select
an available port to allow the available Operations to be populated.
Operation
These are the available actions this web service and port supports. The operation is similar to a method
or function call in a traditional programming language.
Schema
This will allow you to view the schema used for the selected operation. It is a readable version of the
settings contained in the WSDL and allows you to cycle through the ports, operations and body contents
of the input and output for the operation.
7.3.1.3

Parameters

A web service operation will most likely require parameters to be set before the web service is called to
run. The parameter section allows you to see those parameters, thier data type and optionally set the
parameters to a constant value or bind them to a tag.
Some parameters have limited values that can be used and these may be supplied by the operation.
These values will appear as a drop down box.

Inductive Automation

Web Services

875

Web Services Param eter Settings

You may need to use these parameter names in scripting calls when running this web service.

7.3.2

Listener Configuration

Web Service Listeners allows you to define a interval that a configured web service will be run. Event
scripts are provided to process the parameters and results of the web service call.

Web Services Listener Configuration

You create a new listener by right clicking on the "Listeners" folder under the web services and select
"New Web Service Listener".
7.3.2.1

Listener Configuration Settings

This area defines the existing web service configuration to create the listener for.

Web Services Listener Configuration Settings

Inductive Automation

Web Services

876

Configuration
This is the name of the existing web service configuration that this listener will use.
Override Configuration Parameters
If left un-checked the parameter setting defined in the configuration for this web service will be used. By
checking this item you will need to set the parameters specifically for this listener. See the Parameters
section.
7.3.2.2

Listener Interval Settings

This area defines the interval setting used to automatically run this web service.

Web Services Listener Interval Settings

Activate Timed Interval at Startup

When selected, this setting will start the listener when Ignition starts. This is useful when you require a
web service to be running as soon as the Ignition gateway is re-started.
Timed Interval
This is the interval, in milliseconds, that the web service will run. For instance 30,000 equals 30 seconds.
Please note that fast rates may not be supportable by the network.
Delay Type
The two options are:
Fixed Delay: When this option is selected the web service will be run at the timed interval after a
successful run. If the timed interval is set to 10000 (10 seconds) and a call takes 20 seconds then the
next run will be 10 seconds after the last successful run.
Fixed Rate: When this option is selected the web service will be run at the timed interval regardless of
the amount of time a run takes. If a run takes longer than the timed interval then the calls will stack up.
7.3.2.3

Listener Event Scripts

This area allows you to configure scripts that run in response to running a web service.
Before Run
This script is triggered before a web service is run.
After Run
Inductive Automation

Web Services

877

This script is triggered after a web service has returned a result. It is most commonly used to process the
result values.
Service Error
This script is triggered if the web service returns an error.
Parse Error
This script will run if the operation generates an error parsing the XML of the parameters or result .
7.3.2.4

Listener Parameters

The parameter section allows you to set the parameters to a constant value or bind them to a tag. See
Parameters under Web Service Configuration section.
This section will be read-only unless the "Override Configuration Parameters" setting is selected.

Inductive Automation

Web Services

7.4

User Tutorial

7.4.1

Web Service Configuration

878

This tutorial will step you through creating a new web service configuration and then building a screen that
uses it to convert from miles to kilometers. This is a simple sample, but it takes you through the steps to
connecting to a web service on another system and invoking it with parameters and handling the results.
There are various methods of configuring and invoking web services and this just shows one possibility.
Before proceeding with this tutorial, make sure the Web Services Module is installed.

Step 1
To get started, open the designer and expand the Global item in the project browser. If the Web Services
module is installed, you will see the Web Services item in the project tree. Expand the Web Services item
to see the Configurations and Listeners items. The Configurations item is used to define new web
services that can be used by any project in Ignition.

Web Services Configuration

Step 2
Now we will add a web service configuration. Right click on the Configurations item to display the popup
menu. Next select the New Web Service Configuration menu item. A new web service configuration will
appear named New Web Service Configuration. Right click on it and select the Rename and rename it to
Measurement Conversion. Be sure to press enter after type in the new name.
Next, type in or copy and paste the following text into the URL and click the Refresh button.
URL: http://www.webservicex.net/length.asmx?WSDL
The Web Services Module will contact the server defined by the entered url and collect information about
the operations it provides and the associated data types.

Inductive Automation

Web Services

879

New Measurem ent Conversion Web Service

Step 3
Select the first port and the ChangeLengthUnit operation. The parameters for the selected operation will
appear to the right as shown in the image below.

MES Editor Add Existing Child Object

Step 4
The parameters to use when calling a web service operation can be constants entered here, bound to
tags, expressions or passed using scripting. For this tutorial, set the fromLengthUnit to Miles and the
Inductive Automation

Web Services

880

toLengthUnit to Kilometers. Leave the LengthValue blank as shown below. Whenever this configuration is
called, it will invoke the ChangeLengthUnit web service and ask to convert miles to kilometers.

MES Editor Add Person

You can view the details of the parameters by clicking on the Schema button.

Inductive Automation

Web Services

881

More importantly, the output or format of the results can be viewed by clicking on Output. This is
important because there can be multiple values in the results and to read them you typically refer to them
by name. We will see this in step 8 below.

Step 5
Next, right click on the Windows item in the project browser and select the Main Window menu item. This
will add a new window. Right click on the New Windows and select the Rename menu item to rename it
to Measurement Conversion.
Next, add a label and change the text to Miles:.
Add a Numeric Text Field next to it and rename it to Numeric Text Field Miles as shown below. This is
important because it will be references in a button script in a following step.

Inductive Automation

Web Services

882

Step 6
Add another label and change the text to Kilometers.
Add a Numeric Label next to it and rename it to Numeric Label Kilometers as shown below. This is
important because it will be references in a button script in a following step.

Inductive Automation

Web Services

883

Step 7
Add a button and change the text to Convert.

Step 8
Display the script editor by right clicking on the button and selecting the Scripting menu item. Select the
actionPerformed item under the action folder and select the Script Editor tab.
Next, enter or copy and paste the script as shown below.

Inductive Automation

Web Services

884

Just in case you want to save some time, copy and paste this script into the script editor:
miles = event.source.parent.getComponent('Numeric Text Field Miles').doubleValue
result = system.ws.runWebService('Measurement Conversion', {'LengthValue' : miles})
kilometers = result.getChild('ChangeLengthUnitResult')
event.source.parent.getComponent('Numeric Label Kilometers').text = str(kilometers.getValue())

The first line gets the miles value from the Numeric Text Field component.
The second line calls the web service configuration and passes the miles value parameter. The
fromLengthUnit and toLengthUnit parameters don't have to be passed here because they were defined in
step 4. However, they can be passed here and it will override the values in the Measurement Conversion
configuration.
Line 3 read the kilometers value from the results. Because multiple values might exist in the results, this
is done by name.
Line 4 converts the kilometer value to a string and puts it into the Numeric Label component.

Step 9
Enter in a miles value and click the Convert button. You will see the equivalent kilometers.
When the button is clicked, the client, or designer, sends a request to the Ignition gateway. The Ignition
gateway then build a web service request and sends it the the remote web service server. The response
is then handled at the Ignition gateway. After which the results are passed back to the client, or designer,
Inductive Automation

Web Services

885

where the value is diplayed.

There are various methods of configuring and invoking web services and this just shows one possibility.

7.4.2

Setup Listener

This tutorial will step you through creating a new web service listener based on the Measurement
Conversion web service created in the previous tutorial section.
Before proceeding with this tutorial, make sure the Web Services Module is installed and you have
completed the previous tutorial that creates the Measurement Conversion web service.

Step 1
Open the designer and expand the Global item in the project browser. You will see the Web Services item
in the project tree. Expand the Web Services item to see the Configurations and Listeners items. The
Listeners item is used to define new web service listeners that can be used to run a web service
configuration on a timed basis.
Create a new listener by right clicking on the Listeners folder and select New Web Listener. Rename the
listener to Measurement Conversion Listener.

Web Services Listener

Step 2
Select the newly created Measurement Conversion Listener and set the following settings:
Configuration Settings
Inductive Automation

Web Services

886

Configuration : Measurement Conversion

Override Configuration Parameters: Selected
Interval Settings
Activate Timed Interval as Startup: Un-Selected
Timed Interval: 15000
Delay Type: Fixed Delay

Step 3
The Event Scripts can be configured to process the results of the web service run. The After Run event is
where the web service result can be processed and the tag values can be set or other scripts may be
called. For this tutorial we will set a memory tag to the result value.
Use the After Run "event" property to get the "result" of the web service listener call. We know from the
schema definition of the output we will have a child object called 'ChangeLengthUnitResult'. We are
interested in the value of this property to set the tag.
Select the After Run event script and add this code:
system.tag.write('[default]WebServices/ChangeLengthUnitResult', event.result.getChild
('ChangeLengthUnitResult').value)

The above code depends on a memory tag that has been created in a folder called WebServices. Create
the tag folder WebServices and create a memory tag called ChangeLengthUnitResult and set the data
type to float4. In this case the tag name is the same name as the value name that will be returned from
the web service.

Step 4
In step 2 we selected to override the configuration parameters of the selected web service configuration
so we must set them in this listener. The LengthValue parameter will be set to read the length to convert
from a memory tag value. Create a memory tag in the WebServices folder called LengthValue and set the
data type to float4.
In the LengthValue parameter in the listener select the bind function and bind it to the newly created tag.

Inductive Automation

Web Services

887

Leave fromLengthUnit as Miles and toLengthUnit as Kilometers.

Step 5
The listener can be started and stopped via scripting. Create a main window and place a button on the
window title 'Enable Listener'. Place the following code in the actionPerformed script:
result = system.ws.activateListener("Measurement Conversion Listener")
if result == 1:
print "Activation successful"
else:
print "Could not Activate"

Place another button on the window title 'Disnable Listener'. Place the following code in the
actionPerformed script:
result = system.ws.deactivateListener("Measurement Conversion Listener")
if result == 1:
print "Deactivation successful"
else:
print "Could not Deactivate"

Drag the tag WebServices/LengthValue to the window and create a numeric text field control.
Drag the tag WebServices/ChangeLengthUnitResult to the window an create a numeric text label.

Step 6
Save the project and toggle preview mode. Select the Enable Listener button. By changing the length
value control value the change length unit result label will update after 15 seconds to display the converted
value.
Select the Disable Listener button to disable updates.
Inductive Automation

Web Services

7.5

Scripting

7.5.1

Client / Gateway Scripts

888

The Web Service Module exposes many script functions that support associated functions.
In the Ignition script editor, the documentation for the script functions can be accessed by pressing
control-space after typing in "system.". For all the Web Service script functions, type in "system.ws." and
press control-space to see the associated function and documentation.

Ignition Script Auto Docum ent Feature

7.5.1.1

runWebService

system.ws.runWebService(configurationName)

This will run a web service with the current parameter settings that are defined in the configuration.
parameters
configurationName

The name of the Web Service Configuration to run.

Data Type
String

returns
result

A Web Service Variable object that represents the result of the Web
Service.
Data Type
WSVariable

Inductive Automation

Web Services

889

system.ws.runWebService(configurationName, bodyObject)

This will run a web service with the current parameter settings that are defined in the configuration.
parameters
configurationName

The name of the Web Service Configuration to run.

Data Type
String

bodyObject

This will replace any parameters already defined by the

configuration with a python object that will be used as the
parameters of the web service. Using a python dictionary is
recommended.
Data Type
Object

returns
result

A Web Service Variable object that represents the result of the Web
Service.
Data Type
WSVariable

Example:
result = system.ws.runWebService('Measurement Conversion', {'LengthValue' : 26.2})

system.ws.runWebService(configurationName, headersObject, bodyObject)

This will run a web service with the current parameter settings that are defined in the configuration.
parameters
configurationName

The name of the Web Service Configuration to run.

Data Type
String

headersObject

This will replace and headers already defined by the configuration

with a python object that will be used as the headers of the web
service. Using a python dictionary is recommended.
Data Type
Object

bodyObject

This will replace any parameters already defined by the

configuration with a python object that will be used as the
parameters of the web service. Using a python dictionary is
recommended.
Data Type
Object

returns
result

Inductive Automation

A Web Service Variable object that represents the result of the Web
Service.
Data Type
WSVariable

Web Services
7.5.1.2

890

activateListener

system.ws.activateListener(listenerName)

This will activate the provided listener name.

parameters
listenerName

A valid listener name.

Data Type

String

returns
result
7.5.1.3

True if the listener was successfully activated, false otherwise.

Data Type
Boolean

deactivateListener

system.ws.deactivateListener(listenerName)

This will deactivate the provided listener name.

parameters
listenerName

A valid listener name.

Data Type

String

returns
result
7.5.1.4

True if the listener was successfully deactivated, false otherwise.

Data Type
Boolean

deactivateAllListeners

system.ws.deactivateAllListener()

This will deactivate the provided listener name.

parameters
None

returns
result

True if the listener was successfully deactivated, false otherwise.

Data Type
Boolean

Inductive Automation

Web Services
7.5.1.5

891

toDict

system.ws.toDict(wsVariable)

Converts a web service variable into a python dictionary.

parameters
wsVariable

The web service variable to be converted. Must be complex.

Data Type
WSVariable

returns
python dictionaryA python dictionary representing the given Web Service Variable.

Data Type
7.5.1.6

pyDictionary

toDataset

system.ws.toDataset(wsVariable, expanded)

Converts a web service variable into a dataset.

parameters
wsVariable

The web service variable to be converted. Must be complex.

Data Type
WSVariable

expanded

If set to 1 (true) then every child will be converted, if set to 0 then

only the top level child will be converted.
Data Type
Boolean

dataset

A dataset representing the given Web Service Variable.

Data Type
dataset

returns

7.5.2

Miscellaneous Object Reference

7.5.2.1

BeforeRunEvent

This event is triggered by a web service listener before a call to run the web service.
methods:
getName() - String
getOperation() - WSOperation
getScript() - String
7.5.2.2

AfterRunEvent

This event is triggered by a web service listener after a call to run the web service.
methods:
getName() - String
Inductive Automation

Web Services

892

getOperation() - WSOperation
getScript() - String
7.5.2.3

ServiceErrorEvent

This event is triggered by a web service listener if a call to run the web service results in a service error.
methods:
getName() - String
getOperation() - WSOperation
getScript() - String
7.5.2.4

ParseErrorEvent

This event is triggered by a web service listener if a call to run the web service generates a parsing error
on the operation data.
methods:
getName() - String
getOperation() - WSOperation
getScript() - String
7.5.2.5

WSVariable

The WSVariable object is returned from a web service call to hold the results of the call. This object
contains references to child WSVariables that are defined in the schema of the output of the web service
call.
properties:
getChildNames() - List of Strings
Returns all child names of the WSVariables contained in this WSVariable.
getChild(String childName) - String
Returns the WSVariable associated with this child name.
getValue() - Object
Returns an Object representing the value of the child.
example:
wsVariable = system.ws.runWebService('Temperature Convert')
resultData = wsVariable.getChild('FahrenheitToCelsiusResult')
print 'value=%s' %(resultData.getValue() )

getElement() - WSElement
Returns a WSElement Object representing the schema element of the child.
Inductive Automation

Web Services

893

methods:
toDataset() - Dataset
Returns a datset Object representing the child values of the WSVariable.
toExpandedDataset() - Dataset
Returns a datset Object representing the child values of the WSVariable and iterates through
any children of the child values.
toDict() - PyDictionary
Returns a PyDictionary Object representing the child values of the WSVariable.
7.5.2.6

WSOperation

The WSOperation object holds all the operation data associated with a web service port and is available
to the web service listener events via a call to event.getOperation(). It is available for more advanced
usage of a web service.
properties:
getWebFault() - String
hasWebFault() - Boolean
example:
# code snip from the After Run event of a web service listener
wsOperation = event.getOperation()
if wsOperation.hasWebFault():
log.error(wsOperation.getWebFault())

getBodyElement() - WSElement
getBodyVariable() - WSVariable
getFullName() - String
getHeadersElement() - WSElement
getHeadersVariable() - WSVariable
getInput() - String
getName() - String
getOutput() - String
getPort() - WSPort
Inductive Automation

Web Services

894

getResult() - WSVariable
getResultElement() - WSElement
getResultVariable() - WSVariable
7.5.2.7

WSElement

The WSElement object is used to hold the individual elements defined in the schema for a web service
that represent the header, body, input and output.
properties:
getChild(int index) - WSElement
Returns the WSElement at this index in the child WSElement list.
getChild(String childName) - WSElement
Returns the WSElement associated with this child name.
getChildNames() - List of Strings
Returns all child names of the WSElement contained in this WSElement.
getChildren() - List of WSElements
Returns a list of WSElements contained in this WSElement.
getFullName() - String
Returns a String representing the "." separated name of this WSElement and it's parent.
getMaxOccurrences() - int
Returns maximum occurrences this element can appear
getType() - WSType
Returns WSType of this element.
getTypeName() - String
Returns WSType of this element. Can be 'Complex', 'Simple' or 'Resticted'.
isOptional() - Boolean
Returns true if this element is optional.

Inductive Automation

Barcode Scanner
Part VIII

Barcode Scanner

Barcode Scanner

8.1

Introduction

896

The Barcode Scanner module extends Ignition to provide the ability to detect and decode barcode input.
The module provides both a controller to be used on the client and gateway scripting methods for server
barcode decoding. The module was design work with traditional one dimensional (1D) barcode formats,
plus the newer two dimensional (2D) and GS1 international standard of formats that can contain multiple
pieces of data.

UPC Barcode

Code 128

Data Matrix

The module comes pre-configured with 100+ barcode patterns to decode standard barcodes like UPC,
EAN, and GTIN, plus the full range of the GS1 application identification (AI) standard formats for trade
items, logistic units, assets, locations, service relationships, and special applications. The pre-configured
patterns will meet the needs of most operations using standard barcode formats and content. In addition,
the module can be fully customized to read proprietary or industry specific barcode content.
Commonly reading barcode input would follow the scenario of having an operator place the cursor on a
select input field, then scan the barcode to input the barcode's content into the selected field. If multiple
barcodes needed to be scanned or the content of the barcode contained multiple pieces of data, then it
often requires additional intervention by the operator to get the input recorded correctly.
With the Barcode Scanner component, the scenario above is greatly improved while reducing the risk of
input mistakes. Once the Barcode Scanner component is placed on an existing screen, it will listen for
barcode input via a keyboard wedge. This is done in the background and is independent of the focused
input component. Once it detects barcode input, it then decodes the barcode based on one of more
barcode patterns and raises a script event with the results. The script can then simply put the results into
the correct input field(s), update tag(s), write to database table(s), etc.

Inductive Automation

Barcode Scanner

Barcode Detection and Decoding

Inductive Automation

897

Barcode Scanner

8.2

898

Installation

To install the Track and Trace Module into an existing Ignition system, follow the instructions in the
Existing Ignition System. If you are installing Ignition at the same time, use the instructions in the New
Ignition System.

8.2.1

Existing Ignition System

8.2.1.1

Installing Modules

To install the Barcode Scanner Module onto an existing Ignition server, follow the steps below:
1. Download the BCScanner-module.modl module
from the Inductive Automation download website. It will be under the MES modules heading.
2. Install the BCScanner-module.modl module
Navigate to the Modules page of the Ignition gateway. At the bottom of the list of already installed modules,
click the
link located at the bottom of the page. Next, browse to the
BCScanner-module.modl file and click the install button as shown below.

Install Ignition Module

Inductive Automation

Barcode Scanner

8.2.2

New Ignition System

8.2.2.1

Selecting Install Options

899

To install the Barcode Scanner Module at the same time as Ignition, add the following steps to the normal
Ignition installation:
1. Select "Custom Configuration" on the setup step during the Ignition installation.
The following screen will appear. Scroll down to Barcode Scanner Module and select it. This will cause
the modules required for track and trace functionality to be installed at the same time as Ignition.

.
Ignition Installer

Inductive Automation

Barcode Scanner

8.3

900

Component Reference

This section is a reference for all the components that come with the Barcode Scanner Module.

8.3.1

Barcode Controller

Description
An invisible component that listens for barcode input received via a keyboard interface. The term invisible
component means that this component appears during design time, but is not visible during runtime.
The component listens to keystrokes based on a defined preamble and an optional post amble
specification, then decodes the raw barcode using regular expression patterns and passes the results to
a script event. The component is designed to work in the background and allow scripting to process the
results of the barcode content, such as auto fill fields or update information.
There are over 100 barcode patterns predefined to support the most common and GS1 international
standards. All the patterns are customizable and can be enabled as required. Multiple components can
be used on the same window to detect different types of barcodes.
Note: This component when enabled will listen for barcode input only on Stage or Published clients. It
doesn't activate in the designer's preview mode.

Inductive Automation

Barcode Scanner

Barcode Detection and Decoding

Properties
This component has standard Ignition properties with the addition of the following properties:

Inductive Automation

901

Barcode Scanner

902

Barcode Patte Defines the dataset of barcode patterns that will be used by the Decode
r
methods
to search for patterns in the raw barcode.
n
C
o
n
f
i
g
u
r
a
t
i
o
n

Scripting name
Data Type

barcodePatternConfiguration
Dataset

The Dataset must have the following columns that are reference by column name when
building node definitions:
Name
Key
Enabled

StrinA name given to describe the pattern.

g
Strin??
g
BooleWhen true the pattern is enabled and will be used
an
in the decoding methods.

Regex Pattern StrinThe regular expression pattern used to search the raw barcode.

g
If the pattern is to be used with the CONSUME
method of decoding then the carrot character ^ used
to specify the beginning of the string will be
automatically entered and doesn't need to be defined in the pattern.
Non-printable ASCII character can be put into the
pattern using escaped Unicode formatting (ie. Carriage
return could be input with \u000d without the quotes)
The pattern is broken in result groups by surrounding
sections of the pattern with parentheses ( ). These
result groups will be return in the results dataset as an
array of values.
There are various websites and programs that can be
used to develop and test Regex patterns. The pattern
needs to adhere to the Java version of regular expressions.
A special token <<separator>> can be used in the pattern to be
replaced by the Separator property.
Inductive Automation

Barcode Scanner

Preamble

903

Required. A character, string, or Regex Unicode value representing

the preamble pattern (ie. \u0002 for STX (Start of Text) or a GS1
Symbology Identifier ]E0, ]I1, ]C1, ]d2).
This defines the prefix of the incoming raw barcode and triggers the
listening method of the component to start recording input as a raw
barcode.
Scripting name
Data Type

Postamble

preamble
String

Optional. A character, string, or Regex Unicode value representing

the post amble pattern (ie. \u0003 for ETX (End of Text), \u000D
carriage return, \u000A line feed)
This defines the suffix of the incoming raw barcode and triggers the
end of the raw barcode character recording. If no postamble is
defined then the read timeout will trigger the end of the recording.
Scripting name
Data Type

Separator

postamble
String

Optional. A character, string, or Regex Unicode value representing

the barcode group separator pattern (ie. \\u001D or \\u00E8 for Group
Separator GS1 Standard FNC1 )
This property is used to replace the <<separator>> token that can be
embedded in the Barcode Pattern Configuration's Regex patterns.
Scripting name
Data Type

Read Timeout

The pause timeout between keystrokes to check for a barcode scan

(1000 = 1 second, range: 200-1000) ??? Is this mSec?
Scripting name
Data Type

Inductive Automation

separator
String

readtimeout
Integer

Barcode Scanner
Decode Method

904

Determines if the decoding of the barcode does a single-pass or

consume search method for matching patterns.
The single-pass method of decoding does a regex pattern search for
each pattern enabled in the Barcode Pattern Configuration. This
method is the quickest and is best used for barcode that contain a
single element of data such as UPC, EAN, or GTIN values.
The consume method of decoding does a regex pattern search for
each pattern enabled in the Barcode Pattern Configuration by
searching for the pattern at the beginning of the raw barcode string. It
then remove the found pattern from the raw barcode string to start the
search for the next pattern, thus consuming the barcode as it finds
pattern matches. This method is best for GS1 barcodes with multiple
elements of data.
The results of the found barcode data elements are placed in a hash
table that contains a entry for each found pattern with an array of
string values representing each of the pattern groups. The hash table
can be convert to a python dictionary collection for use in the scripting
events. See example scripts under the BarcodeResults object.
An error is logged if no pattern is found in the raw barcode or there is
leftover content in the raw barcode on the consume method of
decoding. The leftover portion of the content is placed in the results
hash table with a key of Unmatched.
Scripting name
Data Type

decodeMethod
Integer

Events
barcode - onBarcodeReceived

Event Properties

Is fired after the component decodes a raw barcode. It is passed a

BarcodeEvent object that contains the results of the decoding, any
error message, and the raw barcode.
See BarcodeEvent for more information about the functions and
properties that are available for the event object.

Example:
Sample #1 onBarcodeReceived event script:
#Sample Use of the Python Dictionary method to get barcode values from a single-pass #decode method
results = event.toDict()
# converts Java hashtable to Python dictionary
#Sample method to print out all result values
for key, value in results.items():
print(key, value)
#Look for an error message and display it to text box
if event.hasErrorMessage():
event.source.parent.getComponent('txtError').text = event.getErrorMessage()
system.util.beep()
Inductive Automation

Barcode Scanner

905

else:
#Update screen components from decode results
if 'GTIN-12' in results:
event.source.parent.getComponent('txtUPC').text = results['GTIN-12'][0]
if 'GTIN-13' in results:
event.source.parent.getComponent('txtUPC').text = results['GTIN-13'][0]
if 'GTIN-14' in results:
event.source.parent.getComponent('txtUPC').text = results['GTIN-14'][0]

Sample #2 onBarcodeReceived event script:

# get results using Java Hashtable
results = event.getResults()
if event.hasErrorMessage():
event.source.parent.getComponent('txtError').text = event.getErrorMessage()
system.util.beep()

if results.containsKey('GS1-01'):
event.source.parent.getComponent('txtGTIN').text = results.get('GS1-01').get(1)
if results.containsKey('GS1-10'):
event.source.parent.getComponent('txtBatchLot').text = results.get('GS1-10').get(1)
if results.containsKey('GS1-17'):
event.source.parent.getComponent('calUseBy').date = event.GS1ConvertToDate(results.get('GS1-17'
if results.containsKey('GS1-310'):
event.source.parent.getComponent('numNetWeight').floatValue = event.GS1ConvertToFloat(results.g
if results.containsKey('GS1-390'):
event.source.parent.getComponent('numAmount').doubleValue = event.GS1ConvertToDouble(results.ge
if event.hasUnmatched:
event.source.parent.getComponent('txtOutput').text = event.getUnmatched()

Inductive Automation

Barcode Scanner

8.4

906

Scripting

This section is a reference for scripting functions provided by the Track and Trace Module. It also has a
reference for any objects that are used by or returned by the scripting functions.

8.4.1

Client / Gateway Scripts

The functionality of the Barcode Controller component is also available for gateway and client scripting.
The following methods can be utilized in a gateway script to create regular expressions (regex) patterns
and decode a barcode by searching the raw barcode for the list of patterns. The results of the barcode
decoding can then be used by in the gateway script.
In the Ignition script editor, the documentation for the script functions can be accessed by pressing
control-space after typing in "system.". For all the track and trace script functions, type in "system.
barcode." and press control-space to see the associated function and documentation.

Ignition Script Auto Docum ent Feature

Barcode decoding uses Regex patterns to decode raw barcode data. The Barcode Scanner Module is
pre-configured with a set of 100+ patterns to include common and GS1 Application Identifier standards. If
the default patterns do not fit the required needs, then custom patterns can be defined. Below is the list of
predefined patterns:
NAME
Default
GTIN-14
GTIN-12 UPC
GTIN-13 EAN
GTIN-8 EAN
SSCC
GTIN
CONTENT

KEY
Default
GTIN-14
GTIN-12
GTIN-13
GTIN-8
GS1-00
GS1-01
GS1-02

REGEX PATTERN
"(.*)"
"^(\\d{14})$
"^(\\d{12})$
"^(\\d{13})$
"^(\\d{8})$
"(00)(\\d{18})"
"(01)(\\d{14})"
"(02)(\\d{14})"
Inductive Automation

Barcode Scanner
BATCH/LOT
PROD DATE
DUE DATE
PACK DATE
BEST BY
SELL BY
USE BY
VARIANT
SERIAL
ADDITIONAL ID
CUST.PART NO.
MTO VARIANT
PCN
SECONDARY SERIAL
REF. TO SOURCE
GDTI
GLN EXTENSIION COMP
GCN
VAR. COUNT
NET WEIGHT (kg)
LENGTH (m )
WIDTH (m )
HEIGHT (m )
AREA (m )
NET VOLUME (l)
NET VOLUME (m )
NET WEIGHT (lb)
LENGTH (i)
LENGTH (f)
LENGTH (y)
WIDTH (i)
WIDTH (f)
WIDTH (y)
HEIGHT (i)
HEIGHT (f)
HEIGHT (y)
GROSS WEIGHT (kg)
LENGTH (m ),log
WIDTH (m ),log
HEIGHT (m ),log
AREA (m ),log
VOLUME (l),log
VOLUME (m ),log
KG PER m
GROSS WEIGHT (lb)
LENGTH (i),log
LENGTH (f),log
LENGTH (y),log
WIDTH (i),log
WIDTH (f),log
WIDTH (y),log
HEIGHT (i),log
HEIGHT (f),log
HEIGHT (y),log
AREA (i)
AREA (f)
AREA (y)
AREA (i),log
AREA (f),log
AREA (y),log
NET WEIGHT (t)
NET VOLUME (oz)
NET VOLUME (q)
Inductive Automation

GS1-10
GS1-11
GS1-12
GS1-13
GS1-15
GS1-16
GS1-17
GS1-20
GS1-21
GS1-240
GS1-241
GS1-242
GS1-243
GS1-250
GS1-251
GS1-253
GS1-254
GS1-255
GS1-30
GS1-310
GS1-311
GS1-312
GS1-313
GS1-314
GS1-315
GS1-316
GS1-320
GS1-321
GS1-322
GS1-323
GS1-324
GS1-325
GS1-326
GS1-327
GS1-328
GS1-329
GS1-330
GS1-331
GS1-332
GS1-333
GS1-334
GS1-335
GS1-336
GS1-337
GS1-340
GS1-341
GS1-342
GS1-343
GS1-344
GS1-345
GS1-346
GS1-347
GS1-348
GS1-349
GS1-350
GS1-351
GS1-352
GS1-353
GS1-354
GS1-355
GS1-356
GS1-357
GS1-360

"(10)(\\d{1,20}" + separator + "|\\d{1,20}$)"

"(11)(\\d{6})"
"(12)(\\d{6})"
"(13)(\\d{6})"
"(15)(\\d{6})"
"(16)(\\d{6})"
"(17)(\\d{6})"
"(20)(\\d{2})"
"(21)(.{1,20}" + separator + "|.{1,20}$)"
"(240)(.{1,30}" + separator + "|.{1,30}$)"
"(241)(.{1,30}" + separator + "|.{1,30}$)"
"(242)(\\d{1,6}" + separator + "|\\d{1,6}$)"
"(243)(.{1,20}" + separator + "|.{1,20}$)"
"(250)(.{1,30}" + separator + "|.{1,30}$)"
"(251)(.{1,30}" + separator + "|.{1,30}$)"
"(253)(\\d{13}.{1,17}" + separator + "|\\d{13}.{1,17}$)"
"(254)(.{1,20}" + separator + "|.{1,20}$)"
"(255)(\\d{13}\\d{1,12}" + separator + "|\\d{13}\\d{1,12}$)"
"(30)(\\d{1,8}" + separator + "|\\d{1,8}$)"
"(310)([0-6]{1})(\\d{6})"
"(311)([0-6]{1})(\\d{6})"
"(312)([0-6]{1})(\\d{6})"
"(313)([0-6]{1})(\\d{6})"
"(314)([0-6]{1})(\\d{6})"
"(315)([0-6]{1})(\\d{6})"
"(316)([0-6]{1})(\\d{6})"
"(320)([0-6]{1})(\\d{6})"
"(321)([0-6]{1})(\\d{6})"
"(322)([0-6]{1})(\\d{6})"
"(323)([0-6]{1})(\\d{6})"
"(324)([0-6]{1})(\\d{6})"
"(325)([0-6]{1})(\\d{6})"
"(326)([0-6]{1})(\\d{6})"
"(327)([0-6]{1})(\\d{6})"
"(328)([0-6]{1})(\\d{6})"
"(329)([0-6]{1})(\\d{6})"
"(330)([0-6]{1})(\\d{6})"
"(331)([0-6]{1})(\\d{6})"
"(332)([0-6]{1})(\\d{6})"
"(333)([0-6]{1})(\\d{6})"
"(334)([0-6]{1})(\\d{6})"
"(335)([0-6]{1})(\\d{6})"
"(336)([0-6]{1})(\\d{6})"
"(337)([0-6]{1})(\\d{6})"
"(340)([0-6]{1})(\\d{6})"
"(341)([0-6]{1})(\\d{6})"
"(342)([0-6]{1})(\\d{6})"
"(343)([0-6]{1})(\\d{6})"
"(344)([0-6]{1})(\\d{6})"
"(345)([0-6]{1})(\\d{6})"
"(346)([0-6]{1})(\\d{6})"
"(347)([0-6]{1})(\\d{6})"
"(348)([0-6]{1})(\\d{6})"
"(349)([0-6]{1})(\\d{6})"
"(350)([0-6]{1})(\\d{6})"
"(351)([0-6]{1})(\\d{6})"
"(352)([0-6]{1})(\\d{6})"
"(353)([0-6]{1})(\\d{6})"
"(354)([0-6]{1})(\\d{6})"
"(355)([0-6]{1})(\\d{6})"
"(356)([0-6]{1})(\\d{6})"
"(357)([0-6]{1})(\\d{6})"
"(360)([0-6]{1})(\\d{6})"

907

Barcode Scanner
NET VOLUME (g)
GS1-361
VOLUME (q),log
GS1-362
VOLUME (g),log
GS1-363
VOLUME (i)
GS1-364
VOLUME (f)
GS1-365
VOLUME (y)
GS1-366
VOLUME (i),log
GS1-367
VOLUME (f),log
GS1-368
VOLUME (y),log
GS1-369
COUNT
GS1-37
AMOUNT
GS1-390
AMOUNT
GS1-391
PRICE
GS1-392
PRICE
GS1-393
ORDER NUMBER
GS1-400
GINC
GS1-401
GSIN
GS1-402
ROUTE
GS1-403
SHIP TO LOC
GS1-410
BILL TO
GS1-411
PURCHASE FROM
GS1-412
SHIP FOR LOC
GS1-413
LOC No
GS1-414
PAY TO
GS1-415
SHIP TO POST
GS1-420
SHIP TO POST
GS1-421
ORIGIN
GS1-422
COUNTRY - INIT PROCESS GS1-423
COUNTRY - PROCESS
GS1-424
COUNTRY - DISASSEMBLY GS1-425
COUNTRY - FULL PROCESS GS1-426
ORIGIN SUBDIVISION
GS1-427

908

"(361)([0-6]{1})(\\d{6})"
"(362)([0-6]{1})(\\d{6})"
"(363)([0-6]{1})(\\d{6})"
"(364)([0-6]{1})(\\d{6})"
"(365)([0-6]{1})(\\d{6})"
"(366)([0-6]{1})(\\d{6})"
"(367)([0-6]{1})(\\d{6})"
"(368)([0-6]{1})(\\d{6})"
"(369)([0-6]{1})(\\d{6})
"(37)(\\d{1,8}" + separator + "|\\d{1,8}$)"
"(390)([0-9]{1})(\\d{1,15}" + separator + "|\\d{1,15}$)"
"(391)([0-9]{1})(\\d{3})(\\d{1,18}" + separator + "|\\d{1,18}$)"
"(392)([0-9]{1})(\\d{1,15}" + separator + "|\\d{1,15}$)"
"(393)([0-9]{1})(\\d{3})(\\d{1,18}" + separator + "|\\d{1,18}$)"
"(400)(.{1,30}" + separator + "|.{1,30}$)"
"(401)(.{1,30}" + separator + "|.{1,30}$)"
"(402)(\\d{17}" + separator + "|\\d{17}$)"
"(403)(.{1,30}" + separator + "|.{1,30}$)"
"(410)(\\d{13})"
"(411)(\\d{13})"
"(412)(\\d{13})"
"(413)(\\d{13})"
"(414)(\\d{13})"
"(415)(\\d{13})"
"(420)(.{1,20}" + separator + "|.{1,20}$)"
"(421)(\\d{3})(.{1,20}" + separator + "|.{1,20}$)"
"(422)(\\d{3})"
"(423)(\\d{3})(\\d{3,12}" + separator + "|\\d{3,12}$)"
"(424)(\\d{3})"
"(425)(\\d{3})"
"(426)(\\d{3})"
"(427)(.{1,3}" + separator + "|.{1,3}$)"

Sample Gateway Tag Change Scripts

Example #1:
# Example #1 - Gateway Tag Change Script to decode a UPC, EAN, GTIN barcode
# Setup the logger to see activity on the Ignition Gateway console
# or just use print statements and look at wrapper.log file.
from org.apache.log4j import Logger
log = Logger.getLogger('GTINDecoder')
# Import java needed classes
from java.util import List
# Only execute if not initializing and tag value is not null
if (initialChange == 0 and newValue.value != None):
# Get rawBarcode from tag value
rawBarcode = newValue.value
# Get only the predefined regex patterns for GTIN-12 UPC, GTIN-13 EAN, & GTIN-14
patterns = system.barcode.scanner.getPatternList("GTIN-12,GTIN-13,GTIN-14", "")

# Call the decode method for a single pass search with a preamble of \u0002 ascii STX (start of
# and no postamble, or separator in barcode
results = system.barcode.scanner.decode(rawBarcode, "SinglePass", patterns, u"\u0002", "", "")
if (results.hasErrorMessage()):
# Log error message
log.info("Error from barcode scan: " + results.getErrorMessage())
else:
Inductive Automation

Barcode Scanner

909

# Get a Python dictionary of the decoding results

resultsDict = results.toDict()
# Loop through results
for key,value in resultsDict.items():
log.info("Key: " + key + ", Value: " + value.toString())

Example #2:
# Example #2 - Gateway Tag Change Script to decode a GS1 Active Matrix barcode
# Setup the logger to see activity on the Ignition Gateway console
# or just use print statements and look at wrapper.log file.
from org.apache.log4j import Logger
log = Logger.getLogger('GS1Decoder')
# Import java needed classes
from java.util import List
# Only execute if not initializing and tag value is not null
if (initialChange == 0 and newValue.value != None):
# Get rawBarcode from tag value
rawBarcode = newValue.value

# Get the predefined regex patterns for GS1 Application Identifer (AI) we are interested in, T
# separator for the variable length AIs is Unicode \u001d and will be inserted into the pattern
patterns = system.barcode.scanner.getPatternList("GS1-10,GS1-17,GS1-01,GS1-390,GS1-310", u"\u00
#Uncomment to see patterns in list
#for p in patterns:
#log.info("key=%s regex=%s" %(p.getKey(), p.getRegexPattern()))

# Call the decode method for a GS1 consume search with a preamble of ]d1,
# and postamble of \u001a (LF line feed), and separator of \u001d (GS Group Separator for FNC1)
results = system.barcode.scanner.decode(rawBarcode, "Consume", patterns, u"]d1", u"\u001a", u"\
if (results.hasErrorMessage()):
# Log error message
log.info("Error from barcode scan: " + results.getErrorMessage())
if (results.hasUnmatched()):
# Log unmatched
log.info("Unmatched: " + results.getUnmatched())
# Get a Python dictionary of the decoding results
resultsDict = results.toDict()
# Loop through results
for key,value in resultsDict.items():
log.info("Key: " + key + ", Value: " + value.toString())

Example #3:
# Example #3 - Gateway Tag Change Script to decode a custom regex pattern
# Setup the logger to see activity on the Ignition Gateway console
# or just use print statements and look at wrapper.log file.
from org.apache.log4j import Logger
log = Logger.getLogger('CustomDecoder')
# Import java needed classes
from java.util import List
Inductive Automation

Barcode Scanner

910

# Only execute if not initializing and tag value is not null

if (initialChange == 0 and newValue.value != None):
# Get rawBarcode from tag value
rawBarcode = newValue.value
# Create a new empty patterns list
patterns = []

# Create customer barcode pattern and add to list

pattern = system.barcode.scanner.getNewBarcodePattern("My Pattern Name", "MyPatternKey", u"^(\\
patterns.append(pattern)
# Call the decode method for a single pass search with no preamble, postamble, or separator in
results = system.barcode.scanner.decode(rawBarcode, "SinglePass", patterns, "", "", "")
if (results.hasErrorMessage()):
# Log error message
log.info("Error from barcode scan: " + results.getErrorMessage())
# Get a Python dictionary of the decoding results
resultDict = results.toDict()
# Loop through results
for key,value in resultDict.items():
log.info("Key: " + key + ", Value: " + value.toString())

8.4.1.1

getPatternList
system.barcode.scanner.getPatternList(fillKeys, separator)

Returns a subset list of the predefined barcode patterns that can be used to decode a barcode.
parameters
fillKeys

A list of keys to the predefined list of patterns to load into the

returned list. Use All to load all predefined patterns. Or for
example use GS1-10,GS1-17, GS1-310 to just get the 3 GS1 AI
patterns 10, 17, 310 respectively.
Data Type

String

separator
An optional separator to be used for patterns that can be of variable length
and need a separator code. For GS1 FNC1 a unicode character
of \u001D or \u00E8 can be used.

Data Type

String

returns

A list of the of barcode patterns.

Data Type

List<BarcodePattern>

Inductive Automation

Barcode Scanner

8.4.1.2

911

getNewBarcodePattern
system.barcode.scanner.getNewBarcodePattern(name, key, pattern)

Returns a BarcodePattern object to be used to append to a List<BarcodePattern>

parameters
name

Name for the pattern.

Data Type

String

key
Key for the pattern. This key is used to reference the results hash table
or Python dictionary object.

Data Type
pattern

String

Regular expression pattern.

Data Type

String

returns

A BarcodePattern object.
Data Type

8.4.1.3

BarcodePattern

decode
system.barcode.scanner.decode(rawBarcode, method, patterns, preamble, postamble,

separator)

Returns a DecodeResults object with the results of the decoding process.

parameters
rawBarcode

Raw barcode data to decode.

Data Type

String

method

Use SinglePass to do a single pass search of each pattern in

the patterns list, or use Consume to do a multi-pass search
where each pattern in the list is search for at the beginning of the
raw barcode string, then remove from the string until the raw
barcode is consumed. A Consume process can result in an
Inductive Automation

Barcode Scanner

912

unmatched portion of the raw barcode left and placed in the

DecodeResults.getUnmatched property. When decoding a GS1
standard barcode the Consume method should be used.
Data Type
patterns

A list of barcode patterns to be used to search the raw barcode.

Data Type

preamble

String

The suffix regex string to be removed from the raw barcode prior
to doing the pattern matching. A Unicode character of \u0003 for
ETX or \u000A for new line/line feed or \u000D for carriage return
can be used.
Data Type

separator

List<BarcodePattern>

The prefix regex string to be removed from the raw barcode prior
to doing the pattern matching. A Unicode character of \u0002 for
STX can be used.
Data Type

postamble

String

String

The GS1 FNC1 separator as a regex string used if decoding a

GS1 barcode. A Unicode character of \u001D or \u00E8 can be
used.
Data Type

String

returns

A DecodeResults object.
Data Type

8.4.2

DecodeResults

Miscellaneous Object Reference

In addition to the MES objects, there are support objects that are used for script functions or when using
functions on the MES objects. An example is the MESLotFilter object where several properties can be set
to narrow down the MES lots to return when using the system.mes.getLotList() script function.
If the MESLotFilter was not provided, then each option would have to be passed as a parameter in the
system.mes.getLotList() call. There are over a dozen options to filter lot on. This would make it vary
difficult to use because the line of script would look something like the following:
Cumbersome method that is NOT used:
system.mes.getLotList('', '000*', '', '', '', '', '', '', '', '', '', beginDate, endDate,'', '', '')

Inductive Automation

Barcode Scanner

913

Instead, using the MESLotFilter object the script look like:

filter = system.mes.lot.filter.createFilter()
filter.setLotNameFilter('000*')
filter.setBeginDateTime(beginDate)
filter.setEndDateTime(endDate)
list = system.mes.getLotList(filter)

The second example is the supported method and is much more readable.
8.4.2.1

Barcode Event

The BarcodeEvent object is an object that contains the decoded results of a barcode. It is passed in the
onBarcodeReceived event of the Barcode Controller component and the system.barcode.scanner.decode
script function.
properties:
hasErrorMessage()

Returns true if there is an error message passed with this event.

parameters
None
returns
Boolean

getErrorMessage()

Returns the error message from the decoding process.

parameters
None
returns
String

hasResults()

Returns true if there is decoded barcode results that matched the patterns given.
parameters
None
returns
Boolean

Inductive Automation

Barcode Scanner

914

getResults()

Returns a java hash table of the decoded results. The hash table has entries that have a key
and a value. The key is defined in the configuration patterns and the value is itself a list of
values returned from the Regex search.
For example, the pre configured GS1 pattern GTIN that has a key of GS1-01 and a Regex
pattern of (01)(\d{14}). When this pattern is found in the raw barcode, then an entry will be
put into the match results with a key of GS1-01 and the value will be a list of strings with 2
elements. The list of value strings is variable and is defined by the Regex pattern's grouping.
In this case the first [0] element is 01 and the second [1] element contains the 14 digit GTIN
number.
parameters
None
returns
Hashtable<String, List<String>>

toDict()

Returns the same results that getResults() but converted to python dictionary object with a
string key and the value as an array of strings.
parameters
None
returns
Python Dictionary

hasUnmatched()

Returns true if there is an unmatched portion of the raw barcode after the decode method was
called.
parameters
None
returns
Boolean

Inductive Automation

Barcode Scanner
getUnmatched()

Returns the string of unmatched raw barcode after the decode method was called.
parameters
None
returns
String

getRawBarcode()

Returns the raw barcode as a string.

parameters
None
returns
String

methods:
gs1ConvertToDate()

This is helper function to convert a GS1 formatted barcode date to a date object.
parameters

String value in the format of YYMMDD

value

Data Type
returns
Date

Inductive Automation

String

915

Barcode Scanner

916

gs1ConvertToFloat()

This is a helper function to convert a GS1numeric value to a float with the correct decimal
place.
parameters

String that represents the number to be converted to a float.

value

Data Type
decimalPlace

String

String that represents the place in the value parameter to place

the decimal place.
Data Type

String

returns
Float

gs1ConvertToDouble()

This is a helper function to convert a GS1numeric value to a float with the correct decimal
place.
parameters

String that represents the number to be converted to a double.

value

Data Type
decimalPlace

String

String that represents the place in the value parameter to place

the decimal place.
Data Type

String

returns
Double

Inductive Automation

Index

Index
-AAdding a Workday Routine Entry

328, 529

-DDeleting a Workday Routine Entry

328, 529

-EEditing a Workday Routine Entry

Inductive Automation

328, 529

917