Skip to content

Layers packages

The CM MES architecture is composed of various system layers highly customizable.

This page provides an overview of the various layers packages available for customizing MES projects, that can be created using the CM CLI. Each layer package serves a specific purpose and offers a structured approach for managing your customizations.

cmf init

Before creating layers packages, ensure you have initialized your project using the cmf init command. This command defines the project's unique name based on the specified TENANT name specified on the environment settings file. This name will be used throughout your layers packages for consistent identification.

MES Customization

Learn more about CM MES extensibility points in the Critical Manufacturing Developer Portal: https://developer.criticalmanufacturing.com.

Layers Packages Explained

Each layer package focuses on a specific aspect of your customization.

1. Business

This package provides a .NET solution for backend development, including:

  • Exposing new REST API services;
  • Extending orchestration and business logic used by API services or DEE actions;

Creating a Business Package:

cmf new business --version 1.0.0

Package Structure:

The created package is composed of three .NET projects:

  • Common - Stores constants, utilities, and other reusable classes.
  • Orchestration - Houses custom business contracts, logic, and IOC configuration.
  • Services - Defines custom REST API services to be consumed by the UI or other MES Rest API client.
📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.Business
 ┃ ┣ 📂Cmf.Custom.Common                 # Common Project 
 ┃ ┃ ┣ 📜Cmf.Custom.{{TENANT}}.Common.csproj
 ┃ ┃ ┣ 📜{{TENANT}}Constants.cs
 ┃ ┃ ┗ 📜{{TENANT}}Utilities.cs
 ┃ ┣ 📂Cmf.Custom.Orchestration          # Orchestration Project
 ┃ ┃ ┣ 📂Abstractions
 ┃ ┃ ┃ ┗ 📜I{{TENANT}}Orchestration.cs 
 ┃ ┃ ┣ 📂InputObjects
 ┃ ┃ ┣ 📂OutputObjects
 ┃ ┃ ┣ 📜Cmf.Custom.{{TENANT}}.Orchestration.csproj
 ┃ ┃ ┣ 📜{{TENANT}}Orchestration.cs
 ┃ ┃ ┗ 📜OrchestrationStartupModule.cs
 ┃ ┣ 📂Cmf.Custom.Services               # REST Services Project
 ┃ ┃ ┣ 📜Cmf.Custom.{{TENANT}}.Services.csproj 
 ┃ ┃ ┗ 📜{{TENANT}}Controller.cs            
 ┃ ┣ 📜Business.sln
 ┃ ┗ 📜cmfpackage.json
 ┣ ...

2. Master Data

This package allows you to load or update:

  • Exported Objects (e.g., UI pages, queries);
  • Process Rules (DEE actions executed during package installation);
  • Master Data (system and/or business entity data).

Creating a Master Data Package:

cmf new data --version 1.0.0 --businessPackage .\Cmf.Custom.Business\

Note

The association of "Data" package with "Business" package, results in a change in the "Business" .NET solution file, to include the "Actions" .NET project. This improves the developer's experience, as he will be able to edit all .NET code in the same integrated environment.

Package Structure:

The Master Data package structure includes folders for:

  • DEEs: Stores logic for Process Rules (executed during installation) and DEE Actions (executed by DEE extension points on the MES backend logic).
  • ExportedObjects: Contains objects (e.g., UI pages, queries) to be created or updated.
  • MasterData: Holds system and/or business entity data for updates.
📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.Data
 ┃ ┣ 📂DEEs             # Folder to store DEE Actions / Process Rules
 ┃ ┃ ┣ 📂ProcessRules   
 ┃ ┃ ┃ ┣ 📂1.0.0
 ┃ ┃ ┃ ┃ ┣ 📂After                
 ┃ ┃ ┃ ┃ ┃ ┗ 📜...      # Process rules for v1.0.0 release to be executed after
 ┃ ┃ ┃ ┃ ┗ 📂Before
 ┃ ┃ ┃ ┃ ┃ ┗ 📜...      # Process rules to run on v1.0.0 installation before host restart
 ┃ ┃ ┃ ┣ 📂EntityTypes
 ┃ ┃ ┃ ┃ ┗ 📜...        # Process rules to create/change MES entities/tables
 ┃ ┃ ┃ ┗ 📜readme.md
 ┃ ┃ ┣ 📜.cmfpackageignore
 ┃ ┃ ┣ 📜Cmf.Custom.{{TENANT}}.Actions.csproj
 ┃ ┃ ┗ 📜DeeDevBase.cs
 ┃ ┣ 📂ExportedObjects
 ┃ ┃ ┗ 📂1.0.0
 ┃ ┃ ┃ ┗ 📜...          # Exported objects to be created/updated on v1.0.0 installation
 ┃ ┣ 📂MasterData
 ┃ ┃ ┣ 📂1.0.0
 ┃ ┃ ┃ ┗ 📜...          # Exported objects to be created/updated on v1.0.0 installation
 ┃ ┃ ┗ 📜readme.md
 ┃ ┗ 📜cmfpackage.json
 ┣ ...

