Advanced Production & BOM Management

Overview

• What you’ll learn:
  • How Production Plans (MProductionPlan) enable multi-product production runs under a single MProduction header
  • How lot and serial tracking works through MProductionLineMA and Attribute Set Instances during production
  • How BOM Verification (BOMVerify) validates structure integrity, detects circular references, and ensures master BOMs exist
  • How phantom BOM expansion recursively replaces non-stocked assemblies with their component parts during line creation
  • How ProductionCreate and ProductionProcess drive the production document lifecycle
• Prerequisites: Lessons 24–25 — Production Overview and Inventory & Warehouse Management
• Estimated reading time: 22 minutes

Introduction

In earlier lessons you learned the fundamentals of iDempiere production — creating a simple production document, defining Bills of Materials, and completing a basic production run. Those basics cover straightforward scenarios where one finished product consumes a fixed set of components in a single operation.

Real-world manufacturing is rarely that simple. A single production run may yield multiple finished products simultaneously. Component materials must be tracked by lot or serial number for quality traceability. BOMs grow complex with phantom sub-assemblies that exist only as logical groupings and never occupy warehouse shelves. Before any production runs, the BOM structure itself needs validation to catch circular references or missing components.

This lesson covers the advanced production and BOM management capabilities in iDempiere’s core production module.

Production Plans: Multi-Product Production Runs

A standard MProduction document produces a single finished product. But many manufacturing environments produce multiple items in a single run — for example, a cutting operation that yields several different parts from the same raw material.

iDempiere handles this through Production Plans. When IsUseProductionPlan is set to true on the production header, the system shifts from a single-product model to a multi-product model using MProductionPlan records.

The MProductionPlan Structure

// Multi-product production with production plans
MProduction production = new MProduction(ctx, 0, trxName);
production.setAD_Org_ID(orgId);
production.setM_Product_ID(finishedProductId);
production.setMovementDate(new Timestamp(System.currentTimeMillis()));
production.setIsUseProductionPlan(true);
production.saveEx();

// Plan 1: Product A — 50 units
MProductionPlan plan1 = new MProductionPlan(production);
plan1.setM_Product_ID(productA_ID);
plan1.setProductionQty(new BigDecimal("50"));
plan1.setM_Locator_ID(locatorId);
plan1.saveEx();

// Plan 2: Product B — 30 units
MProductionPlan plan2 = new MProductionPlan(production);
plan2.setM_Product_ID(productB_ID);
plan2.setProductionQty(new BigDecimal("30"));
plan2.setM_Locator_ID(locatorId);
plan2.saveEx();

// Generate lines for each plan independently
plan1.createLines(true);  // true = mustBeStocked
plan2.createLines(true);

// Each plan manages its own production lines
MProductionLine[] plan1Lines = plan1.getLines();
MProductionLine[] plan2Lines = plan2.getLines();
System.out.println("Plan 1: " + plan1Lines.length + " lines");
System.out.println("Plan 2: " + plan2Lines.length + " lines");

Lot and Serial Tracking with MProductionLineMA

Traceability is critical in regulated industries. iDempiere’s production module achieves lot-level tracking through Material Allocation records stored in MProductionLineMA.

What Is Material Allocation?

A MProductionLineMA record links a production line to a specific Attribute Set Instance (ASI). When a production line consumes 100 units of a component, those units may come from multiple lots — 60 from Lot A and 40 from Lot B. Each allocation is recorded separately.

// During production completion, MA records drive inventory transactions
MProductionLine line = ...; // a component consumption line
MProduct product = line.getM_Product();

if (product.getM_AttributeSet_ID() != 0) {
    // Product requires attribute tracking
    MProductionLineMA[] mas = MProductionLineMA.get(ctx,
        line.getM_ProductionLine_ID(), trxName);

    for (MProductionLineMA ma : mas) {
        BigDecimal qty = ma.getMovementQty();
        int asiId = ma.getM_AttributeSetInstance_ID();
        Timestamp datePolicy = ma.getDateMaterialPolicy();

        // Each MA record generates a separate inventory transaction
        // with its own ASI for lot-level tracking
        System.out.println("Consuming " + qty + " units from ASI=" + asiId
            + " with policy date " + datePolicy);
    }
}

