Sap Fleet Connector

SAP Fleet Connector

Binds a customer's landed SAP data (Plant Maintenance / EAM, Sales & Distribution deliveries, optionally Transportation Management) plus their fleet telematics into the existing neutral FLEET_APP contract. Because every consumer (the 13 SA-app views, the Cortex agent, and SV_FLEET_OPS) reads the contract and never a physical source, swapping the source from synthetic data to SAP lights up the whole accelerator with zero edits above the contract.

This is a semantic-binding skill, not an ingestion connector. SAP and telematics are assumed already in Snowflake (Fivetran / SLT-ODP / Datasphere / Qlik Replicate). The skill maps the landed tables to the contract, it does not extract from SAP.

Co-location first (Step 0). Discovery shows SAP and telematics almost always land in SEPARATE Snowflake accounts, with effectively no in-Snowflake join today (any existing SAP<->telematics co-joins are a tiny, exploratory fraction). Before binding, the two sources must be co-located into ONE queryable account via a data share or replication. The connector treats this as Step 0; the crosswalk and binding assume both sources are reachable from the account where FLEET_APP lives.

Scope

• IN: co-locate SAP + telematics into one account (data share / replication); discover landed SAP + telematics; build the ASSET_CROSSWALK and normalize_serial; dedupe CDC tables to current rows; emit SAP source views shaped to the contract; repoint the FLEET_APP.UNIFIED_FLEET seam; an install-time join self-check.
• OUT (later phases): predictive-maintenance dashboards over the new fact_maintenance entity (Phase 3); write-back to SAP notifications/orders + delivery ETA (Phase 4); marine template for vessel fleets (Phase 5).
• NOT this skill: SAP->Snowflake ingestion, synthetic data generation, ORS engine provisioning.

Prerequisites

1. install-fleet-apps already deployed (provides FLEET_APP.CORE, FLEET_APP.UNIFIED_FLEET, FLEET_INTELLIGENCE.SEMANTIC.SV_FLEET_OPS, and the consumer roles).
2. SAP and telematics reachable from ONE account. They typically land in SEPARATE accounts, so co-locate first via a data share (preferred) or replication into the account where FLEET_APP lives. See references/colocation.md.
3. SAP landed: at minimum EQUI, IFLOT (EAM) and/or LIKP/LIPS (deliveries). For the maintenance pack: IMRG, AUFK, QMEL. (When SAP is finance-only - BSEG/EKKO, no EQUI - see the mapping spec.)
4. Telematics landed: a GPS fact with a device identifier, timestamp, lat, lon.
5. A sap-mapping.yaml filled in for the account (co-location source, object names, device key, CDC tool, join strategy). A default serial_direct block is provided.
6. A role with the privileges in Required Privileges (read on the co-located SAP + telematics shares/schemas, ownership of the SAP_SOURCE database and the FLEET_APP.UNIFIED_FLEET functions).

Configuration

Required Privileges

No ACCOUNTADMIN required. The seam repoint needs ownership of the UNIFIED_FLEET functions (granted to the deploying role by install-fleet-apps).

Workflow

1. Set the query tag (attribution):

   ALTER SESSION SET query_tag = '{"origin":"sf_sit-is-fleet","name":"oss-sap-fleet-connector","version":{"major":1,"minor":0},"attributes":{"is_quickstart":1,"source":"sql"}}';
   

2. Co-locate (Step 0): bring SAP and telematics into the account where FLEET_APP lives. SAP and telematics are typically in separate accounts with no join today, so set up the inbound data share(s) (preferred) or replication per references/colocation.md, then point sap-mapping.yaml colocation.* at the inbound DBs. Skip only if colocation.method: same_account.
3. Discover the landed SAP + telematics objects and their exposure form (raw / CDS / Datasphere): run scripts/introspect_sap.sql. Reconcile the output against sap-mapping.yaml.
   • From the app UI (no SQL): the fleet app's chat agent can run this discovery live via the introspect_sap verb. Ask, e.g., "Which SAP tables can I bind in MY_SAP_DB?" (or "scan MY_SAP_DB and MY_TELEMATICS_DB for bindable tables") and it returns the SAP fleet objects, the CDC-tool fingerprint, the telematics columns, and a suggested cdc.tool + join strategy. The verb wraps the read-only proc FLEET_INTELLIGENCE.ROUTING_TOOLS.TOOL_SAP_INTROSPECT(P_SAP_DB, P_TELEMATICS_DB) (EXECUTE AS OWNER, so the proc owner needs USAGE on the scanned databases). For a demo without real SAP data, use MOCK_SAP / MOCK_TELEMATICS: install-fleet-apps lands this mock landscape automatically (step 3.5, raw tables only, no bind), so on a fleet install it is already present - just ask the agent to scan MOCK_SAP / MOCK_TELEMATICS. For a standalone/SAP-skill-only account, run scripts/mock_sap_seed.sql first (it is the single source of truth the installer runs).