Note

Inspect the package cmfpackage.json file contents to understand:

  • The expected location for files used on a Master Data package;
  • How to extend the package build behavior.

3. UI

This layer consists of two sub-packages for extending the MES UI:

  • HTML - Allows customization of existing MES UI pages, controls, routes and creation of new controls, pages, or wizards.
  • Help - Enables adding documentation entries to the MES Help system to explain your customizations.

Generating UI Packages:

The commands for generating UI packages depends on your MES version:

# HTML
cmf new html --version 1.0.0

# HELP
cmf new help --version 1.0.0

To scaffold HTML and Help, their Deployment Framework package needs to be specified. These files can be found in the MES ISO/disk. Assuming that ISO is mounted on H: drive and MES target version is 9.1.8, use the commands:

#HTML
cmf new html --version 1.0.0 --htmlPackage H:\packages\Cmf.Presentation.HTML.9.1.8.zip

#HELP
cmf new help --version 1.0.0 --documentationPackage H:\packages\Cmf.Documentation.9.1.8.zip

Package Structure:

The resulting file structure depends on the MES version. For details on its usage check CM Training Presentation Training Courses or the Developer Portal.

Hint

If you require NPM registry authentication, the current procedure is to include the auth information in the apps\customization.web.npmrc file as is standard.

4. IoT

This package facilitates developing custom IoT tasks and converters. It also includes a structure for managing IoT Workflows and MasterData under source control.

Generating an IoT Package:

The command for generating IoT packages depends on your MES version:

cmf new iot --version 1.0.0 --htmlPackageLocation Cmf.Custom.Baseline.HTML

Make sure to follow all the steps here. Otherwise, you can have unexpected errors in the package.

cmf new iot --version 1.0.0

Package Structure:

The generated package includes sub-packages for:

  • IoT.Data: Stores IoT-specific MasterData.
  • IoT.Packages: Stores custom tasks and converters implementation.
📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.IoT
 ┃ ┣ 📂Cmf.Custom.IoT.Data
 ┃ ┃ ┣ 📂AutomationWorkFlows
 ┃ ┃ ┃ ┗ 📜...                  # Exported Workflows files
 ┃ ┃ ┣ 📂MasterData
 ┃ ┃ ┃ ┗ 📂1.0.0
 ┃ ┃ ┃ ┃ ┗ 📜...                # IoT MasterData files
 ┃ ┃ ┗ 📜cmfpackage.json
 ┃ ┣ 📂Cmf.Custom.IoT.Packages
 ┃ ┃ ┣ 📂src
 ┃ ┃ ┃ ┗ 📜...                  # Location for Custom Tasks and Converters code
 ┃ ┃ ┣ 📜cmfpackage.json
 ┃ ┗ 📜cmfpackage.json
 ┣ 📂...

5. Database

This package allows creating scripts for execution on MES databases during installation.

Generating a Database Package:

cmf new database --version 1.0.0

Package Structure:

The created package includes sub-packages for scripts to be executed:

  • Pre: Before MES Host restart.
  • Post: After MES Host restart.

Each sub-package further contains folders for specific MES databases (ONLINE, ODS, DWH) to store relevant SQL scripts.

📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.Database
 ┃ ┣ 📂Post
 ┃ ┃ ┣ 📂DWH
 ┃ ┃ ┣ 📂ODS
 ┃ ┃ ┣ 📂ONLINE
 ┃ ┃ ┗ 📜cmfpackage.json
 ┃ ┣ 📂Pre
 ┃ ┃ ┣ 📂DWH
 ┃ ┃ ┣ 📂ODS
 ┃ ┃ ┣ 📂ONLINE
 ┃ ┃ ┗ 📜cmfpackage.json
 ┣ ...

6. Tests

The Tests package provides a framework for creating regression tests to ensure the quality and reliability of your MES customization project. It utilizes the .NET MsTests framework to define and execute test cases.

While the Tests package follows the same structure and creation process as other layer packages, it is not installable as part of the MES system. It is primarily used for internal development and testing purposes.

The package includes dedicated folders for different test types (e.g., Biz, GUI, IoT) and provides necessary configuration files for test execution.

Generating a Test Package:

cmf new test --version 1.0.0

Package Structure:

The created package structure incorporates folders for various test categories:

  • Tests.Biz: Contains project files for Business logic (BE) tests.
  • Tests.Biz.Common: Houses project files for commonly used functionalities across tests.
  • Tests.GUI: Includes project files for Graphical User Interface (GUI) tests.
  • Tests.GUI.PageObjects: Provides project files for defining objects to interact with GUI functionalities during testing.
  • Tests.IoT: Encompasses project files for Internet of Things (IoT) specific tests.
  • MasterData: This folder serves as a repository to store test master data. This data is used to set up the MES environment before actual test execution.
 📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.Tests
 ┃ ┣ 📂Cmf.Custom.Tests.Biz
 ┃ ┃ ┣ 📜Cmf.Custom.Tests.Biz.csproj        #== BE Tests Project
 ┃ ┣ 📂Cmf.Custom.Tests.Biz.Common
 ┃ ┃ ┗ 📜Cmf.Custom.Tests.Biz.Common.csproj #== Common Functions Project
 ┃ ┣ 📂Cmf.Custom.Tests.GUI
 ┃ ┃ ┣ 📜Cmf.Custom.Tests.GUI.csproj        #== GUI Tests Project
 ┃ ┣ 📂Cmf.Custom.Tests.GUI.PageObjects
 ┃ ┃ ┗ 📜Cmf.Custom.Tests.GUI.PageObjects.csproj
 ┃ ┣ 📂Cmf.Custom.Tests.IoT
 ┃ ┃ ┣ 📂Framework
 ┃ ┃ ┣ 📂Tests
 ┃ ┃ ┣ 📜Cmf.Custom.Tests.IoT.csproj        #== IoT Tests Project
 ┃ ┣ 📂MasterData
 ┃ ┃ ┣ 📂Files                 #== Master Data for Test Environment
 ┃ ┃ ┗ 📜cmfpackage.json
 ┃ ┣ 📜app.config
 ┃ ┣ 📜cmfpackage.json
 ┃ ┣ 📜integration.runsettings
 ┃ ┣ 📜local.runsettings
 ┃ ┗ 📜Tests.sln
 ┣ ...

7. Reporting

This package layer allows the installation of additional SQL ServerReporting Services (SSRS) reports to the MES.

Generating a Test Package:

cmf new reporting --version 1.0.0

Package Structure:

The created package structure incorporates folders to store RDL files that will be installed on the MES SSRS folder.

 📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.Reporting
 ┃ ┣ 📂1.0.0
 ┃ ┃ ┗ 📂Custom           # SRSS folder to store the reporting services
 ┃ ┗ 📜cmfpackage.json
 ┣ ...

8. Grafana

This package layer allows you to create/update grafana dashboards in the MES infrastructure (only applicable to environments running in containers with MES v10 or above).

Generating a Grafana Package:

cmf new grafana --version 1.0.0

Package Structure:

The created package structure incorporates folders to store grafana dashboards and data sources.

 📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.Grafana
 ┃ ┣ 📂1.0.0
 ┃ ┃ ┣ 📂dashboards
 ┃ ┃ ┃ ┣ 📂{{TENANT}}
 ┃ ┃ ┃ ┗ 📜dashboards.yaml
 ┃ ┃ ┗ 📂datasources
 ┃ ┃ ┃ ┗ 📜datasources.yaml
 ┃ ┣ 📜cmfpackage.json
 ┃ ┗ 📜README.md
 ┣ ...

9. SecurityPortal

This package layer allows the configuration of authentication strategies on the MES Security Portal component.

Warning

Whenever possible security strategies should be defined through CM DevOps Center. Use this package, only if, your strategy cannot be defined there or the target environment is not running on containers.

Generating a SecurityPortal Package:

cmf new securityportal --version 1.0.0

Package Structure:

This is a simple package. Use the config.json file to define the additional security settings/strategies for the CM MES Security Portal component.

 📦Project
 ┣ ...
 ┣ 📂Cmf.Custom.SecurityPortal
 ┃ ┣ 📜cmfpackage.json
 ┃ ┗ 📜config.json
 ┣ ...

Deprecated layer packages

Exported Objects

Even though the CLI does not provide scaffolding for an ExportedObjects package, as it generally is better to include these in Master Data packages, it is possible to create such a package and the tool will pack it as with any other package type.

As an example, an ExportedObjects package manifest looks like this:

{
  "packageId": "Cmf.Custom.Baseline.ExportedObjects",
  "version": "1.0.0",
  "description": "Baseline Exported Objects Package",
  "packageType": "ExportedObjects",
  "isInstallable": true,
  "isUniqueInstall": false,
  "contentToPack": [
    {
      "source": "$(version)/*",
      "target": "ExportedObjects"
    }
  ]
}

You would create a cmfpackage.json file inside the objects folder with this content. This will pack any XML file in a folder named after the current package version, so in this case 1.0.0 and place it in the package file in an ExportedObjects folder.

Afterwards, do not forget to add this new package as a dependency of your root/feature package, to make sure it gets installed when required.