Entity Types#

Administration.EntityTypes

The Entity Types page provides access to the meta-data of all system objects.

To open a specific entity type just click on the name and the Entity Type details will be displayed.

Main View#

Depending on the optional modules that are licensed in the system, the main view will display some or all of the following page sections:

• Details - displays general information on the Entity Type.
• State Models - displays information on the State Models that are associated to the Entity Type.
• Properties - displays information on the native properties that belong to the Entity Type.
• Attributes - displays information on the attributes that belong to the Entity Type.
• Operations - displays information on the properties that belong to the Entity Type.
• Operation Attributes - displays information on the operations that belong to the Entity Type.

Each entity has four different types of properties:

• Native - the property is stored together with the main record and it is accessed as a property.
• Custom Property - the property is stored with the main record, but it is accessed as an attribute.
• Attribute - the property is stored in a separate attribute table.
• Operation Attribute - the property is stored in a separate attribute table, but it is only updated by an operation.

The following important rules apply:

1. Native Properties can only be added before the object schema is generated.

2. Custom Properties can be added after the object is generated, either by:

   • Creating the Custom Property directly in the properties tab of the object.
   • Migrating an existing Attribute to a Custom Property.

3. Attributes and Operation Attributes can be added at any time.

Create an Entity Type#

EntityType.Create

To create a new Entity Type, select New and then follow the wizard as described below.

Step 1 - General data#

1. Provide a name for the Entity Type.
2. Optionally, provide a description of the Entity Type.
3. Select whether the object is a Relation object. If yes, specify the Source Entity and the Target Entity.

4. Specify the Lock Type, which determines how entities are logically locked during updates. The available options include:

   • Lock None – No locking is applied (default).
   • Lock Source – Only the source entity is locked.
   • Lock Target – Only the target entity is locked.
   • Lock Source And Target – Both the source and target entities are locked.

5. If the entity is a Relation and marked as Cloneable (see the checkbox further down in the screen), it is possible to define the clone behavior:

   • Copy If Source - clones the relation when cloning the source of the relation.
   • Copy If Source Or Target - clones the relation when cloning both the source and target entities.
   • Copy If Target - clones the relation when cloning the target of the relation.
   • No Copy - relation is not cloned (default).

6. Specify - only for versioned objects - whether automatic Change Sets are allowed (by setting the Allow Automatic Change Set to true). In this case, for the change set to be created automatically, the entity that will be the target of change control must have the following configuration:

   • Change Set Name Generator
     • Name generator to be used as the Change Set name once it is automatically created. The name generator needs to be created in advance, through the Administration menu, Name Generator tile.

   • Approval

     • Select whether the items of the Change Set will be made effective upon approval.
     • It is possible to define a specific role or workflow that is responsible for the Change Set approval. According to the selection (Role/Workflow), the field under it displays a dropdown list with the possible Roles/Workflows of approval.

     • Workflow is used when a sequence of roles is required to perform the approval. This approval sequence must be defined in advance by creating a State Model.

       Note

       The Entity Type defined in the state model must be Change Set.

     • If the dropdown list for either Role or Workflow is left empty and the Use Change Set Approval Context field is set to false, there will be no approval role/workflow associated with the Change Set (here the system will behave in the same way as when the Change Set is manually created and the Requires Approval field is set to false).

     • Select whether the requester and approvers should receive email notifications for new versions.

   • Use Change Set Approval Context

     • If true and if no role and workflow were specified above (in the dropdown list), the ChangeSetApprovalContext Smart Table will be resolved and, according to the context, a role/workflow of approval will be associated with the Change Set.

   • Enable Automatic Approval

     • If true, if no role and workflow are specified, and if the Use Change Set Approval Context field is set to false, the change set will be automatically approved, without the need to select the Request Approval button.

     

   • For non-versioned entities, specify whether the GUI should request a Change Set when cloning. This is to handle the case where a non-versioned object is referenced in Smart Tables that are subject to change control.

   • Specify if instances of this object can be deleted.
   • Specify whether to enable default dates for revision creation and validation.

   • Determine whether new versions of this entity can be created.

     

