Adding Custom Properties to Materials

Sepasoft MES Module Suite

Adding Custom Properties to Materials

Custom Properties

Custom properties can be added to any MES object using the MES Object Editor component or with 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 such as Width, Height and Depth custom properties can be added beneath a 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 them to operators or other end users. If the custom property is visible to the end users, the required option will make sure a value is entered before ending an operation.

Warning

Custom properties belong to AbstractMESObject which is the base object for every Track & Trace and OEE Downtime object. See the custom property section of the AbstractMESObject reference for a listing of the custom property functions.

Adding Custom Properties using the MES Object Editor

The MES Object Editor has built-in support to add custom properties to any of the MES object types that can be configured using the MES Object Editor. These objects include Equipment Objects, Material Class & Material Definition, Personnel Class & Personnel, Process Segment, Operations Definition, Operations Segment.

MES object types that custom properties cannot be added to using the MES Object Editor include Material Lot, Material Sublot, MES Work Order, Request Segment, Operations Response and Response Segment, because they are only created during production. However custom properties can be added to these objects using scripting.

Custom Property Inheritance Between MES Objects

Many MES objects have parent-child relationships which allows for custom properties to be inherited. As an example, Material Definitions, will inherit any custom properties defined for the parent Material Class that they belong to. Any custom properties added and configured locally on the Material Definition that have the same name as the inherited custom property, will replace it only on the instance of the child object. Furthermore, the properties are accessible separately through the MESObject's getInheritedProperties and getCustomProperties methods and are viewable from different locations within the MES Object Editor Component.

In the image on the right, the Material Class TestClass1 has a custom property called ClassLevelCP.

When the TestMat1 Material Definition is selected, the locally configured Custom Property TestCP1 is shown. Note that the inherited custom property ClassLevelCP from the parent Material Class does not appear in the Information Panel, nor will it be returned by the obj.getCustomProperties() method. The obj.getCustomProperties() method will return TestCP1 for the TestMat1 Material Definition.

When examining the settings for the Material Definition in the example, note that the locally configured Custom Property and the Inherited Custom Property from the Material Class parent are both shown in the main information panel. To retrieve the inherited value, the obj.getInheritedProperties() method should be used, returning ClassLevelCP. Note that the inherited value is not unique to the Material Definition but is a property of the Material Class. The inherited value can be over-ridden at the child level by adding a custom property on the child with the same name as the property of the parent.

Scripting Function for Manipulating Custom Properties

Read custom property from MES Object

Copy Code
Python
#Read custom property from MES object.
 
#Load the material class object named Vinegar.
mesObject = system.mes.loadMESObject("Vinegar", "MaterialClass")
 
#Print value of custom property pH
print mesObject.getPropertyValue('pH')

AbstractMESComplexProperty

AbstractMESComplexProperty Functions

The AbstractMESComplexProperty object functions:

Characters Not Allowed in Names

These characters are reserved by the Sepasoft modules.

Production Equipment

. ? ! # % ^ * ~ [ ] { } + = ` \ @ & ( ) < >,


MES Person

. ? ! # % ^ * ~ [ ] { } + = ` \/ " $ | < >


Other MES Objects

. ? ! # % ^ * ~ [ ] { } + = ` \/ " $ | ,


Machine Recipe Name in Settings & Changeover Module

Follows the same convention as Other MES Objects

Exception: Full-stop period . is allowed as of 3.81.10 SP2

Batch Names in Batch Procedure Module

. ? ! # % ^ * ~ [ ] { } + = ` \/ " $ | ,

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

Description

You can add properties to any MES object and resource complex properties, such as material, equipment, personnel, etc.

Use the methods below to add custom properties. Add a custom property directly to a MES object by not specifying a path to the parent property. To add a custom property as a child of an existing custom property or to a complex property, the parent path is used to specify the parent.

Each level of the path is separated with a period. This allows for names to be duplicated provided the path is unique. For example, it is possible for a MES object to have custom properties "Dimension 1.Width" and "Dimension 2.Width"

Syntax

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

  • Parameters

String name - The name of the custom property to add.

String dataTypeName - The name of the Ignition data type to make the new custom property.

String description - The description of the custom property.

String units - The units of the new custom property. This is just for reference.