FIFO/LIFO and DateMaterialPolicy

The DateMaterialPolicy field is essential for FIFO or LIFO costing. When components are consumed, the system selects cost layers based on this date. For FIFO, the oldest records are consumed first. For LIFO, the newest are consumed first.

Auto-Generating Lot Numbers

When finished products require lot tracking, the production completion process auto-generates new lot numbers for the output. A new M_AttributeSetInstance is created and populated based on the attribute set’s lot control settings.

BOM Verification with BOMVerify

Before running production, you need confidence that your BOM is structurally sound. The BOMVerify process catches problems before they disrupt production.

What BOMVerify Checks

• Master BOM existence: Verifies the product has a BOM flagged as master (default BOM requires BOMUse = 'A' AND BOMType = 'A' — this is what MPPProductBOM.getDefault() looks for)
• Circular reference detection: Walks the BOM tree recursively to ensure no product appears as both ancestor and descendant
• Component validity: Checks that every BOM line references a valid, active product
• Stocking validation: Confirms non-phantom components are stocked items
• IsVerified flag: Updates the product’s IsVerified flag upon success

BOMVerify Parameters

// Running BOM verification programmatically
MPInstance instance = new MPInstance(ctx, bomVerifyProcessId, 0);
instance.saveEx();

// Single product verification
MPInstancePara para = new MPInstancePara(instance, 10);
para.setParameter("M_Product_ID", productId);
para.saveEx();

// Re-validate previously verified products
MPInstancePara paraRevalidate = new MPInstancePara(instance, 20);
paraRevalidate.setParameter("IsReValidate", "Y");
paraRevalidate.saveEx();

ProcessInfo pi = new ProcessInfo("BOM Verify", bomVerifyProcessId);
pi.setAD_PInstance_ID(instance.getAD_PInstance_ID());

BOMVerify process = new BOMVerify();
process.startProcess(ctx, pi, null);

if (pi.isError()) {
    System.err.println("BOM verification failed: " + pi.getSummary());
} else {
    System.out.println("BOM verified: " + pi.getSummary());
}

Phantom BOM Expansion in Detail

A phantom assembly exists in the BOM for organizational purposes but is never physically stocked. During createLines(), phantom components are recursively expanded into their leaf components.

The ComponentType field on MPPProductBOMLine controls how each line behaves during production. The full set of values:

• Component — Standard part consumed during production
• Phantom — Recursively expanded; never stocked separately
• By-Product — Secondary output received into inventory (e.g., scrap metal from cutting)
• Co-Product — Joint output of equal importance (e.g., chemical process yielding multiple products)
• Packing — Packaging material consumed
• Tools — Tooling required but not consumed
• Variant — Alternative component for product variants
• Option — Optional component (configurable BOMs)
• Planning — Used for MRP planning only, not production

How Phantoms Work

A product is treated as a phantom when:

• The BOM line has ComponentType = 'PH' (checked via MPPProductBOMLine.COMPONENTTYPE_Phantom.equals(bomLine.getComponentType()))
• The component product itself is marked isPhantom() = true on the M_Product record
• The component product has its own BOM (isBOM() = true)
• The product is typically configured with isStocked() = false

Phantom vs. Regular Sub-Assembly

// Conceptual illustration of phantom expansion during createLines()
// This logic is internal to MProduction/MProductionPlan

