Genealogy tracking API fails to create parent-child links after batch serial import

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

After importing serialized items via the genealogy API in batch mode, parent-child relationships are not being established correctly. We’re importing 500+ serialized components and their assemblies, but the traceability links are missing in about 30% of cases.

The API returns 200 OK for all imports, but when we query the genealogy tree, many child components show no parent assembly link. This breaks our compliance traceability requirements.


POST /api/genealogy/items/batch
{"items": [{"serial": "SN001", "parent": "ASM-100"}, ...]}
Response: 200 OK, but links missing

Is there a specific payload structure or timing requirement for establishing parent-child relationships during batch imports?

2

The solution involves three key aspects of proper genealogy API usage:

API Payload Structure: Never mix parent and child creation in a single batch. The genealogy API payload must separate hierarchical levels. Structure your imports as:

Phase 1 - Parent/Assembly creation:


POST /api/genealogy/items/batch
{"items": [{"serial": "ASM-100", "type": "assembly", "material": "MAT-500"}]}

Phase 2 - Child/Component creation with parent links:


POST /api/genealogy/items/batch
{"items": [{"serial": "SN001", "type": "component", "parentSerial": "ASM-100", "position": "1"}]}

Parent-Child Relationship Requirements: The genealogy module validates parent existence before establishing links. This validation occurs at the database constraint level, so parent records must be fully committed and visible to subsequent transactions. In SOC 4.1, batch operations execute in a single transaction context, meaning child items processed in the same batch cannot reference parents created earlier in that same batch - they see the pre-transaction database state.

Traceability Compliance Best Practices: For regulatory compliance, implement verification after each import phase:

// Pseudocode - Two-phase genealogy import:
1. Extract all parent/assembly items from source data
2. POST parents batch to genealogy API, await 201 response
3. Query genealogy API to verify all parents exist (GET /api/genealogy/items?serials=...)
4. Extract child/component items from source data
5. Enrich child payload with validated parentSerial references
6. POST children batch to genealogy API
7. Verify parent-child links via genealogy tree query
// Log any missing links for compliance audit trail

Additionally, enable genealogy API response logging to capture any silent validation failures. The 200 OK response you’re seeing likely contains warning messages in the response body about failed link creation - check the “warnings” array in the JSON response.

For high-volume imports (500+ items), consider implementing micro-batches of 50-100 items per API call within each phase. This improves transaction performance and makes error isolation easier when links fail.

If you’re in a clustered deployment, add a 2-3 second delay between Phase 1 and Phase 2 to allow database replication lag. Some installations have asynchronous replication between nodes, and immediate queries after parent creation may not see newly committed records on replica nodes.

3

Yes, absolutely split them. The genealogy module processes batch items sequentially within the transaction, but parent validation happens before child linking. If a parent hasn’t been committed to the database yet, the child link creation fails silently. Always import parents first, wait for transaction commit, then import children with parent references.

4

We encountered this exact issue in 4.1. The problem is transaction isolation level. Even within the same batch, child items can’t see uncommitted parent records. Split your imports into two phases with explicit transaction boundaries between them.

5

That makes sense. So phase 1 creates all assemblies/parents, phase 2 creates components with parent links after first batch commits?

6

Are you creating parent items before children in the same batch? The genealogy API requires parent records to exist before establishing links. If you’re trying to create both simultaneously, that could cause the missing relationships.