Manage Territory Geographies
Purpose
Prepare new territory geography hierarchies and hand them to
Data Loader as CX Import data for
GeoTerritoryInterface. The task's catalog flags prohibit FSM setup imports;
they do not prohibit the separate CX Import route.
Execution ownership
Core Data Loader is the sole upload and initiation route. Follow its current
SKILL.md and user-friendly output contract; do not use SOAP staging, direct
Import Activities submission, task-local transport callbacks, or a custom
cxUploadContract profile. The former task-local upload/report commands and
finalize-preview are retired and fail before any external action.
The pillar accepts new-record intent only. Do not promise server-enforced
CREATE_ONLY: the native Data Loader contract does not expose that setting.
If the request requires a server-enforced create-only mode, stop with a contract
gap before approval. Never inject ImportMode, Activate, Schedule, or a
server-issued content reference into the native initiation payload.
Prepare source
Read input validation and use the local helper. It writes CSV, local validation, and a non-authorizing Data Loader handoff, without generating an import payload or approval.
python3 pillars/cx/sales/territories/manage-territory-geographies/scripts/territory_geography_import.py prepare \
--records-json <rows.json> \
--output-dir project/{project_id}/artifacts/pillars/cx/sales/territories/manage-territory-geographies/current/
Use --input-csv instead for an existing CSV; template --output <file.csv>
creates a header-only template. Existing artifacts require explicit overwrite
approval. prepare --dry-run validates without writing files.
The eleven-column base contract, optionally followed by GeoParentName5, is:
GeographyOrZoneName,LanguageCode,SourceId,ParentSourceId,GeographyOrZoneType,ZoneCode,CountryName,GeoParentName1,GeoParentName2,GeoParentName3,GeoParentName4
Accept a JSON array or records array. Preserve names, language codes, numeric
identifier text, postal codes, and geography-parent paths. Require one first-row
root, unique unsigned Oracle Long SourceIds, and parents earlier in the file.
Country structures and master geography paths remain target prerequisites;
do not invent an exact-match check against geoZones.
Data Loader and Task Hook sequence
- Resolve the active project/Run Book and explicit environment through the implementation router. Read Data Loader and Task Hook. A pending, failed, or unknown Run Book blocks submission.
- Invoke ordinary CX preflight with the prepared CSV. Use the selected OAuth properties and Run Book configuration, rather than changing another environment's configuration. Core obtains live CX metadata and persists the immutable archive and preflight. Do not ask for approval yet.
python3 core/data-loader/scripts/upload_and_initiate.py <prepared.csv> \
--cx-import --cx-import-object-code GeoTerritoryInterface --task-routed \
--properties <selected-properties> --run-config <selected-run-config> \
--preflight-envelope-output <internal-preflight.json>
- Require
taskRouted=true,mappingComplete=true,sourceType=ORA_CX_IMPORT, the exact object code, matching environment/Run Book, and an artifact digest matching the persisted archive. Immediately run Task Hook:
python3 core/data-loader/task-hook/scripts/task_hook.py data-load \
--task-context <task-context.json> \
--task-name "Manage Territory Geographies" --sequence <task-sequence>
- Read its returned execution guide, registry, and reachable resources,
including error handling. Evaluate the
non-write rules against the exact final archive and preflight, including the
declared metadata GET. Registry
readymeans executable rules, not completed validation. Resolve the UCM account from live target metadata and require it to match core preflight; do not hardcode an account name. Record ordered evidence; block on any unresolved finding. - Call
build-data-load-preview --input-stdinwithtaskContextPath,taskName,sequence,finalDatacontaining the finalarchiveSha256, and orderedruleResults. The registry's readiness gate checks validation and integrity, not prior approval: approval follows preview creation. - Return the normal Data Loader approval-required report only after all rules
pass. A later contextual affirmative, or unambiguous same-request
auto-approval wording accepted by core, authorizes that exact load. Then call
approve-data-load-preview --input-stdin, followed byverify-approved-data-load-archive --input-stdin --archive <final-archive>. Persist its returnedtaskValidationEnvelopeunchanged. Never reconstruct it. - Submit through the native approved-preflight path only:
python3 core/data-loader/scripts/upload_and_initiate.py \
--approved-preflight-envelope <internal-preflight.json> \
--task-validation-envelope <verified-task-envelope.json> --approve-upload \
--properties <selected-properties> --run-config <selected-run-config>
Core reuses the immutable artifact, uploads its CSV members through Documents,
and invokes initiateDataLoad with sourceType=ORA_CX_IMPORT and
cxImportObjectName=GeoTerritoryInterface. It owns reference propagation and
optional Run Book parameters. Do not refresh metadata, rebuild files, or rerun
rules after approval. Pass --cx-import-high-volume-load during preflight only
when the user explicitly requested high-volume/bulk loading; it is not a default.
Result and recovery
Redact secrets, tokens, authorization codes, protected payloads, and raw responses from project diagnostics as required by error handling.
Return the helper's complete Markdown report verbatim. Accepted initiation is
terminal for the submission request; it is not proof that all rows loaded.
Do not automatically poll, query errors, repair Import Activities, or retrieve
reports. On an explicit status/results request use core Data Loader's
get_data_load_info.py and its declared monitoring contract.
Keep uncertain or partial uploads/initiation blocked until reconciled under a supported workflow. Retain existing artifacts and checkpoints, including legacy SOAP checkpoints; never clear them, edit a preflight profile, or create another upload to bypass uncertainty. This correction does not provide a resume route for previously staged SOAP documents or authorize their resubmission.
Persist local pillar preparation and failed routing evidence under the declared project paths, record the durable skill run and token usage, and keep Data Loader internal envelopes private. Core owns its initiation report and cleanup; do not add auxiliary reports to its accepted-initiation response.
Source guidance
Use current Oracle Territory Geography import guidance and its CSV example for domain fields. Native Data Loader transport, approval, and completion rules are governed by core, rather than the separate Import Activities examples.