private void expandBOM(MPPProductBOM bom, BigDecimal parentQty,
        int locatorId) {
    MPPProductBOMLine[] bomLines = bom.getLines();

    for (MPPProductBOMLine bomLine : bomLines) {
        MProduct component = MProduct.get(ctx, bomLine.getM_Product_ID());
        BigDecimal componentQty = bomLine.getQtyBOM().multiply(parentQty);

        if (MPPProductBOMLine.COMPONENTTYPE_Phantom.equals(bomLine.getComponentType())
                && component.isBOM()) {
            // PHANTOM: Recursively expand — no line created for phantom itself
            MPPProductBOM subBOM = MPPProductBOM.getDefault(component, trxName);
            expandBOM(subBOM, componentQty, locatorId);
        } else {
            // REGULAR: Create consumption line
            MProductionLine line = new MProductionLine(plan);
            line.setM_Product_ID(component.getM_Product_ID());
            line.setMovementQty(componentQty.negate()); // negative = consume
            line.setM_Locator_ID(locatorId);
            line.saveEx();
        }
    }
}

ProductionCreate and ProductionProcess

Two key processes drive the production lifecycle:

ProductionCreate — Generate Lines from BOM

ProductionProcess — Execute Document Workflow

ProductionProcess uses MWorkflow.runDocumentActionWorkflow() to ensure workflow conditions, approvals, and transitions are properly executed. When completeIt() runs:

• Iterates through all production lines (or plans)
• Creates MTransaction records for inventory movements
• Processes MProductionLineMA records for lot tracking
• Updates MStorageOnHand quantities
• Posts accounting entries

Note: M_Production_Run is @Deprecated(since="13", forRemoval=true). Always use ProductionProcess instead.

// Complete production workflow
MProduction production = new MProduction(ctx, productionId, trxName);
production.setDocAction(DocAction.ACTION_Complete);
production.saveEx();

// Process via document action
if (!production.processIt(DocAction.ACTION_Complete)) {
    throw new AdempiereException("Production failed: "
        + production.getProcessMsg());
}
production.saveEx();
System.out.println("Production completed: " + production.getDocumentNo());

Key Takeaways

• Production Plans (MProductionPlan) enable multi-product production when IsUseProductionPlan=true. Each plan manages its own product, BOM, and lines independently.
• Material Allocation (MProductionLineMA) provides lot-level traceability. The DateMaterialPolicy field ensures correct FIFO/LIFO cost layer selection.
• BOM Verification (BOMVerify) is critical pre-production validation — checks for circular references, missing components, and master BOM existence.
• Phantom Expansion recursively replaces non-stocked assemblies with leaf components during createLines(). Phantom products are never consumed or produced directly.
• ProductionCreate generates lines from BOM; ProductionProcess executes the DocAction workflow. M_Production_Run is deprecated.

What’s Next

The next lesson — Production Costing & Analysis — covers how iDempiere tracks and calculates production costs, including costing methods, the MCost and MCostDetail APIs, and multi-level BOM cost rollup using IndentedBOM.

// Multi-product production with production plans
MProduction production = new MProduction(ctx, 0, trxName);
production.setAD_Org_ID(orgId);
production.setM_Product_ID(finishedProductId);
production.setMovementDate(new Timestamp(System.currentTimeMillis()));
production.setIsUseProductionPlan(true);
production.saveEx();

// Plan 1: Product A — 50 units
MProductionPlan plan1 = new MProductionPlan(production);
plan1.setM_Product_ID(productA_ID);
plan1.setProductionQty(new BigDecimal("50"));
plan1.setM_Locator_ID(locatorId);
plan1.saveEx();

// Plan 2: Product B — 30 units
MProductionPlan plan2 = new MProductionPlan(production);
plan2.setM_Product_ID(productB_ID);
plan2.setProductionQty(new BigDecimal("30"));
plan2.setM_Locator_ID(locatorId);
plan2.saveEx();

// Generate lines for each plan independently
plan1.createLines(true);  // true = mustBeStocked
plan2.createLines(true);

// Each plan manages its own production lines
MProductionLine[] plan1Lines = plan1.getLines();
MProductionLine[] plan2Lines = plan2.getLines();
System.out.println("Plan 1: " + plan1Lines.length + " lines");
System.out.println("Plan 2: " + plan2Lines.length + " lines");

