Manage Geographies Setup Task Guidance
Purpose
Define the geography country structure and import geography hierarchy master
data for one country from either Oracle-licensed Loqate data or creation-only
data gathered or supplied for the request. Accept a simple Loqate request such
as "Set up geographies for India," or a request containing an ordered structure,
a hierarchy tree/table, compatible CSV files, or a request to prepare the
reusable Country Structure and Geography import mappings. Preserve the existing
Loqate workflow. Route every live geography mutation through core.data-loader
and its Task Hook. Gather and validate the business data, resolve every technical
prerequisite internally, show one concise business preview, and after the user
approves it invoke the existing ESS service, mapping-only REST service, or
native Data Loader helper without adding task-local authentication or transport.
Delegated Execution Boundary
This skill owns Manage Geographies business rules, geography-data transformation, local preconditions and postconditions, and task-local outcome transitions. It delegates authentication, transport, upload, submission, polling, retry, artifact persistence, and cross-task workflow coordination to the declared core services and the active implementation workflow. References to core command modes, request paths, headers, checkpoint fields, or adapters identify the task-specific values required by those contracts; they do not create task-local technical implementations. The task registry represents only the local rules and outcomes required to complete this setup task.
Setup Task Skill Contract
- task_code:
HZ_MANAGE_GEOGRAPHIES - task_name:
Manage Geographies - parent_skill_id:
cx.customer-data-management.enterprise-profile - pillar:
CX - offering:
Customer Data Management - functional_area:
Enterprise Profile - functional_area_code:
ORA_ASK_ENTERPRISE_PROFILE - available_flag:
Y - export_import_supported_flag:
N - csv_export_import_supported_flag:
N - source_catalog:
knowledge/setup-task-catalog/effective/setupTasksAll.json
Usage
Use this skill when planning, validating, or executing Manage Geographies
under Enterprise Profile, including custom or third-party creation-only
country structures, geography hierarchy master data, and their reusable Fusion
Import Management mappings.
Setup Task Metadata
- Task name:
Manage Geographies - Task code:
HZ_MANAGE_GEOGRAPHIES - Available:
Y - Export/import supported:
N - CSV export/import supported:
N - FSM CSV export/import routing:
not supported - Data Loader import mode:
CXIMPORT - User-provided CSV routing:
core/data-loader/scripts/upload_and_initiate.pywith--cx-import; this does not change the catalog flags above
Inputs
country: one country name or two-letter country code; Loqate requests must resolve against the Loqate-supported list, while user-provided structure requests use the explicit or locally resolved ISO two-letter country codegeography_source: internally resolveoracle_loqateoruser_provided; select Loqate for a standard supported-country setup request with no custom hierarchy, and select user-provided when custom structure/hierarchy data is supplied, requested, or gathered for a named hierarchyexecution_phase: foruser_provided,mapping_onlyorfull_import; default tofull_importwhen the request includes geography data and tomapping_onlyonly when the user explicitly asks to prepare or register the reusable mappingsrequested_scope: for user-provided data,structure_only,hierarchy_only, orstructure_and_hierarchy; duringmapping_only, this selects which stable mapping definition or definitions to preparestructure_definition_or_csv: ordered geography levels or a local CSV withCountryCode,LevelNumber,GeographyType; required when scope includes structurehierarchy_definition_or_csv: hierarchy tree/table or a local Geography import CSV; required when scope includes hierarchyfusion_environment_context: optional when exactly one active configured Fusion environment can be resolved; otherwise require the target environmentproject_id: required for live execution so the submission checkpoint and request ID survive an interrupted command-output sessionexecution_options: optionalwait_secondsandpoll_intervalfor Loqate; native CX status is requested separately and is never polled after initiationtask_contextandtask_sequence: required Task Hook inputs for a live Data Loader routeexecution_intent: inferred from the user's request; any initial imperative authorizes validation and immutable preview generation only
country, structure_definition_or_csv, and hierarchy_definition_or_csv
are not required for mapping_only. The target environment, project_id,
requested scope, exact mapping preview, execution intent, and Data Loader Task
Hook approval remain mandatory because creating an import mapping changes
Fusion configuration.
The user never supplies an import-file account, object metadata result, mapping number, adapter, REST path, or technical payload. Native full_import returns Data Loader's required account and identifier fields in its preview and result. Resolve those values internally, retain them only in redacted durable audit artifacts, and omit extra technical payload details from normal previews and failures. Expose additional raw technical details only when the user requests them.
The user also never supplies or overrides import-mapping names, object codes,
or column pairs. Load those reviewed values from
the task-owned mapping definitions.
Run the mandatory core.data-loader validation, immutable-preview, and approval
gates. After authorization, invoke native Data Loader for full_import or the
authorized REST core service for mapping_only; do not implement task-local Fusion REST or file-staging transport.
Outputs
For full_import also return cx_mapping_csvs, data_loader_preflight_envelopes,
data_loader_initiation_result, and pending_geography_stage. Legacy mapping
IDs and import-activity results below belong to mapping_only or historical runs.
country_resolutionsource_resolutiongeography_request_modelgeography_file_validationgeography_structure_csvgeography_hierarchy_csvimmutable_data_loader_artifactdata_loader_task_validation_envelopestructure_import_mapping_previewhierarchy_import_mapping_previewstructure_import_mapping_resulthierarchy_import_mapping_resultdata_loader_import_authorizationstructure_import_previewhierarchy_import_previewstructure_ucm_upload_resulthierarchy_ucm_upload_resultstructure_import_resulthierarchy_import_resultucm_account_resolutionprofile_preflight_resultprofile_change_planprofile_change_resultinternal_execution_planess_submission_checkpointapproved_ess_submission: the validated ESS delegation envelope, created only after Task Hook approval and artifact verificationess_recovery_resultess_execution_resultgeography_setup_resultnext_country_promptdiagnosticsskill_run_recordtoken_usage_record
Read Order
- Read input intake.
- Read input validation.
- Read reference lookups.
- Read defaulting rules.
- Read dependency readiness.
- Read bulk behavior.
- Read design advisory.
- Read design enforcement.
- Before payload construction, internal request validation, or live execution, read REST and ESS execution and error handling.
- For user-provided mapping preparation or import, read the task-owned mapping definitions.
- Use the compiled task registry as the task-local execution graph.
Execution Discipline
- Accept exactly one country and one source mode per run. Infer the source from the requested business outcome: standard country setup uses Loqate; a named custom structure or hierarchy uses user-provided data. Do not ask the user to choose an implementation route.
- Start or refresh the configured Fusion authentication flow automatically when needed. Do not ask the user for permission to authenticate and never ask them to provide credentials or tokens in chat.
- For
oracle_loqate, usecore.fusion-api.apps-commonfor configured site-level profile-value reads and any explicitly approved writes. Do not add OAuth or REST transport logic to this skill. - Apply the Loqate profile, supported-country, and ESS rules below only to the
oracle_loqatebranch. User-provided data must not read or mutate the two Loqate profile options and must not submit the Loqate ESS job. - For
oracle_loqate, requireORA_HZ_ENABLE_DAAS_LOQATE=Y. RequireORA_HZ_DAAS_GEO_ENDPOINTto contain any non-null, non-empty value after trimming; do not require a specific endpoint URL. - When both profiles already satisfy those conditions, report them as validated and continue immediately. Do not write either profile and do not ask for profile-change confirmation.
- If
ORA_HZ_ENABLE_DAAS_LOQATEis missing or is notY, the single geography execution preview must explicitly ask whether the user wants to use Loqate as the source for geography data. Explain that doing so requires settingORA_HZ_ENABLE_DAAS_LOQATEtoY, and show the profile option's safe current state and proposed value. Use one combined Loqate-and-submission question; do not ask separate profile and submission questions. - If
ORA_HZ_DAAS_GEO_ENDPOINTis missing or blank, ask the user to configure its site-level value and stop before import. Do not propose a default URL or write this profile option. On a later run, re-read and verify it before continuing. After approval for an eligibleORA_HZ_ENABLE_DAAS_LOQATEchange, create or update only that profile and re-read both profiles. - Stop before internal request validation when the country, post-change profile verification, or environment gates fail.
- Build and validate the exact request internally, resolve read-only technical prerequisites, create the immutable artifact, and render one business-only Data Loader preview. An initial imperative never authorizes the first POST.
- After standalone approval of the current immutable preview, apply any
included prerequisite remediation and then use
core.fusion-api.ess-job-submitterin two phases: submit with--submit-onlyand a durable--outputcheckpoint, then track with--request-id. Do not combine submission and long polling in one process. - Before submission, persist a unique correlation description and the exact
submission window. After submission, read the durable checkpoint, require
its
requestId, persist that ID, and report it before starting polling. - Submit once. Never automatically retry or replace an uncertain request.
If command output is interrupted, inspect the checkpoint first and use the
read-only recovery query through
core.fusion-api.rest-api-clientonly when the checkpoint is missing or unreadable. - Treat a polling timeout as nonterminal and resume the same
requestId. - Report prerequisite readiness in business language, geography structure and
hierarchy status, and the ESS job ID (
requestId). Always showORA_HZ_ENABLE_DAAS_LOQATEand proposed valueYwhen asking whether the user wants Loqate to supply the geography data; keep the DaaS endpoint value out of every user-facing response and redacted diagnostic. Keep mappings, metadata, and file-staging details internal unless explicitly requested. - Ask a concise clarifying question only when a missing country or genuinely ambiguous target environment changes the business outcome. Never ask about source mode, mappings, import accounts, object metadata, adapters, payloads, or transport.
- Tell the user whenever a lookup, profile mutation or verification, ESS submission, polling request, or ESS process fails. Include the failed business stage, safe error summary, known job ID, and recommended next step.
- Persist only redacted project outputs and token-usage records.
- After terminal success, ask whether the user wants to set up geographies for another country. If the user supplies another country, treat it as a fresh one-country run: resolve it, repeat all reads and gates, and submit a separate job only when that run is authorized. Never turn this into a multi-country batch.
- If the terminal ESS error unambiguously states that geography data for the selected country already exists or was already imported, report that fact plainly and ask whether to set up another country, using the same prompt and fresh-run behavior as terminal success. Do not retry, claim a new import, or present generic troubleshooting for this known condition.
- For
user_provided, resolveexecution_phasefirst.mapping_onlyretains the reviewed REST mapping-preparation route;full_importuses the native Data Loader CX Import route described below. - Load the reviewed mapping definitions and validate the complete one-country structure/hierarchy model before generating mapping and data CSVs.
- For full_import, invoke only
core.data-loader'supload_and_initiate.pyfor preflight and approved submission. Do not call the standalone CX adapter, ERP Integration upload, importMappings, or importActivities as a fallback. - Use one mapping CSV and its data CSV per stage. The mapping CSV's
IMPORT OBJECTis authoritative; do not also pass--cx-import-object-code. - Let Data Loader resolve the exact object's UCM account before approval and retain its normalized representation in the envelope. After approval, use only the saved envelope and artifact; never requery live metadata or rebuild sources. Return the Data Loader preview and result without hiding required Business Object Name, UCM Account, Content ID, or Request ID fields.
- Reject update, upsert, delete, replacement, and ambiguous identifier semantics locally. The helper has no ImportMode flag: do not invent a CREATE_ONLY option or claim that it sets that mode. If target support cannot establish the required additive behavior, stop before approval as a catalog mismatch.
- For structure_and_hierarchy, initiate structure first and stop with hierarchy pending. Only a user-requested status check may confirm successful structure completion and permit a separately validated and approved hierarchy load.
- Preserve partial successes and reconcile uncertain uploads or initiation; never replay a load from the status path.
Data Loader authorization lifecycle
Apply this lifecycle only to Loqate ESS submission and mapping_only REST mapping preparation. Full imports use the native Data Loader envelope lifecycle in the user-provided workflow below:
- For
oracle_loqate, complete the pillar-owned Loqate ESS preflight and delegation inora-resource/ora_rest_execution.md. This explicitly selected ESS route uses the existing Task Hook validation and approval commands, with the Loqate preflight replacing their native file-import preflight prerequisite. This exception is limited to this pillar'soracle_loqatebranch; it does not change the shared Data Loader or Task Hook contracts for other operations. Formapping_only, retain the existing Data Loader authorization requirement; stop if that route cannot authorize the mapping operation. Build one deterministic immutable artifact under the project workspace. For Loqate, use JSON containing the exact environment, country, job identity, request payload, execution options, prerequisite change plan, correlation description, checkpoint path, and business effect. Formapping_only, use JSON or ZIP containing the exact mapping definitions and environment. Do not use this JSON/manifest archive for full_import: CX archives accept only mapping and data CSVs. Calculate the applicable artifact SHA-256. - Resolve the task with
core/data-loader/task-hook/scripts/task_hook.py data-loadusing the selectedtask_context, task name, and sequence. Read its execution guide and evaluate applicable registry nodes;readyalone is not completed validation. Stop if readiness or task-rule validation fails. - Run
build-data-load-preview --input-stdinwith the resolved task context, ordered rule results, the complete immutable request infinalData, andfinalData.archiveSha256. Render only the country, target environment, source description, structure levels, hierarchy row or node counts, creation-only boundary, execution order, and any prerequisite business change. Do not render hashes, archives, mapping definitions or IDs, object metadata, import-file accounts, adapters, REST paths, or payloads. End with exactly:Do you want to proceed with submitting the reviewed archive? - Treat only a standalone affirmative reply to the latest unchanged preview
as approval. Then run
approve-data-load-preview --input-stdinandverify-approved-data-load-archive --input-stdin --archive <artifact>. Persist the returnedtaskValidationEnvelopeandarchiveSha256receipt. - Immediately before every live core-service mutation, rerun
verify-approved-data-load-archiveagainst the receipt inputs and exact artifact, and require its SHA-256 to match the persisted receipt. Before a UCM upload, also require the CSV bytes to match exactly one same-named member of the approved ZIP. A changed country, environment, business data, scope, creation semantics, or artifact bytes invalidates approval. Server-issued mapping numbers, activity IDs, document IDs, and an internally revalidated adapter-specific account representation do not require another confirmation when they leave the approved business effect and artifact bytes unchanged.
Workflow
Select the geography source
Resolve geography_source before country-specific execution:
- Choose
oracle_loqatewhen the user explicitly requests Oracle-licensed or Loqate data, or asks for standard supported geography setup without supplying custom data. - Choose
user_providedwhen the user supplies or asks the agent to form a country structure, hierarchy, table, tree, or CSV from their own data. - When neither rule is conclusive, default a plain country-setup request to Loqate and a request naming custom levels or geographies to user-provided data. Stop only when the requested business outcome itself is contradictory; never ask the user to choose between internal source or transport routes.
The numbered workflow immediately below is the existing oracle_loqate path.
The creation-only user-data workflow follows it.
1. Resolve the Loqate country
Match the trimmed input case-insensitively against
ora-resource/ora_reference_lookups.md. Accept either the documented country
name or its two-letter code. Return the documented name and uppercase code.
Stop before Fusion calls when the input is blank, contains more than one country, is ambiguous, or is unsupported. When country is missing or ambiguous, ask the user for one supported country name or two-letter code. When it is unsupported, state that clearly, show close supported matches when available, and ask the user to select one rather than ending with an unexplained blocker.
2. Verify DaaS and Loqate prerequisites
Invoke core.fusion-api.apps-common to read the configured SITE value for each
exact profile option:
ORA_HZ_ENABLE_DAAS_LOQATEORA_HZ_DAAS_GEO_ENDPOINT
Use each profile's siteProfileOptionValues child collection under
profileOptions/{ProfileOptionName}, request ProfileOptionValue, and require
onlyData=true. Require exactly one SITE record for each code:
/fscmRestApi/resources/11.13.18.05/profileOptions/ORA_HZ_ENABLE_DAAS_LOQATE/child/siteProfileOptionValues
/fscmRestApi/resources/11.13.18.05/profileOptions/ORA_HZ_DAAS_GEO_ENDPOINT/child/siteProfileOptionValues
Trim both values. Compare Y case-insensitively. Treat any endpoint containing
at least one non-whitespace character as valid; do not compare it with a fixed
URL:
| Profile option | Expected SITE value |
|---|---|
ORA_HZ_ENABLE_DAAS_LOQATE |
Y |
ORA_HZ_DAAS_GEO_ENDPOINT |
Any non-null, non-empty value after trimming |
Record each profile validation internally. If the endpoint is missing or blank,
follow the configuration blocker below before preparing a change plan. If
Loqate enablement is missing or different and the endpoint is configured,
prepare a change plan for Loqate enablement only. If
ORA_HZ_ENABLE_DAAS_LOQATE is missing or not Y, show a line such as
Loqate enablement: ORA_HZ_ENABLE_DAAS_LOQATE is <current state>; proposed value: Y. This enables Oracle-licensed geography reference-data import for <country>. Do not hide or paraphrase this profile option. Keep the DaaS
endpoint value out of every user-facing response and redacted diagnostic,
including technical-detail requests. Keep REST details internal unless the
user explicitly requests them.
If both values already satisfy their required conditions, this is a pure
no-op profile path: do not call POST or PATCH, do not ask for confirmation,
and proceed to geography setup after reporting that both values were validated.
If ORA_HZ_DAAS_GEO_ENDPOINT is null, empty, whitespace-only, or has no SITE
record, tell the user that the site-level DaaS geography endpoint must be
configured in Fusion before a Loqate import can run. Ask them to configure
ORA_HZ_DAAS_GEO_ENDPOINT, then stop without changing either profile or
submitting the job. Do not propose a URL or accept a chat value as a substitute
for the configured Fusion value. Re-read the profile when the user resumes.
Preserve every existing nonblank endpoint exactly; never mutate this option.
After the single geography execution confirmation, use
core.fusion-api.apps-common to POST a missing
SITE record or PATCH an existing eligible ORA_HZ_ENABLE_DAAS_LOQATE item.
Never write ORA_HZ_DAAS_GEO_ENDPOINT. Before writing,
require the profile's site level to be enabled and updatable and require the
profile-value management privilege. Never retry a profile mutation
automatically. Read both profiles again after all approved writes and continue only when
ORA_HZ_ENABLE_DAAS_LOQATE is Y and ORA_HZ_DAAS_GEO_ENDPOINT is nonblank.
Retain each applied technical change in the audit record and summarize it to the
user only as prerequisite setup. If the user declines the single execution
preview, make no profile changes and do not submit the Loqate geography job.
Explain that the user can open Setup and
Maintenance > Customer Data Management > Enterprise Profile > Manage
Geographies to define the country structure and master geography hierarchy
manually, then leave the next action to the user.
3. Validate the environment
Resolve the target Fusion environment before any side effect. When exactly one
active configured environment is available, use it without asking the user to
repeat it and name it in the brief progress update. Ask one short question only
when the environment is missing or ambiguous, naming the available choices when
safe. Do not perform a separate role or ESS-access preflight check. If Fusion
rejects the authorized ESS submission, classify and report the response as
authorization_or_privilege without retrying.
4. Prepare the execution internally
Build and validate the fixed ESS request described in
ora-resource/ora_rest_execution.md. Do not show the REST path, payload, job
definition, application, parameter names, CLI command, or polling mechanics in
the normal user flow.
Require a live-run project_id. Before the ESS POST, create and persist a
unique correlation description using the resolved project, country code, and
run ID. Record the UTC submission-window start. Reserve these task-local paths:
project/{project_id}/artifacts/pillars/cx/customer-data-management/enterprise-profile/manage-geographies/current/ess-submission-checkpoint.json
project/{project_id}/artifacts/pillars/cx/customer-data-management/enterprise-profile/manage-geographies/current/ess-execution-result.json
The checkpoint path must be passed to the core ESS process as --output; it is
the durable handoff between submission and polling.
Give the user an explanatory business-level update, such as:
Prerequisite validation is complete for India in the selected Fusion environment. I am now submitting Oracle's Import Geography Data process. It will define the country geography structure and load the Loqate hierarchy master data; it does not configure geocoding or address cleansing.
Do not suppress the two profile validation results, profile changes, geography structure and hierarchy status, or job ID. Reveal other technical request details only when the user explicitly asks for a preview, payload, API, ESS job, troubleshooting details, or audit evidence.
5. Build and approve the immutable execution preview
A direct imperative request such as "Set up geographies for India" or "Import
geographies for IN" authorizes validation and preview only. Gather the data,
complete all read-only prerequisite checks, and build the deterministic request
artifact before interrupting the user. Show one concise business preview with
the country, target environment, source, geography scope, creation-only effect,
and any prerequisite business change. When ORA_HZ_ENABLE_DAAS_LOQATE is
missing or not Y, end with exactly: Do you want to use Loqate as the source for geography data? If so, we need to enable ORA_HZ_ENABLE_DAAS_LOQATE by setting it to Y. Do you want to proceed with enabling it and submitting the reviewed archive? Otherwise, ask the standard reviewed-archive
question once. A standalone affirmative reply authorizes the complete previewed
sequence, including eligible prerequisite remediation and one submission;
never ask a second profile, mapping, upload, or submission question.
If the request is advisory, hypothetical, ambiguous about whether to execute, or does not resolve to one target environment, stop before submission. Ask at most one short business-level question, without showing technical details.
6. Submit and monitor
Invoke the existing ESS skill using the fixed two-phase contract in
ora-resource/ora_rest_execution.md:
- Verify the Task Hook receipt and artifact immediately before invocation,
then validate the ESS
approved_submissiondelegation contract described in that resource. Map only its approved request payload and execution options into the existing ESS adapter. Submit with--submit-onlyand the durable checkpoint path supplied through--output. - If the process returns a session handle instead of a terminal result, retain and poll that same process handle until it exits. Do not treat an empty first output chunk as an empty ESS response.
- Read the checkpoint file and require a positive integer
execution_result.requestId. Persist and report that ID immediately. - Start a separate tracking invocation using only
--request-id <captured-id>, the polling options, and the durable execution-result path.
Separating submission from polling prevents a polling authentication refresh, transport interruption, or output-session handoff from replaying the ESS POST.
Use default wait_seconds=300 and poll_interval=10 unless the caller supplies
valid positive values. Larger-country imports can take several hours.
If polling times out, tell the user that setup is still running. Retain the
requestId, last status, elapsed wait, and resume instructions internally.
Resume through the ESS skill's existing request-tracking path; do not submit a
second request. Always show the requestId as the job ID; show the remaining
mechanics only when the user asks.
If submission output is interrupted, inspect the checkpoint before doing
anything else. When it contains a request ID, continue tracking that request.
When it is missing or unreadable, do not submit again. Run the task-local
read-only recovery query using the exact correlation description, application,
job definition, submission window, and country parameter. Continue only when
exactly one matching request is found; zero or multiple matches are an
approval_blocker requiring manual reconciliation.
7. Report the outcome and offer another country
On terminal success, give an explanatory business-level confirmation naming the country and environment. Describe what was checked and why, list both profile validation results and any changes, identify the job ID, and report these outcomes:
Define Geography Country Structure: completedDefine Geography Hierarchy Master Data: completed
Do not claim that geocoding or address cleansing was configured. Oracle's
post-import UI verification is the Structure Defined and Hierarchy Defined
indicators for the selected country.
Use a result format with this level of explanation:
Geography setup completed successfully for
<country>in<environment>.Prerequisite validation
ORA_HZ_ENABLE_DAAS_LOQATE:<validated value and whether it was already set or changed>— this enables Oracle's Loqate geography import.ORA_HZ_DAAS_GEO_ENDPOINT: validated as configured; its value is omitted from the result.Import result
- Job ID:
<requestId>- Define Geography Country Structure: completed. The country now has the structural geography levels used by master geographies.
- Define Geography Hierarchy Master Data: completed. The supported Loqate geography hierarchy was loaded for the country.
This run did not configure geocoding or address cleansing; those are separate setup activities. In Manage Geographies,
Structure DefinedandHierarchy Definedshould now be selected for the country.
End every terminal success response with:
Do you want to set up geographies for another country? If yes, provide one supported country name or two-letter country code.
When the user supplies a country, start a fresh run for that one country. Reuse the already resolved environment only when it remains unambiguous, but always repeat the country support check and both profile reads. Do not assume that the previous job authorizes another submission. The new country reply is a direct setup instruction for one new run; persist a new run ID, correlation description, checkpoint, and job ID. Continue offering another country after each successful run until the user declines or stops.
If the ESS process ends unsuccessfully but its safe error message, status description, or process log unambiguously says that the selected country's geography data already exists or was already imported, handle it as an informational already-present outcome instead of a generic failure. Say:
Geography data for
<country>is already present in<environment>; Oracle reports that it was previously imported, so no new geography import was performed. Job ID:<requestId>.Do you want to set up geographies for another country? If yes, provide one supported country name or two-letter country code.
Do not claim that this run created or changed the country structure or hierarchy. Do not recommend retrying the same country. Preserve the original terminal status and safe diagnostic in project artifacts, but allow a supplied next country to start the same fresh one-country flow used after success. Apply this special handling only when the existing/already-imported condition is unambiguous; otherwise follow the normal terminal-failure behavior below.
On terminal failure, state that geography setup did not complete, include the job ID when submission occurred, summarize profile changes already completed, identify the failed stage, provide a safe Fusion error summary, and give the recommended next step. Apply the same proactive disclosure when a country or profile lookup, profile write or verification, ESS submission, or polling call fails. Never return only an internal failure classification or silently stop. When recovery requires information only the user can provide, ask one focused follow-up question—for example, which environment to use, whether access has been restored, or whether they want to retry a read-only lookup. Do not ask for credentials, tokens, or other secrets in chat. Keep full status payloads, ECIDs, API paths, credentials, and other sensitive implementation details internal unless the user asks for technical or troubleshooting information. Require a new direct setup instruction before any new ESS submission.
User-provided creation-only workflow
Use this path only when geography_source=user_provided. It supports creating a
country structure, creating hierarchy geographies beneath an existing or newly
created structure, and adding explicitly requested alternate names or codes.
It does not update, delete, replace, or merge existing structures or geography
records.
0. Resolve the execution phase
Resolve exactly one execution_phase:
mapping_only: prepare the mapping or mappings selected byrequested_scope, then stop after reporting that reusable import preparation is ready. RetainMappingNumbervalues internally. Do not require country data, generate a CSV, upload to UCM, create an import activity, or poll a job.full_import: render the reviewed mapping definitions as mapping CSVs and pass each stage to native Data Loader preflight, approval, upload, and initiation. Stop after initiation; check status only when the user explicitly requests it.
A direct request to prepare or register mappings selects mapping_only. A
request containing geography rows or asking to create the hierarchy selects
full_import. Resolve this internally, show the resulting business operation
in the one preview, and require one standalone affirmative reply before a
mapping POST or import. Do not ask the user to choose a phase or mapping route.
1. Collect the requested scope and canonical model
Resolve exactly one requested_scope:
structure_onlyhierarchy_onlystructure_and_hierarchy
For mapping_only, use the scope only to select the structure mapping, the
hierarchy mapping, or both. Skip the remaining canonical country and file model
in this subsection.
Accept a local CSV, an ordered list/table, or a hierarchy tree. Normalize it to one internal model before forming files or payloads:
When the user asks the skill to create, source, or suggest the hierarchy, gather the requested geography names and codes from the current approved country reference source before preview. If the user requests a sample count such as four states, select that many valid entries deterministically in alphabetical order unless the request names them. Do not ask the user to prepare a CSV or supply technical import data. Retain source citations in the audit artifact and show the selected business names in the one confirmation preview. Never invent real geographies for a live import; if authoritative data cannot be resolved, stop with a business-data readiness message.
country:
code: AU
name: Australia
structure:
- level_number: 1
geography_type: COUNTRY
- level_number: 2
geography_type: STATE
hierarchy:
- source_id: "1"
parent_source_id: null
level_number: 1
geography_type: COUNTRY
primary_name: Australia
record_type_code: 0
- source_id: "2"
parent_source_id: "1"
level_number: 2
geography_type: STATE
primary_name: New State
record_type_code: 1
When Source IDs are not supplied, assign deterministic positive integer strings
within the generated file, starting at 1 for the country anchor and traversing
parents before children. Do not reuse a generated Source ID for two primary
geographies. An alternate identifier row intentionally reuses its primary
geography's Source ID and Parent Source ID.
For hierarchy_only, require either a validated description of the existing
country structure or a reliable read-only result showing its levels. Use that
structure only for validation and do not import it. If the existing structure
cannot be established, stop rather than infer it.
2. Validate the structure
The generated or supplied Country Structure data must use exactly these columns:
CountryCode,LevelNumber,GeographyType
Require all of the following:
- Every row has the same explicit or locally resolved ISO two-letter country code. Do not call Fusion to preflight the country for a structure import.
- Level 1 exists exactly once and has
GeographyType=COUNTRY. - Level numbers are positive, unique, contiguous, and ordered from 1 through the lowest requested level.
- Each geography type is nonblank and appears at only one level.
- Normalize display labels to the canonical import code shown in the preview
by trimming, uppercasing, and replacing internal spaces or hyphens with
underscores (for example,
Postal CodebecomesPOSTAL_CODE). Do not call Fusion metadata or lookup APIs to preflight geography types. - Use the creation-only import result as the authoritative target validation. If Fusion reports an invalid country/type or an existing country structure, preserve and report that diagnostic; do not delete, replace, retry, or append lower levels.
3. Validate the hierarchy
Use this canonical column order when generating a Geography import file:
GeographyIdentifierId,PrimaryGeographyCodeType,PrimaryGeographyName,RecordTypeCode,SourceId,StartDate,ParentGeographyType,CountryCode,EndDate,GeographyId,GeographyType,GeoDataProvider,IdentifierSubtype,IdentifierType,IdentifierValue,LanguageCode,LevelNumber,ParentSourceId,PrimaryGeographyCode
Require all of the following before side effects:
CountryCode,PrimaryGeographyName,RecordTypeCode,SourceId, andLevelNumberare present on every primary or anchor row. The country anchor has a blankParentSourceId; every lower primary row has one.- Exactly one level-1 country anchor uses
RecordTypeCode=0, has the resolved country name and code, and has no alternate identifier row. - A primary geography to create uses
RecordTypeCode=1. Its level exists in the validated structure, itsGeographyTypematches that level, and its parent is present earlier in the same file. - Every child includes the complete parent chain needed by Oracle's Geography
import.
ParentGeographyType, when supplied, matches the parent's type. - Source IDs are unique across primary and anchor rows. Each
RecordTypeCode=2alternate-name or alternate-code row is explicitly requested, is below country level, and reuses the exact Source ID, Parent Source ID, level, and primary geography name of one preceding primary row. IdentifierType,IdentifierSubtype, andIdentifierValueare supplied together for type-2 rows and use current target-pod lookup values. Reject an alternate name already known to identify another geography.- `Prim
…(truncated)