4. Build the crosswalk: run scripts/build_crosswalk.sql (creates SAP_SOURCE.FLEET.normalize_serial + ASSET_CROSSWALK per the chosen strategy).
5. Validate the join in-account: run scripts/overlap_selfcheck.sql. Confirm acceptable overlap % and tune normalization if low. This is informational, not a hard gate.
6. Emit SAP source views: run scripts/sap_source_views.sql (L1 current-row dedup -> L4 contract-shaped views in SAP_SOURCE.FLEET).
7. Bind the seam: run scripts/bind_sap_source.sql to repoint FLEET_APP.UNIFIED_FLEET.F_VW_*_SCOPED (and VW_*) at the SAP source, and register one always-live DIM_DATASETS row. FLEET_APP.CORE and SV_FLEET_OPS are untouched.
8. Verify non-invasiveness: confirm SV_FLEET_OPS and FLEET_APP.CORE.* definitions are unchanged, and that SELECT * FROM FLEET_APP.CORE.VW_FACT_JOURNEY LIMIT 10 now returns SAP rows. See references/binding.md.

See references/sap-entity-mapping.md for the column-level mapping, references/asset-crosswalk.md for the join seam, and references/cdc-dedup.md for the current-row layer.

Examples

• "Bind our SAP equipment + telematics to the fleet app" -> run Steps 0-7 with the serial_direct profile; the dashboards/agent light up on SAP data.
• "Our telematics only has a device/message id, not a serial" -> use the device_vin_bridge profile (2-hop device -> VIN -> EQUI.SERNR).
• "SAP only has finance data, no equipment master" -> use the vin_external profile; assets come from an external master, SAP joins only at the cost layer.

Stopping points

• After Step 0 (co-location): confirm SAP + telematics are both queryable from the FLEET_APP account before continuing.
• After Step 4 (overlap self-check): if match % is low, stop and tune normalize_serial / the crosswalk strategy before emitting source views.
• After Step 7 (bind): verify SV_FLEET_OPS is unchanged and the contract returns SAP rows.

Error Logging

When any step fails (missing SAP/telematics objects, low join overlap, a seam repoint error, or a contract view returning zero rows), log it to logs/ per logs/README.md (sap-fleet-connector_{YYYY-MM-DD}_{HH-MM}.md). Continue where possible, recording each issue. Common cases: co-location not done (Step 0 skipped); wrong cdc.tool so dedup returns duplicates; normalize_serial mismatch so the crosswalk is empty; missing ownership of the FLEET_APP.UNIFIED_FLEET functions so the bind cannot CREATE OR REPLACE.

Cleanup

-- 1. Restore the synthetic seam (re-run the install-fleet-apps unified_fleet pack), then:
-- 2. Drop the SAP source artifacts.
DROP DATABASE IF EXISTS SAP_SOURCE;
-- 3. Remove the always-live SAP dataset row.
DELETE FROM FLEET_INTELLIGENCE.CORE.DIM_DATASETS WHERE NOTES = 'sap-fleet-connector';

Re-running install-fleet-apps's packs/fleet/unified_fleet/setup.sql repoints the seam back to SYNTHETIC_DATASETS.UNIFIED.V_*_CURRENT, fully reverting the bind.

References

• references/colocation.md - Step 0: co-locate SAP + telematics into one account
• references/sap-entity-mapping.md - column-level SAP -> contract mapping
• references/asset-crosswalk.md - telematics<->SAP join seam + normalize_serial
• references/cdc-dedup.md - current-row layer per replication tool
• references/binding.md - how the seam is repointed; non-invasiveness proof
• references/conventions.md - tracking-tag formats