// During production completion, MA records drive inventory transactions
MProductionLine line = ...; // a component consumption line
MProduct product = line.getM_Product();

if (product.getM_AttributeSet_ID() != 0) {
    // Product requires attribute tracking
    MProductionLineMA[] mas = MProductionLineMA.get(ctx,
        line.getM_ProductionLine_ID(), trxName);

    for (MProductionLineMA ma : mas) {
        BigDecimal qty = ma.getMovementQty();
        int asiId = ma.getM_AttributeSetInstance_ID();
        Timestamp datePolicy = ma.getDateMaterialPolicy();

        // Each MA record generates a separate inventory transaction
        // with its own ASI for lot-level tracking
        System.out.println("Consuming " + qty + " units from ASI=" + asiId
            + " with policy date " + datePolicy);
    }
}

// Running BOM verification programmatically
MPInstance instance = new MPInstance(ctx, bomVerifyProcessId, 0);
instance.saveEx();

// Single product verification
MPInstancePara para = new MPInstancePara(instance, 10);
para.setParameter("M_Product_ID", productId);
para.saveEx();

// Re-validate previously verified products
MPInstancePara paraRevalidate = new MPInstancePara(instance, 20);
paraRevalidate.setParameter("IsReValidate", "Y");
paraRevalidate.saveEx();

ProcessInfo pi = new ProcessInfo("BOM Verify", bomVerifyProcessId);
pi.setAD_PInstance_ID(instance.getAD_PInstance_ID());

BOMVerify process = new BOMVerify();
process.startProcess(ctx, pi, null);

if (pi.isError()) {
    System.err.println("BOM verification failed: " + pi.getSummary());
} else {
    System.out.println("BOM verified: " + pi.getSummary());
}

// Conceptual illustration of phantom expansion during createLines()
// This logic is internal to MProduction/MProductionPlan

private void expandBOM(MPPProductBOM bom, BigDecimal parentQty,
        int locatorId) {
    MPPProductBOMLine[] bomLines = bom.getLines();

    for (MPPProductBOMLine bomLine : bomLines) {
        MProduct component = MProduct.get(ctx, bomLine.getM_Product_ID());
        BigDecimal componentQty = bomLine.getQtyBOM().multiply(parentQty);

        if (MPPProductBOMLine.COMPONENTTYPE_Phantom.equals(bomLine.getComponentType())
                && component.isBOM()) {
            // PHANTOM: Recursively expand — no line created for phantom itself
            MPPProductBOM subBOM = MPPProductBOM.getDefault(component, trxName);
            expandBOM(subBOM, componentQty, locatorId);
        } else {
            // REGULAR: Create consumption line
            MProductionLine line = new MProductionLine(plan);
            line.setM_Product_ID(component.getM_Product_ID());
            line.setMovementQty(componentQty.negate()); // negative = consume
            line.setM_Locator_ID(locatorId);
            line.saveEx();
        }
    }
}

// Complete production workflow
MProduction production = new MProduction(ctx, productionId, trxName);
production.setDocAction(DocAction.ACTION_Complete);
production.saveEx();

// Process via document action
if (!production.processIt(DocAction.ACTION_Complete)) {
    throw new AdempiereException("Production failed: "
        + production.getProcessMsg());
}
production.saveEx();
System.out.println("Production completed: " + production.getDocumentNo());

// Multi-product production with production plans
MProduction production = new MProduction(ctx, 0, trxName);
production.setAD_Org_ID(orgId);
production.setM_Product_ID(finishedProductId);
production.setMovementDate(new Timestamp(System.currentTimeMillis()));
production.setIsUseProductionPlan(true);
production.saveEx();

// Plan 1: Product A — 50 units
MProductionPlan plan1 = new MProductionPlan(production);
plan1.setM_Product_ID(productA_ID);
plan1.setProductionQty(new BigDecimal("50"));
plan1.setM_Locator_ID(locatorId);
plan1.saveEx();