Boolean productionVisible - The default is false. If True, show the custom property in various components. If False, it will be hidden and can be used to store values behind the scenes.

Boolean required - If True, a value must be assigned to the custom property before and segment is ended.

String value - The value to assign to the custom property after it has been added.

  • Returns

Nothing

  • Scope

All

Code Examples
Code Snippet
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#Load a MES object
obj = system.mes.loadMESObject('Box', 'MaterialDef')
  
#Add Type custom property directly to the MES object
obj.addCustomProperty('Type', 'String')
  
#Add Dimension custom property directly to the MES object
obj.addCustomProperty('Dimension', 'String', 'Dimension of box', '', True, False)
  
#Add Width custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Width', 'Int4', 'Width of box', 'in', True, False, '24')
  
#Add Height custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Height', 'Int4', 'Height of box', 'in', True, False, '12')
  
#Type custom property was never assigned a value so None is returned
print obj.getPropertyValue('Type')
  
#Remember to save the MES object
system.mes.saveMESObject(obj)
  
#Width and Height custom properties were assigned values
print obj.getPropertyValue('Dimension.Width')
print obj.getPropertyValue('Dimension.Height')
Output
None
24
12
 

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

Description

Custom properties can be added to MES objects or even complex properties (such as a material, equipment or personnel reference) of an MES object. The Complex Property Functions method can be used to add a custom property directly to a MES object by not specifying a path to the parent property. To add a custom property as a child of an existing custom property or to a complex property, the parent path is used to specify the parent.

Each level of the path is separated with a period. This allows for names to be duplicated provided the path is unique. For example, it is possible for a MES object to have custom properties "Dimension 1.Width" and "Dimension 2.Width"

Syntax

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

  • Parameters

String name - The name of the custom property to add.

String dataTypeName - The name of the Ignition data type to make the new custom property.

String description - The description of the custom property.

String units - The units of the new custom property. This is just for reference.

boolean productionVisible - The default is false. If True, show the custom property in various components. If False, it will be hidden and can be used to store values behind the scenes.

boolean required - If True, a value must be assigned to the custom property before and segment is ended.

  • Returns

Nothing

  • Scope

All

Code Examples
Code Snippet
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#Load a MES object
obj = system.mes.loadMESObject('Box', 'MaterialDef')
  
#Add Type custom property directly to the MES object
obj.addCustomProperty('Type', 'String')
  
#Add Dimension custom property directly to the MES object
obj.addCustomProperty('Dimension', 'String', 'Dimension of box', '', True, False)
  
#Add Width custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Width', 'Int4', 'Width of box', 'in', True, False, '24')
  
#Add Height custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Height', 'Int4', 'Height of box', 'in', True, False, '12')
  
#Type custom property was never assigned a value so None is returned
print obj.getPropertyValue('Type')
  
#Remember to save the MES object
system.mes.saveMESObject(obj)
  
#Width and Height custom properties were assigned values
print obj.getPropertyValue('Dimension.Width')
print obj.getPropertyValue('Dimension.Height')
Output
None
24
12
 

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

Description

Custom properties can be added to MES objects or even complex properties (such as a material, equipment or personnel reference) of an MES object. The Complex Property Functions method can be used to add a custom property directly to a MES object by not specifying a path to the parent property. To add a custom property as a child of an existing custom property or to a complex property, the property path is used to specify the property.

Each level of the path is separated with a period. This allows for names to be duplicated provided the path is unique. For example, it is possible for a MES object to have custom properties "Dimension 1.Width" and "Dimension 2.Width"

Syntax

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

  • Parameters

String propertyPath - The name or property path of the custom property.

String name - The name of the custom property to add.

String dataTypeName - The name of the Ignition data type to make the new custom property.

String description - The description of the custom property.

String units - The units of the new custom property. This is just for reference.

Boolean productionVisible - The default is false. If True, show the custom property in various components. If False, it will be hidden and can be used to store values behind the scenes.

Boolean required - If True, a value must be assigned to the custom property before and segment is ended.

  • Returns

Nothing

  • Scope

All

Code Examples
Code Snippet
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
#Load a MES object
obj = system.mes.loadMESObject('Box', 'MaterialDef')
  