7. Specify the additional properties of the new entity type:

   • Whether the entity requires unique names.

   • Whether the entity data is replicated to the Operational Data Store (ODS).

     Info

     If updating this information, changes only become effective after the Generate Schema procedure is run.

   • Whether history is recorded for the entity.

     Info

     If updating this information, changes only become effective after the Generate Schema procedure is run.

   • Whether the entity is partitioned.

   • Whether the entity is visible in the Business Data page group.
   • Whether the entity is enabled for Connect IoT.
   • Whether the entity has attributes.
   • Whether the entity contains operation attributes.
   • Whether the entity state models are managed by the system or not.
   • Whether the entity allows multiple state models (all entity types support one main state model).

   Support for Multiple State Models will be removed in a future version.

   • Whether the entity allows Barcode IDs to be used for identification.

   • Whether the entity is importable via the Import Objects API.

     Info

     It is not possible to mark a custom entity as a system entity or whether the entity is licensed.

8. Enter the History Retention Time for the entity (in days). Instances of the entity type are purged from the online database after they are terminated for more than the specified Retention Time.

9. Define the History Default Interval (in days), to be used when showing the entity history in the GUI - if not specified, the system will use 180 days.

   Info

   The History Retention Time is related with the purging mechanism of the online database. After termination, the time configured is the time the information will remain in the online database until being purged (after this, you only be able to see the data using Analytic reports). The History Default Interval sets the initial time frame for viewing an entity's historical data, accessible by selecting History from the Views dropdown menu at the top right corner of the entity page.

10. In case that the Entity Type requires a specific purge, it is necessary to select the Specific purge type and to provide the purge procedure. Selecting Bypass means that no purge is performed. By default the Generic purge is selected.

11. Define whether the Entity can be cloned.
12. Select the localized message key that will be used in the localization process. See Localized Messages for more information.
13. For Entity Types which are relations, you can set the Access Levels that define whether the relation is visible on both the create or update of either the source or the target.
14. Select Create to complete the operation and the new Entity Type will be created.

Manage Entity Type Properties#

EntityType.Edit

After creating the Entity Type, the user can manage the list of properties that are a part of the Entity Type definition. Navigating to the Properties section in the main page and selecting the Manage button will display a wizard that allows the user to add new properties to the Entity Type.

1. On the left side panel, add as many properties as desired (select in the top right of the grid to add, and to remove), specifying for each property:

   • the name
   • the description (optional)
   • the property type - Native (the property is stored together with the main record)
   • the reference type - Entity, Entity Definition, Entity Type, Entity Version, Enum, File, Lookup Table, Lookup Value, None, Query, Role, User; and in case that the reference type is different from None, also the specific reference of the property
   • the scalar type (data type); size (only for some data types, such as Varchar and NVarchar) and precision (only for some data types, such as Decimal)
   • the default value - if any, which must be compatible with the selected data type
   • whether it is an array (valid only for attributes)
   • a set of flags:
     • whether it is enabled
     • whether it is indexed
     • whether it is reportable, that is, it is used in the Data Warehouse
     • whether the property is editable on clone
     • whether it is mandatory
     • whether history is enabled (for attributes only, since properties inherit the history behavior set for the entity)
     • whether it should be used when searching for entities with specific property values. This setting is only visible if the property matches specific characteristics. See below in Searchable Properties and Find Entity Control for more information.
       • if the property is defined as searchable, define the search type to be performed on the property:
         • Contains: property will be matched if the search term is found anywhere on the property value.
         • Starts With (default): property will be matched if the search term is found on the beginning of its value.
     • for versioned entities only: whether the property belongs to the global or versioned portion of the object

   • optionally, a validation range - a string like [start:end] to designate ranges between start and end. An open bracket (] or [) excludes the corresponding limit value. For example, ]1:10] excludes the number 1 and includes the number 10.

     Warning

     Decimal range validations must use the current cultured defined decimal separator.

   • optionally, a validation regular expression used for validation. For more information on regular expressions please follow this link ⧉

   • optionally, the key for a localized message which must exist and be of message type EntityType
   • a set of access levels which apply to the entity and the template:
     • whether it is read only at create or update
     • whether it is hidden at create or update

Searchable Properties#

To allow better and and more granular search capabilities for specific entities, you can define entity type properties as searchable, as described in the Manage Entity Type Properties section. Those properties will be displayed in any fields that allow searching for entities through their defined properties.

There are specific requirements for the type of properties you may add as searchable. You can add any property (native or custom) provided they match the following characteristics:

• Reference Type: None
• Scalar Type: Varchar or NVarchar
• Size: [1-512]

An error will be displayed in the wizard if you try to add more than the allowed searchable properties:

