# Manage Geographies Setup Task Guidance

> Creates geography country structures and hierarchy master data for one country from either Oracle-licensed Loqate data or creation-only user-provided data under CX Customer Data Management Enterprise Profile.

- Skill: `oracle/manage-geographies-setup-task-guidance` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx get-skill add oracle/manage-geographies-setup-task-guidance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oracle/manage-geographies-setup-task-guidance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Oracle (https://skillmd.com/u/oracle)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/oracle/manage-geographies-setup-task-guidance

---


# 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.py`
  with `--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 code
- `geography_source`: internally resolve `oracle_loqate` or `user_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 hierarchy
- `execution_phase`: for `user_provided`, `mapping_only` or `full_import`;
  default to `full_import` when the request includes geography data and to
  `mapping_only` only when the user explicitly asks to prepare or register the
  reusable mappings
- `requested_scope`: for user-provided data, `structure_only`,
  `hierarchy_only`, or `structure_and_hierarchy`; during `mapping_only`, this
  selects which stable mapping definition or definitions to prepare
- `structure_definition_or_csv`: ordered geography levels or a local CSV with
  `CountryCode,LevelNumber,GeographyType`; required when scope includes structure
- `hierarchy_definition_or_csv`: hierarchy tree/table or a local Geography
  import CSV; required when scope includes hierarchy
- `fusion_environment_context`: optional when exactly one active configured
  Fusion environment can be resolved; otherwise require the target environment
- `project_id`: required for live execution so the submission checkpoint and
  request ID survive an interrupted command-output session
- `execution_options`: optional `wait_seconds` and `poll_interval` for Loqate;
  native CX status is requested separately and is never polled after initiation
- `task_context` and `task_sequence`: required Task Hook inputs for a live
  Data Loader route
- `execution_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](references/import-mapping-definitions.json).
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_resolution`
- `source_resolution`
- `geography_request_model`
- `geography_file_validation`
- `geography_structure_csv`
- `geography_hierarchy_csv`
- `immutable_data_loader_artifact`
- `data_loader_task_validation_envelope`
- `structure_import_mapping_preview`
- `hierarchy_import_mapping_preview`
- `structure_import_mapping_result`
- `hierarchy_import_mapping_result`
- `data_loader_import_authorization`
- `structure_import_preview`
- `hierarchy_import_preview`
- `structure_ucm_upload_result`
- `hierarchy_ucm_upload_result`
- `structure_import_result`
- `hierarchy_import_result`
- `ucm_account_resolution`
- `profile_preflight_result`
- `profile_change_plan`
- `profile_change_result`
- `internal_execution_plan`
- `ess_submission_checkpoint`
- `approved_ess_submission`: the validated ESS delegation envelope, created
  only after Task Hook approval and artifact verification
- `ess_recovery_result`
- `ess_execution_result`
- `geography_setup_result`
- `next_country_prompt`
- `diagnostics`
- `skill_run_record`
- `token_usage_record`

## Read Order

1. Read [input intake](ora-resource/ora_input_intake.md).
2. Read [input validation](ora-resource/ora_input_validation.md).
3. Read [reference lookups](ora-resource/ora_reference_lookups.md).
4. Read [defaulting rules](ora-resource/ora_defaulting_rules.md).
5. Read [dependency readiness](ora-resource/ora_dependency_readiness.md).
6. Read [bulk behavior](ora-resource/ora_bulk_intake.md).
7. Read [design advisory](ora-resource/ora_design_advisory.md).
8. Read [design enforcement](ora-resource/ora_design_enforcement.md).
9. Before payload construction, internal request validation, or live execution,
   read [REST and ESS execution](ora-resource/ora_rest_execution.md) and
   [error handling](ora-resource/ora_error_handling.md).
10. For user-provided mapping preparation or import, read
    [the task-owned mapping definitions](references/import-mapping-definitions.json).
11. Use [the compiled task registry](ora-resource/ora_rule_registry.json) as
    the task-local execution graph.

## Execution Discipline

1. 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.
2. 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.
3. For `oracle_loqate`, use `core.fusion-api.apps-common` for configured site-level profile-value
   reads and any explicitly approved writes. Do not add OAuth or REST transport
   logic to this skill.
4. Apply the Loqate profile, supported-country, and ESS rules below only to the
   `oracle_loqate` branch. User-provided data must not read or mutate the two
   Loqate profile options and must not submit the Loqate ESS job.
5. For `oracle_loqate`, require `ORA_HZ_ENABLE_DAAS_LOQATE` = `Y`. Require
   `ORA_HZ_DAAS_GEO_ENDPOINT` to contain any non-null, non-empty value after
   trimming; do not require a specific endpoint URL.
6. 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.
7. If `ORA_HZ_ENABLE_DAAS_LOQATE` is missing or is not `Y`, 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
   setting `ORA_HZ_ENABLE_DAAS_LOQATE` to `Y`, 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.
8. If `ORA_HZ_DAAS_GEO_ENDPOINT` is 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 eligible `ORA_HZ_ENABLE_DAAS_LOQATE`
   change, create or update only that profile and re-read both profiles.
9. Stop before internal request validation when the country, post-change
   profile verification, or environment gates fail.
10. 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.
11. After standalone approval of the current immutable preview, apply any
    included prerequisite remediation and then use
    `core.fusion-api.ess-job-submitter` in two phases: submit with
    `--submit-only` and a durable `--output` checkpoint, then track with
    `--request-id`. Do not combine submission and long polling in one process.
12. 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.
13. 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-client` only when
    the checkpoint is missing or unreadable.
14. Treat a polling timeout as nonterminal and resume the same `requestId`.
15. Report prerequisite readiness in business language, geography structure and
    hierarchy status, and the ESS job ID (`requestId`). Always show
    `ORA_HZ_ENABLE_DAAS_LOQATE` and proposed value `Y` when 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.
16. 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.
17. 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.
18. Persist only redacted project outputs and token-usage records.
19. 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.
20. 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.
21. For `user_provided`, resolve `execution_phase` first. `mapping_only`
    retains the reviewed REST mapping-preparation route; `full_import` uses
    the native Data Loader CX Import route described below.
22. Load the reviewed mapping definitions and validate the complete one-country
    structure/hierarchy model before generating mapping and data CSVs.
23. For full_import, invoke only `core.data-loader`'s `upload_and_initiate.py`
    for preflight and approved submission. Do not call the standalone CX adapter,
    ERP Integration upload, importMappings, or importActivities as a fallback.
24. Use one mapping CSV and its data CSV per stage. The mapping CSV's
    `IMPORT OBJECT` is authoritative; do not also pass `--cx-import-object-code`.
25. 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.
26. 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.
27. 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.
28. 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:

1. For `oracle_loqate`, complete the pillar-owned **Loqate ESS preflight and
   delegation** in `ora-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's `oracle_loqate` branch; it does not
   change the shared Data Loader or Task Hook contracts for other operations.
   For `mapping_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. For `mapping_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.
2. Resolve the task with `core/data-loader/task-hook/scripts/task_hook.py
   data-load` using the selected `task_context`, task name, and sequence. Read
   its execution guide and evaluate applicable registry nodes; `ready` alone
   is not completed validation. Stop if readiness or task-rule validation fails.
3. Run `build-data-load-preview --input-stdin` with the resolved task context,
   ordered rule results, the complete immutable request in `finalData`, and
   `finalData.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?`
4. Treat only a standalone affirmative reply to the latest unchanged preview
   as approval. Then run `approve-data-load-preview --input-stdin` and
   `verify-approved-data-load-archive --input-stdin --archive <artifact>`.
   Persist the returned `taskValidationEnvelope` and `archiveSha256` receipt.
5. Immediately before every live core-service mutation, rerun
   `verify-approved-data-load-archive` against 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_loqate` when the user explicitly requests Oracle-licensed or
  Loqate data, or asks for standard supported geography setup without supplying
  custom data.
- Choose `user_provided` when 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_LOQATE`
- `ORA_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:

```text
/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:

```text
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`:

1. Verify the Task Hook receipt and artifact immediately before invocation,
   then validate the ESS `approved_submission` delegation contract described
   in that resource. Map only its approved request payload and execution options
   into the existing ESS adapter. Submit with `--submit-only` and the durable
   checkpoint path supplied through `--output`.
2. 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.
3. Read the checkpoint file and require a positive integer
   `execution_result.requestId`. Persist and report that ID immediately.
4. 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`: completed
- `Define 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 Defined` and `Hierarchy
> Defined` should 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 by
  `requested_scope`, then stop after reporting that reusable import preparation
  is ready. Retain `MappingNumber` values 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_only`
- `hierarchy_only`
- `structure_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.

```yaml
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:

```text
CountryCode,LevelNumber,GeographyType
```

Require all of the following:

1. 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.
2. Level 1 exists exactly once and has `GeographyType=COUNTRY`.
3. Level numbers are positive, unique, contiguous, and ordered from 1 through
   the lowest requested level.
4. Each geography type is nonblank and appears at only one level.
5. 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 Code` becomes `POSTAL_CODE`). Do not call
   Fusion metadata or lookup APIs to preflight geography types.
6. 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:

```text
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:

1. `CountryCode`, `PrimaryGeographyName`, `RecordTypeCode`, `SourceId`, and
   `LevelNumber` are present on every primary or anchor row. The country anchor
   has a blank `ParentSourceId`; every lower primary row has one.
2. Exactly one level-1 country anchor uses `RecordTypeCode=0`, has the resolved
   country name and code, and has no alternate identifier row.
3. A primary geography to create uses `RecordTypeCode=1`. Its level exists in
   the validated structure, its `GeographyType` matches that level, and its
   parent is present earlier in the same file.
4. Every child includes the complete parent chain needed by Oracle's Geography
   import. `ParentGeographyType`, when supplied, matches the parent's type.
5. Source IDs are unique across primary and anchor rows. Each
   `RecordTypeCode=2` alternate-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.
6. `IdentifierType`, `IdentifierSubtype`, and `IdentifierValue` are supplied
   together for type-2 rows and use current target-pod lookup values. Reject an
   alternate name already known to identify another geography.
7. `Prim

…(truncated)