#Add Type custom property directly to the MES object
obj.addCustomProperty('Type', 'String')
  
#Add Dimension custom property directly to the MES object
obj.addCustomProperty('Dimension', 'String', 'Dimension of box', '', True, False)
  
#Add custom property by specifying the property path
obj.addCustomProperty('Kind', 'Dimension', 'String', 'Dimension of box', '', True, False)
#Add Width custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Width', 'Int4', 'Width of box', 'in', True, False, '24')
  
#Add Height custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Height', 'Int4', 'Height of box', 'in', True, False, '12')
  
#Type custom property was never assigned a value so None is returned
print obj.getPropertyValue('Type')
  
#Remember to save the MES object
system.mes.saveMESObject(obj)
  
#Width and Height custom properties were assigned values
print obj.getPropertyValue('Dimension.Width')
print obj.getPropertyValue('Dimension.Height')
Output
None
24
12
 

addCustomProperty(name, dataTypeName)

Description

Custom properties can be added to MES objects or even complex properties (such as a material, equipment or personnel reference) of an MES object. The Complex Property Functions method can be used to add a custom property directly to a MES object by not specifying a path to the parent property. To add a custom property as a child of an existing custom property or to a complex property, the property path is used to specify the property.

Each level of the path is separated with a period. This allows for names to be duplicated provided the path is unique. For example, it is possible for a MES object to have custom properties "Dimension 1.Width" and "Dimension 2.Width"

Syntax

addCustomProperty(name, dataTypeName)

  • Parameters

String name - The name of the custom property to add.

String dataTypeName - The name of the Ignition data type to make the new custom property.

  • Returns

Nothing

  • Scope

All

Code Examples
Code Snippet
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#Load a MES object
obj = system.mes.loadMESObject('Box', 'MaterialDef')
  
#Add Type custom property directly to the MES object
obj.addCustomProperty('Type', 'String')
  
#Add Dimension custom property directly to the MES object
obj.addCustomProperty('Dimension', 'String', 'Dimension of box', '', True, False)
  
#Add Width custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Width', 'Int4', 'Width of box', 'in', True, False, '24')
  
#Add Height custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Height', 'Int4', 'Height of box', 'in', True, False, '12')
  
#Type custom property was never assigned a value so None is returned
print obj.getPropertyValue('Type')
  
#Remember to save the MES object
system.mes.saveMESObject(obj)
  
#Width and Height custom properties were assigned values
print obj.getPropertyValue('Dimension.Width')
print obj.getPropertyValue('Dimension.Height')
Output
None
24
12
 

addCustomProperty(propertyPath, name, dataTypeName)

Description

Custom properties can be added to MES objects or even complex properties (such as a material, equipment or personnel reference) of an MES object. The Complex Property Functions method can be used to add a custom property directly to a MES object by not specifying a path to the parent property. To add a custom property as a child of an existing custom property or to a complex property, the property path is used to specify the property.

Each level of the path is separated with a period. This allows for names to be duplicated provided the path is unique. For example, it is possible for a MES object to have custom properties "Dimension 1.Width" and "Dimension 2.Width"

Syntax

addCustomProperty(propertyPath, name, dataTypeName)

  • Parameters

String propertyPath - The name or property path of the custom property.

String name - The name of the custom property to add.

String dataTypeName - The name of the Ignition data type to make the new custom property.

  • Returns

Nothing

  • Scope

All

Code Examples
Code Snippet
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
#Load a MES object
obj = system.mes.loadMESObject('Box', 'MaterialDef')
  
#Add Type custom property directly to the MES object
obj.addCustomProperty('Type', 'String')
  
#Add custom property with property path parameter
obj.addCustomProperty('Kind', 'Type', 'String')
#Add Dimension custom property directly to the MES object
obj.addCustomProperty('Dimension', 'String', 'Dimension of box', '', True, False)
  
#Add Width custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Width', 'Int4', 'Width of box', 'in', True, False, '24')
  
#Add Height custom property to the previous Dimension custom property and assign a value
obj.addCustomProperty('Dimension', 'Height', 'Int4', 'Height of box', 'in', True, False, '12')
  
#Type custom property was never assigned a value so None is returned
print obj.getPropertyValue('Type')
  