Furthermore, when using Contains as the search type, a warning will also be displayed to alert for the potential performance issues.

You can see the current list of searchable properties from the Properties section in the Entity Type by selecting the Searchable flag:

Manage Entity Type Attributes#

EntityType.Edit

This is similar to the process of adding new properties, with the exception of the Editable on Clone checkbox. This screen is only available if the Entity Type was specified to have attributes in the first screen. After creating the Entity Type, you can manage the list of attributes that are a part of the Entity Type definition. Navigating to the Attributes section in the main page and selecting the Manage button will display a wizard that allows you to add new attributes to the Entity Type.

1. On the left side panel, add as many attributes as desired (select in the top right of the grid to add, and to remove), specifying for each attribute:

   • the name
   • the description (optional)
   • the property type:
     • Attribute - the attribute is stored in a separate attribute record
   • a Data Group (optional) - if defined, only members of this Data Group are able to update this attribute
   • the reference type - None; LookupValue; LookupTable or Enum and in case that the reference type is LookupValue or Enum, also the specific reference of the property in the Reference To field
   • the scalar type (data type); size (only for some data types, such as Varchar and NVarchar) and precision (only for some data types, such as Decimal)
   • whether the attribute must be copied on clone or not
   • the default value - if any, which must be compatible with the selected data type
   • whether it is an array (valid only for attributes)
   • a set of flags:
     • whether it is enabled
     • whether it is indexed
     • whether it is reportable, that is, it is used in the Data Warehouse
     • whether history is enabled (for attributes only, since properties inherit the history behavior set for the entity)
     • for versioned entities only: whether the property belongs to the global or versioned portion of the object

   • optionally, a validation range - a string like [start:end] to designate ranges between start and end. An open bracket (] or [) excludes the corresponding limit value. For example, ]1:10] excludes the number 1 and includes the number 10.

     Warning

     Decimal range validations must use the current cultured defined decimal separator.

   • optionally, a validation regular expression used for validation. For more information on regular expressions please follow this link ⧉

   • optionally, the key for a localized message which must exist and be of message type EntityType
   • a set of access levels which apply to the entity and the template:
     • whether it is read only at create or update
     • whether it is hidden at create or update

Manage Entity Type Operations#

EntityType.Edit

This step is used to define the Entity Type operations (methods).

1. On the left side panel, add as many operations as desired (select in the top right of the grid to add, and to remove), specifying for each operation:
   • the name
   • the description
   • whether history for the operation is enabled
   • whether an event is published when the operation is completed
   • whether fabLive will subscribe to this event for automatic updates

Manage Entity Type Operation Attributes#

EntityType.Edit

This is similar to the process of adding new attributes. This screen is only available if the Entity Type was specified to have operation attributes in the first screen. After creating the Entity Type, the user can manage the list of operation attributes that are a part of the Entity Type definition. Navigating to the Operation Attributes section in the main page and selecting the Manage button will display a wizard that allows the user to add new operation attributes to the Entity Type.

1. On the left side panel, add as many operation attributes as desired (select in the top right of the grid to add, and to remove), specifying for each operation attribute:

   • the name
   • the description
   • the property type:
     • Attribute - the property is stored in a separate attribute table
   • the reference type - None; LookupValue; LookupTable or Enum and in case that the reference type is LookupValue or Enum, also the specific reference of the property in the Reference To field
   • the scalar type (data type); size (only for some data types, such as Varchar and NVarchar) and precision (only for some data types, such as Decimal)
   • the default value - if any
   • whether it is an array
   • a set of flags:
     • whether it is enabled
     • whether it is indexed
     • whether it is reportable, that is, it is used in the Data Warehouse
     • whether history is enabled
   • the validation range - a string like [start:end] to designate ranges between start and end. An open bracket (] or [) excludes the corresponding limit value. For example, ]1:10] excludes the number 1 and includes the number 10.
   • the validation expression - a validation is a string that describes a regular expression. For more information on regular expressions please follow this link ⧉
   • optionally, the key for a localized message which must exist and be of message type EntityType
   • a set of access levels which apply to the entity and the template:
     • whether it is read only at create or update
     • whether it is hidden at create or update

Manage Entity Type ODS Retention Time#

EntityType.Edit

This procedure allows you to define the ODS data retention period for each Entity Type, both in the State and History tables stored in the ClickHouse database. After creating the Entity Type, you can manage the ODS retention time that are a part of the Entity Type definition. Navigating to the ODS Retention section in the main page and selecting the Manage button will open the Manage Entity Type ODS Retention Time wizard.