// Plan 2: Product B — 30 units
MProductionPlan plan2 = new MProductionPlan(production);
plan2.setM_Product_ID(productB_ID);
plan2.setProductionQty(new BigDecimal("30"));
plan2.setM_Locator_ID(locatorId);
plan2.saveEx();

// Generate lines for each plan independently
plan1.createLines(true);  // true = mustBeStocked
plan2.createLines(true);

// Each plan manages its own production lines
MProductionLine[] plan1Lines = plan1.getLines();
MProductionLine[] plan2Lines = plan2.getLines();
System.out.println("Plan 1: " + plan1Lines.length + " lines");
System.out.println("Plan 2: " + plan2Lines.length + " lines");

// During production completion, MA records drive inventory transactions
MProductionLine line = ...; // a component consumption line
MProduct product = line.getM_Product();

if (product.getM_AttributeSet_ID() != 0) {
    // Product requires attribute tracking
    MProductionLineMA[] mas = MProductionLineMA.get(ctx,
        line.getM_ProductionLine_ID(), trxName);

    for (MProductionLineMA ma : mas) {
        BigDecimal qty = ma.getMovementQty();
        int asiId = ma.getM_AttributeSetInstance_ID();
        Timestamp datePolicy = ma.getDateMaterialPolicy();

        // Each MA record generates a separate inventory transaction
        // with its own ASI for lot-level tracking
        System.out.println("Consuming " + qty + " units from ASI=" + asiId
            + " with policy date " + datePolicy);
    }
}

// Running BOM verification programmatically
MPInstance instance = new MPInstance(ctx, bomVerifyProcessId, 0);
instance.saveEx();

// Single product verification
MPInstancePara para = new MPInstancePara(instance, 10);
para.setParameter("M_Product_ID", productId);
para.saveEx();

// Re-validate previously verified products
MPInstancePara paraRevalidate = new MPInstancePara(instance, 20);
paraRevalidate.setParameter("IsReValidate", "Y");
paraRevalidate.saveEx();

ProcessInfo pi = new ProcessInfo("BOM Verify", bomVerifyProcessId);
pi.setAD_PInstance_ID(instance.getAD_PInstance_ID());

BOMVerify process = new BOMVerify();
process.startProcess(ctx, pi, null);

if (pi.isError()) {
    System.err.println("BOM verification failed: " + pi.getSummary());
} else {
    System.out.println("BOM verified: " + pi.getSummary());
}

// Conceptual illustration of phantom expansion during createLines()
// This logic is internal to MProduction/MProductionPlan

private void expandBOM(MPPProductBOM bom, BigDecimal parentQty,
        int locatorId) {
    MPPProductBOMLine[] bomLines = bom.getLines();

    for (MPPProductBOMLine bomLine : bomLines) {
        MProduct component = MProduct.get(ctx, bomLine.getM_Product_ID());
        BigDecimal componentQty = bomLine.getQtyBOM().multiply(parentQty);

        if (MPPProductBOMLine.COMPONENTTYPE_Phantom.equals(bomLine.getComponentType())
                && component.isBOM()) {
            // PHANTOM: Recursively expand — no line created for phantom itself
            MPPProductBOM subBOM = MPPProductBOM.getDefault(component, trxName);
            expandBOM(subBOM, componentQty, locatorId);
        } else {
            // REGULAR: Create consumption line
            MProductionLine line = new MProductionLine(plan);
            line.setM_Product_ID(component.getM_Product_ID());
            line.setMovementQty(componentQty.negate()); // negative = consume
            line.setM_Locator_ID(locatorId);
            line.saveEx();
        }
    }
}

// Complete production workflow
MProduction production = new MProduction(ctx, productionId, trxName);
production.setDocAction(DocAction.ACTION_Complete);
production.saveEx();

// Process via document action
if (!production.processIt(DocAction.ACTION_Complete)) {
    throw new AdempiereException("Production failed: "
        + production.getProcessMsg());
}
production.saveEx();
System.out.println("Production completed: " + production.getDocumentNo());