# Material Serialization ## Overview The **Material Serialization** feature provides a framework for assigning unique identification codes to PCB panels and boards at various stages of the manufacturing process. By utilizing specific **Smart Tables**, users can determine exactly when and how materials expand into smaller units during track-in or track-out operations. The system supports multiple configurations, including **Special Mode**, which allows for two levels of serialization to occur simultaneously within a single production step. This level of traceability ensures that every individual component is accurately tracked from the initial SMT line through to final assembly. The flexible setup also accommodates both internal name generation and external naming conventions to suit different factory requirements. ![Screenshot](images/materialserialization/SerializationDiagram.png) ### Concept When a Material is tracked-in or tracked-out, the table [SMTMaterialExpandContext](../artifacts/tables.md#smtmaterialexpandcontext) is resolved and based on that context the Material is Expanded. Then if the columns: - IsExternalNaming equals `False` - The table [SMTMaterialNameGenerationContext](../artifacts/tables.md#smtmaterialnamegenerationcontext) is resolved and based on that context a Name Generation is assigned to the Material Expand Operation that will be performed !!! info "Info" Further information and examples on how to configure this feature are available in the [Tutorial](https://help.criticalmanufacturing.com/tutorials/industrytemplates/smt/materialserialization/) --- ## Functional Behavior ### System Configuration Before using Material Serialization, the following conditions must be met: - Enable the following global configurations: - `/SMT/MaterialSerialization/` – enables the **Material Serialization** feature - `/SMT/MaterialNameGeneration/` – enables the ability to generate names for the materials - `/SMT/MaterialAutomaticLabelPrinting/` – enables the label-printing functionality of this feature - Define the relationship through the *Material Form Generic Table* between parent and child materials. - Ensure each parent material has sufficient quantity to cover the total quantity required by its child (sub-material) expansion. - Make sure the material's step property `Use Split and Track-Out` is not set to `True`; otherwise, Material Serialization will not be performed. - Ensure a printer is available for each label to be printed, either through the **PrinterTypePrintersContext** Smart Table or through the **Default Printer** of the Printable Document (see [Printer Resolution](#printer-resolution)); otherwise the operation fails with an error message. ### Smart Tables #### SMTMaterialExpandContext This table controls if, when, and how a parent material is expanded (serialized) into child and sub-child materials. The system resolves this table for every material entering a tracked-in or tracked-out operation, using the material's current step, form, product, and product group as resolution criteria. Table fields: - **Expand Step** – the step where expansion is going to occur; - **Parent Form** – the material form of the material being expanded (e.g. _Lot_). Only materials whose form matches this value at the configured _Expand Step_ will trigger the serialization process; - **Child Form** – the material form assigned to the directly expanded child materials (e.g. _Panel_); - **Sub Child Form** – the material form assigned to the second-level expanded materials, children of the child materials (e.g. _Board_). Only applicable when a second level of expansion is configured, either via **Special Mode** or through chained expansion steps; - **Expand Operation** – the transaction that will trigger the serialization process, either _Track-In_ or _Track-Out_. The expansion only occurs when the material enters the configured step via the matching operation; - **Is External Naming** – set to _true_ if the names of the child materials are provided externally (e.g. scanned from labels); set to _false_ if naming is performed automatically by an MES name generator. When set to _false_, the [SMTMaterialNameGenerationContext](../artifacts/tables.md#smtmaterialnamegenerationcontext) table must be configured accordingly; - **Expansion Factor** – integer value controlling the first level of expansion. Defines the primary quantity each child material will hold. Combined with the **Sub Expansion Factor**, it also determines the total number of child materials created; - **Sub Expansion Factor** – integer value controlling the second level of expansion, from child to sub-child form. Defines the number of sub-child materials created per child material, as well as the primary quantity each sub-child material will hold. Required when **Is Special Mode** is set to _true_; - **Detach Step** – the step at which boards (sub-child materials) will be physically separated from their panels (child materials) in a later production stage. When this field is populated, the system saves the configured step name as an attribute (`DetachStep`) on each expanded child material at the moment of serialization, allowing downstream steps to identify and act on panels that are scheduled for detachment. This field is optional; if left empty, no detach step attribute is set on the expanded materials; - **Position Mapping** – when set to _true_, the system assigns a sequential integer position identifier (starting from 1) to each sub-child material (e.g. each _Board_) that does not already have one. This attribute (`MESPositionId`) allows downstream processes to map each board to its physical location within its parent panel, which is essential for placement and traceability purposes. Position mapping is applied only to sub-child materials (i.e. boards), not to the first-level child materials (i.e. panels); - **Is Special Mode** – if the expansion (serialization) has 3 levels, such as _Lot_, _Panel_, and _Board_, and it all occurs at the same expand step, this property must be set to **true**. If the expand from parent to child and from child to sub-child occurs in different steps, **Is Special Mode** should be set to **false**. > **Note:** When **Is Special Mode** is `true`, **Position Mapping** is only applied during the second expansion (panels to boards), not during the first expansion (lot to panels). This ensures that position identifiers are assigned at the board level, where physical placement tracking is relevant. ##### Precedence Rules, Configurations & Execution Behavior - Precedence Rules Definition When resolving the contexts, the system evaluates matching rows in the smart tables using strict **Precedence Keys** (defined from highest priority/most specific to lowest priority/most generic). | Order | Precedence Keys | | :---: | :------------------------------------------------- | | 1 | Product+ExpandStep+ParentForm+ExpandOperation | | 2 | Product+ExpandStep+ParentForm | | 3 | ProductGroup+ExpandStep+ParentForm+ExpandOperation | | 4 | ProductGroup+ExpandStep+ParentForm | | 5 | ExpandStep+ParentForm+ExpandOperation | | 6 | ExpandStep+ParentForm | --- ##### Examples of Valid and Invalid Configurations ###### Valid Configurations - Different Form > **Why it's valid:** Both entries align on `Product`, `ExpandStep`, and `ExpandOperation`, but the material forms (`ParentForm` / `ChildForm`) are different, giving them different contexts. | Entry | Product | ExpandStep | ParentForm | ChildForm | ExpandOperation | IsExternalNaming | ExpansionFactor | IsSpecialMode | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **1st** | `SMT_Product` | `SMT_Assembly` | **`PANEL`** | **`BOARD`** | `Track-In` | `False` | `4` | `False` | | **2nd** | `SMT_Product` | `SMT_Assembly` | **`BOARD`** | **`PCB`** | `Track-In` | `False` | `4` | `False` | --- - Different Product > **Why it's valid:** Both entries align on `ExpandStep`, material forms, and `ExpandOperation`, but the `Product` is different, giving them different contexts. | Entry | Product | ExpandStep | ParentForm | ChildForm | ExpandOperation | IsExternalNaming | ExpansionFactor | IsSpecialMode | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **1st** | **`SMT_Product`** | `SMT_Assembly` | `PANEL` | `BOARD` | `Track-In` | `False` | `4` | `False` | | **2nd** | **`SMT_ProductB`** | `SMT_Assembly` | `PANEL` | `BOARD` | `Track-In` | `False` | `4` | `False` | --- - Different Expand Step > **Why it's valid:** Both entries align on `Product`, material forms, and `ExpandOperation`, but the `ExpandStep` is different, giving them different contexts. | Entry | Product | ExpandStep | ParentForm | ChildForm | ExpandOperation | IsExternalNaming | ExpansionFactor | IsSpecialMode | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **1st** | `SMT_Product` | **`SMT_Assembly`** | `PANEL` | `BOARD` | `Track-In` | `False` | `4` | `False` | | **2nd** | `SMT_Product` | **`SMT_Packing`** | `PANEL` | `BOARD` | `Track-In` | `False` | `4` | `False` | --- ###### Invalid Configurations - Different Special Mode Values with Same Context > **Why it's invalid:** Both entries share the exact same context (`Product`, `ExpandStep`, material forms, `ExpandOperation`). Differing only in `IsSpecialMode` causes a conflict/error. | Entry | Product | ExpandStep | ParentForm | ChildForm | ExpandOperation | IsExternalNaming | ExpansionFactor | IsSpecialMode | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **1st** | `SMT_Product` | `SMT_Assembly` | `PANEL` | `BOARD` | `Track-In` | `False` | `4` | **`True`** | | **2nd** | `SMT_Product` | `SMT_Assembly` | `PANEL` | `BOARD` | `Track-In` | `False` | `4` | **`False`** | --- - Different Expand Operation with Same Context > **Why it's invalid:** Both entries share the same core context (`Product`, `ExpandStep`, material forms). Having a different `ExpandOperation` within the same context raises an error. | Entry | Product | ExpandStep | ParentForm | ChildForm | ExpandOperation | IsExternalNaming | ExpansionFactor | IsSpecialMode | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **1st** | `SMT_Product` | `SMT_Assembly` | `PANEL` | `BOARD` | **`Track-In`** | `False` | `4` | `False` | | **2nd** | `SMT_Product` | `SMT_Assembly` | `PANEL` | `BOARD` | **`Track-Out`** | `False` | `4` | `False` | --- ##### Expected Behavior for Track-In and Track-Out Scenarios Depending on the `ExpandOperation` configured in the [SMTMaterialExpandContext](#smtmaterialexpandcontext), the expansion process behaves as follows: ###### Track-In Scenario - **Trigger:** Executed immediately when the parent material is scanned and tracked into the step. ###### Track-Out Scenario - **Trigger:** Executed at the end of the operation, right before the material moves out of the current step. #### SMTMaterialNameGenerationContext Used to configure and derive, for boards and/or panels, the **Name Generator** to be applied when **Is External Naming** is set to `false` on [SMTMaterialExpandContext](#smtmaterialexpandcontext). Table fields: - **Step** – Step where Name Generator is called - **Customer** – Define the Manufacturer - **Product Group** – Define a Group of Products - **Product** – Define Product - **Form** – Material form - **Operation** – Triggering Operation (AddItemsToPackingContainer, ClosePackingContainer, ExpandMaterial, OpenPackingContainer, StartMaterial) - **Name Generator** – Define the Name Generator to be used - **Label Validation Mask** – Expression used for validation #### SMTMaterialPrintableDocumentContext Used to configure and determine which labels apply to each expand (serialization) operation, when a label is to be printed. Table fields: - **Step** – Step where to print a Printable document - **Customer** – Define the Manufacturer - **Product Group** – Define a Group of Products - **Product** – Define Product - **Flow** – Step Flow - **Material** – Material Name - **Material Type** – Material Type - **Material Form** – Material form - **Operation** – Triggering Operation (AddItemsToPackingContainer, AutomaticAssemble, ClosePackingContainer, Expand, MoveNext, OpenPackingContainer, Serialization, TrackIn, TrackOut) - **Label** – Define the Printable Document to be used - **Synchronous Printing** – Indicates whether the Print should be Synchronous ##### Printer Resolution When a label is printed, the printer is resolved as follows: 1. The **PrinterTypePrintersContext** Smart Table is resolved, using the **Printer Type** of the Printable Document (**Label**) and the facility, step and resource of the material; 2. If the Smart Table does not return a printer, the **Default Printer** of the Printable Document is used. If neither is available, the operation is stopped **before** the printing service is invoked, and the following message is shown: > There's no configured printer for the printable document <>. The operation fails as a whole, so no label is printed and no change is kept. This behavior is the same whether **Synchronous Printing** is enabled or not; when it is disabled, no print request is created. !!! info "Info" When a material has more than one Printable Document to print, each one applies its own **Default Printer**. A Printable Document without a printer never uses the **Default Printer** of another one. When a printer is available, the labels are printed as usual. --- You can find more detailed information in the [**Material Serialization**](https://help.criticalmanufacturing.com/tutorials/industrytemplates/smt/materialserialization/) tutorial.