Material management API BOM sync fails when duplicate material numbers exist across plants

MES Siemens Opcenter Execution
, , , , , , , ,
1

We’re synchronizing BOMs from our PLM system to Opcenter Execution 4.0 using the material-mgmt API. The sync fails whenever a material number exists in multiple plants with different specifications.

Our company uses the same material number across plants (e.g., MAT-12345) but with plant-specific variants. When the API tries to sync a BOM containing these materials, it throws a conflict error saying ‘duplicate material identifier’.

<BOM>
  <Material number="MAT-12345" plant="Plant-A"/>
  <Material number="MAT-12345" plant="Plant-B"/>
</BOM>
Error: Duplicate material MAT-12345 in sync payload

How should we handle material deduplication in the API when the same number has plant-specific contexts?

2

Use the plantId field in the API payload to establish plant-specific material contexts. The material-mgmt module supports multi-plant scenarios where the combination of materialNumber + plantId creates unique records. Make sure both fields are included in every material reference within your BOM sync.

3

So the plantId field acts as part of the unique key? That would solve our issue if we include it consistently in all material references.

4

The material-mgmt API requires unique material identifiers. If you’re using the same number across plants, you need to include plant code in the material key. Try using composite keys like ‘MAT-12345-PlantA’ instead of relying on separate plant attributes.

5

Here’s the comprehensive solution covering BOM deduplication, API conflict handling, and integration validation:

BOM Deduplication Strategy: The material-mgmt API in SOC 4.0 uses composite keys for material identification in multi-plant environments. The unique identifier is the combination of materialNumber + plantId, not materialNumber alone. Restructure your BOM sync payload to include plant context on every material reference:

<BOM plantId="Plant-A">
  <Material number="MAT-12345" plantId="Plant-A" description="Variant A"/>
  <Component number="MAT-67890" plantId="Plant-A"/>
</BOM>

When syncing materials that exist across multiple plants, send separate BOM sync requests per plant. This ensures the API processes each plant context independently:

<!-- Sync 1: Plant A BOM -->
<BOM plantId="Plant-A">
  <Material number="MAT-12345" plantId="Plant-A"/>
</BOM>

<!-- Sync 2: Plant B BOM -->
<BOM plantId="Plant-B">
  <Material number="MAT-12345" plantId="Plant-B"/>
</BOM>

API Conflict Handling: The API validates material uniqueness within the plant scope of each sync request. If your payload contains the same materialNumber + plantId combination multiple times, the sync fails with the duplicate error you’re seeing. The conflict detection occurs at the API layer before database insertion, so the entire BOM batch is rejected - partial syncs don’t occur.

To handle conflicts gracefully, implement these API call patterns:

  1. Use the validation endpoint before actual sync:

POST /api/materials/bom/validate
{"bom": {...}, "plantId": "Plant-A"}

This returns conflict warnings without committing data, allowing you to fix duplicates before the real sync.

  1. Enable conflict resolution mode in the API request:

POST /api/materials/bom/sync?conflictMode=merge&plantContext=Plant-A

The ‘merge’ mode updates existing materials instead of failing on duplicates. Use this when plant-specific material attributes may have changed in PLM.

Integration Validation: Implement pre-sync validation in your integration layer to catch issues before API calls:

// Pseudocode - BOM validation before sync:
1. Parse incoming BOM from PLM system
2. Extract all material numbers and build Set per plantId
3. Check for duplicates within same plant context
4. If duplicates found, determine merge strategy (use latest revision, flag for manual review, etc.)
5. Enrich BOM payload with plantId on every material reference
6. Call validation API endpoint to verify payload structure
7. If validation passes, execute actual BOM sync API call
// Log all conflicts and resolutions for audit trail

For your specific scenario with plant-specific variants of the same material number, ensure your PLM-to-Opcenter mapping includes:

  • Material number (from PLM)
  • Plant code (from PLM site/location data)
  • Plant-specific attributes (description, specifications, etc.)

The API will create separate material master records for MAT-12345 in Plant-A and MAT-12345 in Plant-B, treating them as distinct materials even though they share the same number.

If you need to sync cross-plant BOMs (where a Plant-A assembly uses Plant-B components), use the plantId attribute on individual material references to specify source plant for each component. The BOM header plantId indicates where the assembly is manufactured, while component plantId values indicate material sourcing plants.