Apex Universal Sync Orchestrator

Overview

Normalizes external application JSON payloads into APEX-OmniHub state vectors, enabling reliable OmniBoard integration pipeline onboarding. OmniBoard is a dual-surface system; this skill targets its application integration layer only and does not handle the separate OmniBoard client-facing conversational modal surface.

Input / Output / Success / Fails-when

Input: External app JSON payload (source_system, sync_timestamp, data_payload) and a mapping schema JSON file containing a field_mappings dict.

Output: Normalized state vector JSON with omni_id, typed fields, and meta.fields_mapped count written to stdout; exit 0 on success.

Success: All required payload fields present, all mappings applied without violation, omni_id generated deterministically, output is valid JSON.

Fails-when: field_mappings key missing or not a dict in schema; required payload fields (source_system, sync_timestamp, data_payload) absent; non-optional mapped source fields not found in data_payload.

Workflow Decision Tree

1. Load schema JSON
   ├── SCHEMA ERROR: field_mappings missing or not dict → exit 1
   └── OK → continue

2. Load payload JSON
   ├── PAYLOAD ERROR: source_system missing → exit 1
   ├── PAYLOAD ERROR: sync_timestamp missing → exit 1
   ├── PAYLOAD ERROR: data_payload missing → exit 1
   └── OK → continue

3. data_payload empty?
   ├── Yes → warn to stderr ("WARNING: data_payload is empty"), continue
   └── No → apply field mappings

4. For each field mapping:
   ├── source_field present → apply type coercion (string/integer/float/boolean)
   ├── source_field absent + optional → use schema default value
   └── source_field absent + required → collect violation

5. Violations collected?
   ├── Yes → print all violations, exit 1
   └── No → generate omni_id, write JSON to stdout, exit 0

Verification Command

python3 scripts/sync_payload.py <input_json_path> <mapping_schema_path>
echo "EXIT CODE: $?"

Exit 0 = success (JSON on stdout). Exit 1 = violations or errors printed to stdout.

Failure Handling

• Empty data_payload: Emits WARNING: data_payload is empty to stderr, continues execution — an empty payload is a valid initial state for a new integration.
• Optional missing field: Uses the default value from schema (may be null).
• Required missing field: Collects FIELD_NAME: required field missing from data_payload; all violations are reported before exit 1 — no early termination.

References

See references/payload-mapping-schema.md for: required payload fields, field_mappings structure, supported type coercions, optional field behavior, omni_id generation rules.