Run Geocode Generation
Purpose
Run and monitor Oracle Fusion's Populate Location Latitude and Longitude Information scheduled process for eligible active and verified addresses. The
setup task is Run Geocode Generation; its fixed ESS job is
HZ-HZGEOCODER.
When to Use
Use this skill when the user asks to:
- run geocode generation with no optional parameters;
- restrict the run by country or location last-update date range;
- regenerate coordinates that are already populated;
- choose a batch size;
- monitor a submitted geocode request; or
- resume monitoring by an existing
requestId.
This skill does not configure country geography structures, enable geocoding, cleanse addresses, or import geography reference data.
Inputs
execution_intent: infer live authorization from a direct request to run geocode generation; advisory or hypothetical requests do not authorize a submission.execution_mode_selection:parameterlessorparameterized. Infer parameterized when the user supplies filters. Otherwise resolve it with the user-friendly scope question before execution.monitoring_choice:request_id_onlyormonitor_status. Resolve this before preview and submission unless the user's request already states it.fusion_environment_context: required unless exactly one configured target can be resolved without ambiguity.country: optional country name, common country alias, or two-letter code. Resolve it to one documented country andcountry_codebefore submission.country_code: resolved two-letter Fusion geography code sent to ESS.start_dateandend_date: optional paired inclusive date range. Accept Fusion UI-styleM/D/YYorMM/DD/YY, and accept ISOYYYY-MM-DD; apply the range to the location last-update date. Always serialize ESS arguments asYYYY-MM-DD.regenerate_geocode: optionalYorN; the process default isN.batch_size: optional positive integer. Default is50; values above the SME-confirmed runtime limit are normalized to100and disclosed.requestId: optional existing ESS request to monitor. It is mutually exclusive with new-submission parameters.execution_options: optional positivewait_secondsandpoll_interval.project_id: required only when the user explicitly requests durable project output or supplies a project ID. Its absence means a transient live run and must not trigger project-workspace creation.
All five business process parameters are optional. If none is supplied, run in parameterless mode and let Fusion apply the scheduled process defaults.
Outputs
execution_preview: informational target environment, mode, normalized inputs, effective defaults, impact, and execution-intent state.ess_execution_result: request ID and terminal or last-known ESS status.diagnostics: redacted failure classification and recovery guidance.skill_run_recordandtoken_usage_recordwhen a project workspace is used.
Ownership and Review
- Owner: CX Customer Data Management pillar team.
- Required functional reviewer: CX Pillar Development Lead or Geography SME.
- Required platform reviewer: FSCR A-Team/core reviewer.
- Required behavior reviewer: QA, including approval, privilege, retry, timeout, diagnostics, and redaction coverage for this hybrid skill.
Read Order
- Read input intake.
- Read reference lookups.
- Read input validation.
- Read defaulting rules.
- Read dependency readiness.
- Read bulk behavior.
- Read design advisory.
- Read design enforcement.
- Before preview or execution, read REST and ESS execution and error handling.
- Use the compiled task registry as the task-local execution graph.
Workflow
1. Resolve parameters naturally
Use one of:
- parameterless new submission;
- parameterized new submission; or
- tracking an existing
requestId.
For a direct request such as "Run geocode generation" that does not already specify filters or no-filter behavior, ask:
Should I run geocode generation for all eligible addresses in countries where geocoding is enabled, or narrow it to a specific country or other filters?
Do not use the terms parameterless and parameterized in the normal user
prompt. Interpret "all eligible addresses" or "without filters" as
parameterless. Interpret a specific country, date range, regenerate option, or
batch size as parameterized. If the original request already resolves the
scope, do not repeat the question.
When the user asks to narrow or parameterize the run but has not supplied the values, ask in plain language:
You can optionally narrow the run. Send any values you want to use:
- Country name or code, for example
IndiaorIN- Start and end dates like the Fusion UI, for example
8/4/26and8/6/26- Regenerate existing coordinates:
YorN- Batch size; default and recommended is
50Reply
noneto run all eligible addresses for geocoding-enabled countries. See Oracle's parameter documentation for details.
Do not ask separately for omitted parameters because all five are optional. If the user provides one date, ask only for the missing paired date. Normalize and validate values after collection.
After mode and any parameters are resolved, but before previewing or submitting a new request, ask when the monitoring choice is not already explicit:
After submission, should I return the ESS request ID only, or monitor the status here?
Use request_id_only to submit once in the core skill's submit-only mode,
return the requestId, and end without polling. Use monitor_status to submit
once, return the requestId, and poll that same request using the configured
wait_seconds and poll_interval. Include the selected behavior in the
business-level execution summary. Do not choose a monitoring mode silently.
Do not combine requestId with fields for a new submission. Reject arrays,
CSV, spreadsheets, and multi-request input.
2. Resolve and validate the target
Bind the run to exactly one Fusion environment. Validate only the fields the
user supplied. Resolve a supplied country name, alias, or common misspelling
through ora-resource/ora_reference_lookups.md, then send only its normalized
uppercase two-letter code to ESS. Require both dates when either is supplied.
Parse UI-style M/D/YY or MM/DD/YY as a real calendar date, interpret a
two-digit year as 20YY, accept ISO YYYY-MM-DD as already normalized, and
serialize both ESS date arguments strictly as ISO YYYY-MM-DD. Compare the
normalized dates and ensure the start date is not later than the end date.
Never pass slash-formatted dates to ESS. Perform this task-specific
normalization as part of the skill's validation and mapping workflow; do not
add task-local executable code or modify the shared ESS submitter.
Show the resolved country and code in the informational execution summary. If the resolver corrected spelling, disclose it without asking for confirmation when the match is uniquely high confidence. Ask a short clarification question instead of submitting when the input is unknown or ambiguous.
Do not ask the user to confirm that geocoding is enabled for the intended country or countries. Treat that configuration, along with active and verified address status, as Fusion selection criteria rather than manual approval gates. Disclose briefly that Fusion processes only eligible addresses in countries already enabled for geocoding and that a successful request can legitimately select no rows.
Let Fusion enforce the declared ESS privilege at submission and classify an
access rejection as auth_or_authorization.
3. Confirm execution intent without a second approval
Treat a direct imperative request to run geocode generation as authorization
for one submission after validation and readiness checks pass. Do not ask the
user to approve the environment, dependency, payload, or core skill again.
After the user answers any required scope and monitoring questions, continue
directly to one submission in the same flow. The execution preview is
informational and must not pause the flow. Never ask the user to reply
Approve, Confirm, or equivalent when the original request was a direct
imperative.
Before execution, give a short business-level update naming the environment,
whether optional filters are being used, and whether the skill will return only
the request ID or monitor status. If regeneration is Y, warn that already
populated coordinates may be processed again. Reveal the technical payload only
when the user asks for it. When dates are supplied, show their normalized ISO
values in the informational summary so the user can verify the effective range.
If the request is advisory, hypothetical, or ambiguous about whether to run, stop before submission and ask one short execution-intent question.
4. Submit or monitor through the core ESS skill
Invoke core.fusion-api.ess-job-submitter; do not call Scheduler REST directly
and do not add task-local authentication or polling code.
For a new request, use the fixed job definition and mapping in
ora-resource/ora_rest_execution.md, including application CrmEss. Submit
exactly once with no automatic POST retry and capture the returned requestId.
When monitoring_choice=request_id_only, use submit-only mode and return
immediately. When monitoring_choice=monitor_status, poll the same request with
bounded defaults of wait_seconds=300 and poll_interval=10 unless valid
overrides are supplied.
For an existing requestId, use the core tracking path and never submit a
replacement request.
5. Report the outcome
On terminal success, report the environment, request ID, and terminal status. State that the scheduled process completed; do not claim that every selected address received coordinates.
On polling timeout, report that the process is still nonterminal, preserve the request ID and last status, and resume the same request later. On failure, return the failure class, available ESS status and ECID, and the recommended next action. A new submission after failure requires a new direct run request.
Persistence
When project_id is explicitly supplied or the user explicitly requests
durable project output, persist redacted validation, preview, request ID,
terminal or last-known status, diagnostics, skill-run, and token-usage records
under the manifest paths. Otherwise run transiently: do not create a draft
implementation project, audit workspace, run workspace, artifact, or
token-usage record, and do not pause submission for persistence approval.
Never persist credentials, bearer tokens, client secrets, token-cache contents,
private keys, or sensitive payloads.
Error and Retry Policy
- Allow only the shared cached-token refresh behavior for a
401or403. - Never retry a new ESS
POSTautomatically. - Treat a missing request ID after POST as an uncertain outcome; do not resubmit.
- Treat a polling timeout as nonterminal and resume the same request ID.
- Classify failures using
governance/error-handling-guidelines.md.
Refusal Rules
- Do not submit without one exact environment and direct execution intent.
- Do not invent a country code outside the documented resolver or silently repair an ambiguous country or invalid date range.
- Do not default regeneration to
Y. - Do not submit again when Fusion rejects the required privilege.
- Do not issue more than one POST or replace an uncertain or timed-out request.
- Do not report success before a terminal successful ESS status.
Golden Scenarios
| Scenario | Expected Result |
|---|---|
| User says "Run geocode generation" without stating scope | Ask whether to run for all eligible addresses in geocoding-enabled countries or narrow the run |
| User chooses all eligible addresses | Resolve parameterless, ask for monitoring behavior when missing, and submit once without a second approval prompt |
| User directly requests a run, then selects all addresses and monitoring | Show a short informational summary and submit immediately; never ask for Approve submission |
| No project ID or durable-output request is supplied | Run transiently without creating or requesting approval for a project workspace |
| User chooses all eligible addresses but has not confirmed country setup | Do not ask for setup confirmation; explain that Fusion automatically limits processing to eligible addresses in geocoding-enabled countries |
| User supplies one or more supported filters | Infer parameterized, validate the supplied values, and do not ask for omitted optional filters |
User says Australia | Resolve and disclose Australia (AU), then pass AU as submit.argument1 |
User says austraila | Resolve the unique adjacent-letter spelling correction to Australia (AU), disclose it, and pass AU |
| Country text has no unique high-confidence match | Ask the user to choose from the closest documented candidates; do not submit |
| User asks for filters but supplies none | Show the friendly parameter list and allow none to select parameterless execution |
| User does not state a monitoring preference | Before preview, ask whether to return only the request ID or monitor status here |
| User chooses request ID only | Submit once in submit-only mode, return the request ID, and end without polling |
| User chooses monitor status | Submit once, return the request ID, and poll that same request using the selected timeout |
User supplies US, a valid date pair, N, and batch 50 | Use the normalized ordered values and submit once according to the selected monitoring behavior |
User supplies batch 150 | Normalize to 100, disclose the change, and continue under the original direct execution intent |
| User supplies only a start date | Stop as input_validation and request the end date |
User supplies 8/4/26 through 8/6/26 | Accept the UI-style input, show 2026-08-04 through 2026-08-06, and pass those ISO values as submit.argument2 and submit.argument3 |
User supplies 08/04/26 | Never pass it unchanged to ESS; normalize it to 2026-08-04 |
User supplies an invalid calendar date such as 2/30/26 | Stop as input_validation; do not submit |
User supplies regeneration Y | Warn that already geocoded locations may be processed again before submission |
| User supplies an existing request ID | Monitor that request without a POST |
| Polling times out | Preserve the request ID and resume it later; do not submit again |
Source Boundaries
- Process guidance:
https://docs.oracle.com/en/cloud/saas/sales/fauss/populate-location-latitude-and-longitude-information.html - Geocoding setup:
https://docs.oracle.com/en/cloud/saas/applications-common/26b/facia/set-up-geocoding.html - Scheduler REST contract:
https://docs.oracle.com/en/cloud/saas/applications-common/26c/farca/op-ess-rest-scheduler-v1-requests-post.html - Internal job metadata:
https://confluence.oraclecorp.com/confluence/pages/viewpage.action?pageId=7210249295 - Effective task catalog:
knowledge/setup-task-catalog/effective/setupTasksAll.json
Use the parent skill
cx.customer-data-management.enterprise-profile for functional-area scope and
sequencing.