1. Select the Manage button to open the Manage Entity Type ODS Retention Time wizard.
2. In the wizard, select either the State or History tab. Both tabs provide the same configuration options.

3. In the left side panel, you can add or remove ODS Data Retention instances as needed (select the icon to add, and the icon to remove). For each retention instance, define the following parameters:

   • Older Than - specifies how long the ODS data should be retained. You can choose the time unit (days, weeks, months, or years).
   • Location – specifies the ClickHouse volume where the ODS data will be stored. ClickHouse volumes must be configured directly in your ClickHouse environment. You can also select Delete to permanently remove ODS data after the defined retention period expires.

   Warning

   Selecting Delete in the Location field will cause the data to be permanently deleted after the retention period expires. This action is irreversible.

   The creation of ClickHouse volumes is not supported when using ClickHouse Cloud.

   Keep Data in Default LocationDelete Data After Retention Period

   

   

4. After defining all retention times, select Update to apply the configuration.

Understanding Entity Type Access Levels#

All properties of an Entity Type must have an access level defined. This access level is responsible for ensuring that the corresponding property is visible or updated whenever it is required.

The access level can be represented in the form of the table below, where each field describes the significance of setting the appropriate value as true for a given property.

Table: Access Level for Entity Type Property

The image below shows the access levels for a property Name of an Entity Type:

Note that the table shows the information for View/Create/Update so that different information can be defined for an instance (marked as ENTITY) or a template (TEMPLATE). Any value set on the access level for TEMPLATE (for example, Read Only/CREATE set to true) will be relevant only if the Entity Type allows the creation of templates.

Furthermore, the information displayed shows that the field Read Only/VIEW is set to true for both ENTITY and TEMPLATE. Furthermore, field Read Only/UPDATE is also set to true indicating that property Name cannot be updated either for TEMPLATE or ENTITY.

Generating An Entity Type Schema#

EntityType.GenerateSchema

It is necessary to generate the schema for the entity in the following situations:

• An entity is created (for the first time).
• A new custom property is added (or modified) or an existing attribute is changed to a custom property.

After the entity type is created, to actually generate it, one needs to select the Generate Schema button (image below). Be sure to do this in a test system first! It is also necessary to perform the Generate Schema action whenever a new Custom Property is added or changed. The creation of attributes does not require Generate Schema to be run.

To generate the Entity Type (Schema and .Net Assembly) is necessary to select the Generate Schema button.

When a MES host receives a Generate Schema request, it performs the following actions by default:

• Creates the necessary database tables for the new entity's data.
• Generates the C# object (Business Object) used in services or orchestration.
• Compiles the generated code into a .Net Assembly file (Cmf.Custom.BusinessObjects.<EntityTypeName>.dll).
• Copies the .dll file to the [Services].[T_GeneratedAssembly] table in the MES online database.
• If AssemblyDeploy is set to true in the host's app.config file, a multicast message is published to all servers, deploying the Assembly to each MES host deployment path.

Making a Custom Entity Available in the GUI#

Critical Manufacturing MES provides a default, basic GUI for all entity types. To make a new custom entity type available in the Business Data GUI, the following steps are required.

1. Set the property "Visible in business data" to "true".
2. Generate the custom entity.

3. Create the custom entity security features to control its visibility and available actions within the system. These features include:

   • EntityTypeName.ChangeState
   • EntityTypeName.Clone
   • EntityTypeName.Comment
   • EntityTypeName.Create
   • EntityTypeName.CreateFromTemplate
   • EntityTypeName.CreateTemplate
   • EntityTypeName.Edit
   • EntityTypeName.Export
   • EntityTypeName.History
   • EntityTypeName.Import
   • EntityTypeName.ManageAttachments
   • EntityTypeName.MassUpdate
   • EntityTypeName.MasterDataExport
   • EntityTypeName.Show
   • EntityTypeName.Terminate
   • EntityTypeName.Unterminate

4. Associate the newly created security features to specific users or security groups within the system.

LBOs#

On this page, it is possible to download LBOs by selecting the Download LBOs button.

If a generation is in progress when the LBOs are requested, it will be possible to track the progress of the Generation.

When the generation is over there will be a feedback message indicating success.

If there are errors in the generation there is also a feedback message. In this message there is an option to download the last successful LBOs, or the default ones if no successful generation occurred yet.