#Remember to save the MES object
system.mes.saveMESObject(obj)
  
#Width and Height custom properties were assigned values
print obj.getPropertyValue('Dimension.Width')
print obj.getPropertyValue('Dimension.Height')
Output
None
24
12
 

getAllCustomProperties()

Description

Returns all the custom properties.

Syntax

getAllCustomProperties()

  • Parameters

None

  • Returns

List<MESCustomProperty> - The list of custom properties.

  • Scope

All

Code Examples
Code Snippet
1
2
matDef = system.mes.loadMESObject('Cane Sugar', 'MaterialDef')
matDef.getAllCustomProperties()
 

getBaseName()

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.

Description

Get the base name for the complex property.

Syntax

getBaseName()

  • Parameters

None

  • Returns

  String baseName - The base name for the complex property.

  • Scope

All

Code Examples
Code Snippet
1
2
3
4
5
#This code snippet prints the base name for the specific property.
seg = system.mes.createMESObject('ProcessSegment')
#Create a new material reference complex property
materialProp = seg.createComplexProperty('Material', 'Vinegar')
print materialProp.getBaseName()
Output
Vinegar
 

getName()

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.

Description

Get the name for the complex property.

Syntax

getName()

  • Parameters

None

  • Returns

 String - The name for the complex property.

  • Scope

All

Code Examples
Code Snippet
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
seg = system.mes.createSegment('Receive Steel', '\\Enterprise\Site\Area\Unload Station 1', True)
seg.setMaterial('Steel In', '84000', '\\Enterprise\Site\Receiving\Steel\QC Holding', 'Lot 84000-1', 100.0)
cnt = seg.getComplexPropertyCount('ResponseMaterial')
for ndx in range(0, cnt):
 prop = seg.getComplexProperty('ResponseMaterial', ndx)
 print prop.getName()
seg.begin()
seg = system.mes.getActiveSegment('Enterprise\Site\Area\Unload Station 1', 'Receive Steel')
seg.setMaterial('Steel In', '84001', '\\Enterprise\Site\Receiving\Steel\QC Holding', 'Lot 84001-1', 100.0)
seg.update()
seg = system.mes.getActiveSegment('Enterprise\Site\Area\Unload Station 1', 'Receive Steel')
cnt = seg.getComplexPropertyCount('ResponseMaterial')
for ndx in range(0, cnt):
 prop = seg.getComplexProperty('ResponseMaterial', ndx)
 print prop.getName()
Output
Steel In-1
Steel In-2
 
Description

Get the parent property for this complex property.

Syntax

getParentProperty(propertyName)

  • Parameters

String propertyName - The name of complex property to return the parent property for.

  • Returns

AbstractMESProperty - The parent property of the specified complex property.

  • Scope

All

Code Examples
Code Snippet
1
2
matDef = system.mes.loadMESObject('Cane Sugar', 'MaterialDef')
matDef.getParentProperty('Width')

 getValue(valueName)

Description

Returns the value for the specific property.

Syntax

 getValue(valueName)

  • Parameters

String valueName - The name of the value to return.

  • Returns

String - The value as an object, or returns null if the property is not found (does not throw an error).

  • Scope

All

Code Examples
Code Snippet
1
2
3
4
5
#This code snippet prints the value for the specific property.
seg = system.mes.createMESObject('ProcessSegment')
#Create a new material reference complex property
materialProp = seg.createComplexProperty('Material', 'Vinegar')
print materialProp.getValue('MaterialProductionSelectable')
Output
True

 logRenameChangeEvent(String oldName, String changeNote)

Description

The 'changeNote' allows you to attach any arbitrary message to the change so that it appears in the Change Log table.

Syntax

logRenameChangeEvent(String oldName, String changeNote)

  • Parameters

String oldName

String changeNote

  • Scope

All

 

setName(String name, String changeNote)

Description

Attaches any arbitrary message to the change so that it appears in the Change Log table.

Syntax

setName(String name, String changeNote)

  • Parameters

String String name - The 'changeNote' allows you to attach any arbitrary message to the change so that it appears in the Change Log table.

  • Returns

nothing

  • Scope

All

 

setValue(valueName, value)

Description

Set the value for the specified value name.

Syntax

 setValue(valueName, value)

  • Parameters

String valueName - The name of the value to set.

String value - The new value.

  • Returns

boolean - True if the property has been set successfully and False otherwise (does not thrown an error if property does not exist or is of a different type).

  • Scope

All

Code Examples
Code Snippet
1
2
3
4
5
6
7
8
9
10
11
#Example
seg = system.mes.createMESObject('ProcessSegment')
#Create a new material reference complex property
materialProp = seg.createComplexProperty('Material', 'Vinegar')
materialProp.setValue('MaterialRatePeriod', 'Sec')
materialProp.setValue('MaterialRate', '74')
#Just to make sure the value is reset.
print materialProp.getValue('MaterialRatePeriod')
   
##Save the segment to manifest the changes.
system.mes.saveMESObject(seg)
Output
Sec
Read Custom Prop
Copy Code
Python
[Python]

#Read custom property from MES object.
 
#Load the material class object named Vinegar.
mesObject = system.mes.loadMESObject("Vinegar", "MaterialClass")
 
#Print value of custom property pH
print mesObject.getPropertyValue('pH')

Add New Prop
Copy Code
Python
#Add new custom property to MES object.
 
#Load the material class object named Mounting Plate.
mesObject = system.mes.loadMESObject('Mounting Plate', 'MaterialDef')
 
#Add a new custom property named Width.
mesObject.addCustomProperty('Width', 'Float8', 'Width of mounting plate', 'mm', True, True)
Add New and Set Value
Copy Code
Python
#Add new custom property to MES object.
 
#Load the material class object named Vinegar.
mesObject = system.mes.loadMESObject('Vinegar', 'MaterialClass')
 
#Add a new custom property named pH.
mesObject.addCustomProperty('pH', 'Float8')
 
#Set the value of pH to 5.1
mesObject.setPropertyValue('pH', 5.1)

Add Multiple Properties
Copy Code
Python
The following code snippets show how multiple custom properties can be added, updated, deleted and queried against any MES Object type. 
Note that as of this time (2.9.2 SP5), using 'DateTime' as a datatype parameter does not seem to work. If you are storing a date, store it as a string and then convert it back to a datetime object when you need it.

def deleteCustomProperties(mesObject):
    #This function will delete all custom properties of the passed object and return the updated object instance
    cpList = mesObject.getCustomPropertiesFull()
    for key in cpList:
        mesObject.removeCustomProperty(key) 
        
    system.mes.saveMESObject(mesObject)
    return system.mes.loadMESObject(mesObject.getUUID())
    
############################################################
def updateCustomProperties(mesObject, cpList):
    #This function will update the passed object with the list of custom properties 
    #and return the updated object instance. If the custom properties do not exist, they will be created
    
    mesObject.setCustomPropertyValues(cpList)
    system.mes.saveMESObject(mesObject)
    return system.mes.loadMESObject(mesObject.getUUID())    


############################################################
def getCustomProperties(mesObject):
    #This function returns all custom properties of the passed object
    cpList = mesObject.getAllCustomProperties()
    for item in cpList:
        print 'Custom Property Settings for ', item.getName()
        print 'Value - ', item.getValue()
        print 'Units - ', item.getUnits()
        print 'DataType - ', item.getIgnitionDataType()
        print 'Description - ', item.getDescription()
        print
    
############################################################


name = 'WO-0001'
objType = 'WorkOrder'

#Here we will define the custom property settings to be added to the MES Object
#Note datatypes 'DateTime' and 'Text' do not work
cpName = 'Start Date'
cpDataType = 'String'
cpVal= system.date.now()
cpDesc = 'Start Date for this WO'
cpUnits = 'No Units'
cpList = {cpName : [cpDataType , cpVal, cpDesc , cpUnits]}

#This is an example of how to pass multiple custom property settings
#cpList = {'Amps' : [current_dataType , current, current_desc , current_units], 'Volts': [volts_dataType , volts, volts_desc, volts_units]}

mesObject = system.mes.loadMESObject(name, objType)
mesObject = deleteCustomProperties(mesObject)   #We only need to delete the custom property if we are trying to change the units, seems to be a bug
mesObject = updateCustomProperties(mesObject, cpList)

getCustomProperties(mesObject)

Sepasoft MES Module Suite