Manage Address Formats Setup Task Guidance
Purpose and Boundary
Export or import the complete FSM setup package for Manage Address Formats.
Fix the task identity to HZ_MANAGE_ADDRESS_FORMATS under Trading Community Foundation.
Do not use this skill for planning, standalone validation, template generation,
filtered exports, or individual address-style inspection or maintenance.
Validation is permitted only as mandatory preparation for an export or import.
Supported Operations
export: export every setup-data object owned by the fixed task as one
unfiltered, non-template FSM package through
shared.setup-export.task-level-export.
import: import one complete, unchanged FSM ZIP for the fixed task through
mandatory core.data-loader validation and approval, then execute only
through this skill's native-fsm-import as the selected native FSM
adapter.
Treat a migration request as two operations. Complete and persist the source
export before starting a separate target import preflight and approval.
One Consolidated Approval
Use exactly one conversational approval point for each export or import.
Gather and validate every detail before asking for approval. Project creation,
local task-context refresh, authentication, browser sign-in, source review,
metadata checks, preview generation, Task Hook validation, and approval-envelope
creation are preparation steps and require no business-operation approval.
For an import, bind the approval to an initial submission with
SourceTargetDiffOkFlag=N and one conditional fallback with
SourceTargetDiffOkFlag=Y only if Fusion explicitly rejects the first
submission for a source-target revision mismatch. Disclose that bounded
two-submission behavior in the summary. The same approval authorizes the
conditional fallback because its target, task, archive bytes, hash, adapter,
and execution options remain immutable.
The only approval or acknowledgement response this skill may ask the user to
send is the standalone word approve, and only after the complete immutable
execution summary is ready. Factual questions remain permitted only for a
genuinely missing value that cannot be resolved safely from durable context.
Never ask the user to reply with ready, continue, approve, or any other
acknowledgement to start, finish, or resume authentication. Never ask whether
the user approves opening a login page, starting the OAuth callback listener,
using the configured local token cache, refreshing authentication, or running
read-only preflight checks.
Authentication Is Unapproved Preparation
Run authentication as one uninterrupted preparation phase before the execution
approval summary:
- Use the configured environment and the prescribed local, gitignored file
token cache from the first authentication attempt. Reuse a valid cached
token; otherwise start exactly one OAuth callback listener in a persistent
execution session and open the configured identity-provider page.
- If the identity provider requires interactive user input, provide only an
informational update such as:
Complete the Oracle sign-in in the browser window; preparation will continue automatically. Do not request a reply,
confirmation, approval, or sentinel word.
- Keep waiting on the same login process and callback. After authentication
succeeds, continue environment identity, privilege, task, package, adapter,
Task Hook, and preview validation automatically from the same waiting
process, without a conversational handoff.
- Do not launch repeated login flows merely because the first listener has not
produced output yet. Poll or wait on that listener until it completes or its
declared timeout is reached.
- If authentication ultimately fails or times out, report an authentication
blocker and the concrete remediation. Do not present an execution approval
summary, do not ask for
approve, and do not ask the user to reply ready.
When authentication later becomes available, resume preparation directly.
Authentication permission prompts imposed by the host runtime are platform
controls, not conversational approvals owned by this skill. Do not add a
second chat approval around them.
Complete this preparation bundle first:
- Resolve the project, configured environment, fixed task, operation, scope,
source or output path, execution options, and overwrite state from supplied
inputs and durable context. Ask a factual question only when a value remains
ambiguous or unsafe.
- If no implementation project exists, create the repository-prescribed draft
project. If its local task context is missing or stale, run the project
workspace initializer's artifact-only refresh. Do not create or update a
live Oracle Run Book.
- Complete OAuth authentication and source or target identity checks under
Authentication Is Unapproved Preparation. Treat interactive browser
sign-in as authentication, never as a chat checkpoint or export/import
approval.
- Finish catalog, privilege, live task, path, overwrite, package, Data Loader,
Task Hook, and immutable-preview checks that apply to the selected operation.
After preparation succeeds, render the execution summary as a CommonMark bullet
list with one labeled detail per item, in this order:
- Environment: source for export or target for import.
- Operation:
export or import.
- Task name:
Manage Address Formats.
- Task code:
HZ_MANAGE_ADDRESS_FORMATS.
- Scope: the exact whole-task scope.
- File name: for export, the planned pattern
<environment>_setup_task_csv_export_hz_manage_address_formats_<ProcessId>.zip
and note that Fusion assigns ProcessId; for import, the exact ZIP basename.
- File path: output directory plus the planned pattern for export; exact absolute
ZIP path for import.
- SHA-256:
Computed after download; unavailable before approval for export;
verified archive hash for import.
- Execution adapter: the selected shared adapter.
- Execution options: wait, polling, and applicable fallback settings.
- Revision mismatch fallback: import only; bounded initial
N and exact-mismatch-only Y behavior.
- Side effect: the precise Fusion mutation and local artifacts produced.
Do not collapse these details into prose or a table, and do not omit the file
items merely because an export filename and hash are finalized after approval.
Ask the user once to reply exactly approve. That single approval authorizes
only the immutable operation shown:
- Export: one FSM export submission, polling, and result retrieval.
- Import: one initial
setupTaskCSVImports submission of the validated FSM ZIP
and, only for Fusion's explicit revision-mismatch rejection, one conditional
override submission of those same immutable bytes, followed by polling and
result retrieval through the selected shared adapter.
Downstream approval records are internal representations of that same approval.
Do not prompt again at a task-local, Task Hook, adapter, upload, initiation, or
polling boundary. A change to any preview-bound value invalidates approval and
requires a new prepared summary.
An approve message received before a ready immutable summary is not usable.
Continue or repair preparation without asking for another acknowledgement;
after preparation succeeds, present the one complete summary and make the
operation's single approval request.
If a local failure provably happens before the first POST, permit one bounded
recovery without another approval only when the preview fingerprint and every
bound value are unchanged and audit evidence confirms no POST was attempted.
If a POST was attempted or its outcome is uncertain, approval is consumed and
automatic resubmission is forbidden, except for the exact revision-mismatch
fallback already disclosed and bound in the import preview.
Direct Export Trigger and Resume
Treat export manage address formats task, export fsm task Manage Address Formats, and equivalent whole-task wording as a complete export request. Infer
operation=export, the fixed task identity, template_only=false,
export_criteria=[], wait_seconds=300, and poll_interval=10. Resolve the
single configured Fusion environment and project without an approval prompt.
Run all safe preparation in the same turn. Persist the redacted ready preview:
project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/current/export-approval-preview.json
The preview must have status=ready_for_approval and bind its fingerprint to:
- project ID and source environment
- operation, task name, and task code
- whole-task, unfiltered, non-template scope
- output directory and shared export adapter
- empty export criteria
- wait and polling options
- exact live lookup artifact and lookup result
Compute the fingerprint from a canonical JSON representation of those bound
values, excluding timestamps, status, and the fingerprint field itself. Never
persist a token, secret, authorization header, or token-cache content.
Present the same values and ask exactly for approve. On the next standalone
approve, load the persisted preview, recompute its fingerprint, recheck all
bound values and the destination state, and immediately run the one shared
export command. Do not repeat discovery or request another approval. Capture
the ProcessId, poll it, retrieve FileContent or ProcessLog, verify and
register the artifact, update project state, append token usage, and report the
result. If no valid ready preview exists, repair preflight and present a new
summary; never treat an unbound approval as permission for a POST.
Fixed Task Context
- Pillar:
CX
- Offering:
Customer Data Management
- Offering code:
ZCH_CDM
- Functional area:
Trading Community Foundation
- Functional area code:
ORA_HZ_CDM_FOUNDATION
- Task name:
Manage Address Formats
- Task code:
HZ_MANAGE_ADDRESS_FORMATS
- CSV export/import supported:
Y
- Data Loader import mode:
FSM
Never accept a task-code, offering, or functional-area override.
Whole-Task FSM Export
Resolve or create the project, refresh missing local task-context artifacts,
and select the configured source Fusion environment. Complete authentication,
environment identity, privilege, destination-path, and overwrite checks as
read-only preparation without a login approval or ready handshake.
Use the shared task-name lookup without hierarchy filters:
python3 shared/setup-export/task-level-export/scripts/find_setup_task_code.py \
--task-name "Manage Address Formats" \
--token-cache auto \
--output project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/current/setup-task-search.json \
--json \
--print
Require exactly one returned row with the exact TaskName,
TaskCode=HZ_MANAGE_ADDRESS_FORMATS, AvailableFlag=Y, and
CSVExportImportSupportedFlag=Y. Live setup-task responses may omit offering
and functional-area fields; validate hierarchy from the effective catalog
and persisted task context. Fail closed on contradictory nonblank hierarchy
data or zero/multiple exact rows. Never select the first search result merely
because it appears first.
Fix template_only=false and export_criteria=[]. Refuse every record,
country, address-style, business-object, attribute, and template filter.
Persist the immutable export-approval-preview.json, show the single
execution summary, and ask once for approve as defined above. Do not route
export preview creation through core.data-loader, its Task Hook, or any
archive-verification command. An export has no ZIP or archive SHA-256 before
Fusion completes it.
After approval verification, invoke the shared exporter exactly once:
python3 -u shared/setup-export/task-level-export/scripts/export_setup_task_csv.py \
--data \
--task-code HZ_MANAGE_ADDRESS_FORMATS \
--offering-name "Customer Data Management" \
--functional-area-name "Trading Community Foundation" \
--project-id "{project_id}" \
--output-dir project/{project_id}/exports/customer-data-management/trading-community-foundation/manage-address-formats/ \
--token-cache auto \
--wait-seconds 300 \
--poll-interval 10
Use a persistent execution session with unbuffered output. Empty initial
output is not failure and must not trigger another export.
Persist the returned ProcessId immediately, then poll and retrieve results
only for that process. On COMPLETED or COMPLETED_WARNINGS, verify the ZIP,
compute its SHA-256, register it, and update project state. On
COMPLETED_ERRORS, retrieve and persist ProcessLog when available.
On timeout, preserve the same ProcessId, last status, and elapsed time.
Resume only that process after a later status request; never submit a
replacement export automatically.
If execution ends after the POST but before the ProcessId is observable,
reconcile with a read-only export-process lookup using the environment, task
code, and run-start window. Resume exactly one matching process. Fail closed on
zero, multiple, or unidentifiable candidates; a new POST requires a new preview
and approval.
Whole-Task FSM Import Through the Data Loader-Authorized FSM Adapter
Resolve or create the project and select the configured target environment.
Require one explicit ZIP path; reject loose CSV files, multiple archives,
directory scans, edited archives, and repacked archives.
Ensure the project has a current task-context entry resolving the sequence,
exact task name/code, and this skill path. Refresh only local artifacts when
needed; do not create a live Oracle Run Book.
Complete authentication under Authentication Is Unapproved Preparation,
then target identity, privilege, route, and source-path checks before preview
creation. Do not pause for a ready response after sign-in.
Verify a readable ZIP containing exactly one member whose basename is
ASM_SETUP_CSV_METADATA.xml. Require its single ObjectShortName to equal
HZ_MANAGE_ADDRESS_FORMATS. Preserve the archive byte for byte and compute
its SHA-256.
Route the import through core.data-loader with the fixed task context and
dataloader_import_mode=FSM. Data Loader owns source review, Task Hook
validation, adapter selection, immutable preview, approval-envelope
creation, and approved-payload release. It does not require its generic UCM
uploader to be the execution adapter.
During adapter selection, inspect the target pod's live
dataLoaderDataSets/describe action metadata. Never add runID,
sourceType, or another property to an ADF action unless that exact action
advertises the property. For this setup-task FSM package, select
cx.customer-data-management.trading-community-foundation.manage-address-formats.native-fsm-import and its setupTaskCSVImports route.
Do not select core/data-loader/scripts/upload_and_initiate.py; generic
Data Loader upload/initiation is not the native setup-task CSV import
contract for this package.
Build the Data Loader Task Hook preview over the exact immutable archive.
Require it to retain executionRoute=data-loader,
executionAdapter=cx.customer-data-management.trading-community-foundation.manage-address-formats.native-fsm-import,
packageType=FSM, revisionMismatchPolicy=auto_override_on_exact_mismatch,
sourceTargetDiffOkFlagSequence=[N,Y_on_exact_revision_mismatch], the fixed task name/code,
absolute archive path, archive SHA-256, wholeTask=true, waitSeconds=180,
and pollInterval=15. The adapter and revision policy are preview-bound;
changing either invalidates approval.
After every preflight check passes, display the one immutable-operation
summary and ask once for the standalone response approve. On that message,
record Task Hook approval internally, verify the archive hash again, persist
the approved envelope, and release that exact payload to the selected task-local
adapter without another prompt.
Invoke the task-local adapter exactly once:
python3 -u pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/scripts/import_manage_address_formats.py \
--zip-file "{setup_data_zip_path}" \
--task-validation-envelope project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/current/import-approval-envelope.json \
--token-cache auto \
--wait-seconds 180 \
--poll-interval 15 \
--output-dir project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/imports/
This adapter owns the bounded setupTaskCSVImports submission sequence,
immediate ProcessId capture, polling, and ProcessLog retrieval. Do not
call its endpoint or scripts before Data Loader releases the approved payload.
The approved command sends SourceTargetDiffOkFlag=N first. If and only if
Fusion returns the explicit HTTP 400 source-target revision-mismatch
rejection without a ProcessId, continue automatically with
SourceTargetDiffOkFlag=Y under the same approval. Permit no more than this
one fallback submission. Stop on any other response, uncertain outcome, or
failure, and never ask for a second approval for the preview-bound fallback.
Do not upload this FSM ZIP through uploadDataLoaderFile, call
initiateDataLoad, or send sourceType: FSM. Any changed target, archive
bytes, hash, task context, adapter, revision policy, or execution option
invalidates approval.
Persist the accepted result and redacted diagnostics. If the adapter returns
a ProcessId, resume or inspect only that process and never resubmit while
its outcome is uncertain.
User Experience Contract
Keep the workflow calm, predictable, and easy to resume:
- During preparation, send short progress updates only when the stage changes:
authentication, package validation, live task validation, and approval-ready.
Never expose endpoint trivia, raw JSON, Base64 content, or internal rule names.
- Present exactly one approval summary using the labeled list defined above.
Explain the revision fallback as a safety behavior, not as a second import:
Fusion is tried with revision protection first; only an explicit revision mismatch permits one retry of the same package.
- After approval, report
Import accepted as soon as Fusion returns a
ProcessId. State whether the revision fallback was not needed or applied once.
- On completion, lead with the outcome and show only the target, task, status,
ProcessId, immutable ZIP/hash, and artifact links. Put technical diagnostics
after the outcome and only when they help resolve a failure.
- On timeout, say
The import is still running; no new submission is needed,
show the same ProcessId and last status, and offer the status-only continuation.
- On a blocked preflight, identify the single failed check and the concrete
correction. Do not ask for approval until the full immutable summary is ready.
- On an uncertain POST response, say that no retry was made and that the next
action is read-only reconciliation. Never imply that the import failed merely
because a ProcessId was not observable.
Error and Retry Contract
Classify failures as input_validation, catalog_or_metadata_mismatch,
auth_expired_or_invalid, authorization_or_privilege,
transport_or_environment, fusion_api_error, process_timeout,
process_failed, artifact_persistence, or approval_blocker.
- Refresh a cache-managed token once after a read-only 401 or 403. A second
authentication response blocks execution. During the approved adapter POST
sequence, a cache-managed 401/403 may also refresh once; resume the same
N
or Y stage and never restart from N after reaching Y.
- Treat HTTP 400 action error
27503 from generic initiateDataLoad as an
adapter-contract defect. Stop, preserve whether UCM upload already succeeded
and its content ID when available, and do not retry that generic route or
upload the archive again.
- Never retry an export POST or an import POST automatically except for the
preview-approved Manage Address Formats fallback from
N to Y after
Fusion's exact revision-mismatch rejection. Limit that fallback to one second
submission of the same immutable operation.
- On timeout or failure, report environment, operation, task code,
ProcessId
or request ID, last status, elapsed time, diagnostic artifact, and one safe
next action.
- Never print or persist tokens, secrets, authorization headers, token-cache
contents, full Base64 payloads, or sensitive customer data.
Result Contract
For export, report source environment, fixed task name/code, ProcessId, status,
ZIP or log path, enclosure type, and ZIP SHA-256 when available. For import,
return the Data Loader-authorized shared adapter result and report target, task
name/code, immutable ZIP path and hash, ProcessId, status, and available
process log. Lead with Import accepted, Import completed, Import completed with errors, or Import is still running. State revision fallback as not needed or applied once; never expose N/Y without the plain-language label.
Record the skill run and token usage for every durable project activity.
Refusal Rules
- Refuse individual address-style creation, editing, deletion, reordering, or
inspection.
- Refuse filtered, partial, criteria-based, and template/specification exports.
- Refuse task-code overrides, loose CSV files, edited or repacked ZIPs, and
packages that Data Loader cannot confirm as the fixed FSM task.
- Refuse the generic
uploadDataLoaderFile plus initiateDataLoad route when
live action metadata does not advertise every proposed payload property.
- Refuse direct endpoint, script, or adapter execution that bypasses the
operation-specific approval workflow.
Golden Scenarios
| Request |
Expected route |
| Export all address formats from the configured environment |
Gather and validate all inputs, persist one export preview, ask once for approval, then run one shared FSM export and persist the ZIP, hash, and process result |
| Import the complete exported ZIP |
Finish Data Loader and Task Hook preflight, select this skill's native FSM adapter, show one immutable summary, ask once for approval, and submit the bounded initial-plus-exact-mismatch-fallback sequence |
| Fusion rejects import for a revision mismatch |
Under the already approved bounded fallback, immediately resubmit the same immutable operation once with SourceTargetDiffOkFlag=Y, then poll the returned ProcessId without another approval |
| Export only one country or address style |
Refuse partial scope without making a Fusion call |
| Create or edit an address style |
Refuse record-level maintenance without making a Fusion call |
| Export polling times out |
Preserve the ProcessId and resume only that process after a later status request |
Sources
knowledge/setup-task-catalog/effective/setupTasksAll.json
shared/setup-export/task-level-export/SKILL.md
shared/setup-import/fsm-csv-import/SKILL.md
core/data-loader/SKILL.md
https://docs.oracle.com/en/cloud/saas/applications-common/26c/farca/api-setup-task-csv-exports.html
https://docs.oracle.com/en/cloud/saas/applications-common/26c/farca/api-setup-task-csv-imports.html
1---2skill_id: "cx.customer-data-management.trading-community-foundation.manage-address-formats"3name: manage-address-formats-setup-task-guidance4description: "Exports or imports the complete Manage Address Formats setup-task data as an unfiltered Oracle Fusion FSM package, including cross-environment imports whose single approval explicitly covers a bounded source-target revision-mismatch fallback. Use only for whole-task FSM export/import; route exports through the shared task-level exporter and imports through core.data-loader validation with this task's native FSM adapter. Refuse record-level maintenance, filtered or template exports, undisclosed revision overrides, and execution that bypasses the approved route."5layer: "pillar"6pillar: "CX"7offering: "Customer Data Management"8functional_area: "Trading Community Foundation"9functional_area_code: "ORA_HZ_CDM_FOUNDATION"10task_code: "HZ_MANAGE_ADDRESS_FORMATS"11task_name: "Manage Address Formats"12parent_skill_id: "cx.customer-data-management.trading-community-foundation"13available_flag: "Y"14export_import_supported_flag: "Y"15csv_export_import_supported_flag: "Y"16dataloader_import_mode: "FSM"17businessObject: ""18source_catalog: "knowledge/setup-task-catalog/effective/setupTasksAll.json"19type: "orchestration"20execution_mode: "hybrid"21owner_team: "CX customer data management pillar team"22version: "0.14.0"23inputs:24 - "operation"25 - "project_id"26 - "fusion_environment_context"27 - "setup_data_zip_path"28 - "execution_options"29 - "execution_approval"30outputs:31 - "consolidated_approval_preview"32 - "configuration_export"33 - "export_submission_record"34 - "data_load_execution_result"35 - "diagnostics"36 - "skill_run_record"37 - "token_usage_record"38depends_on:39 - "shared.setup-export.task-level-export"40 - "shared.setup-import.fsm-csv-import"41 - "core.data-loader"42uses_core:43 - "core.auth.fusion-oauth-authentication"44 - "core.project-mgmt.project-workspace-initializer"45 - "core.project-mgmt.artifact-registry-manager"46 - "core.project-mgmt.project-state-manager"47persists_project_state: true48token_usage_tracking:49 enabled: true50 granularity: "per_skill_run"51 artifact_type: "token_usage_record"52 default_location: "project/{project_id}/artifacts/shared/token-usage/current/token-usage-log.md"53 estimation_method: "chars/4 estimate unless exact tokenizer or API accounting is available"54 required_fields:55 - "activity_start_time"56 - "skill_id"57 - "task"58 - "trigger"59 - "artifacts_written"60 - "files_read"61 - "estimated_input_tokens"62 - "estimated_output_tokens"63 - "estimated_total_tokens"64 - "estimation_method"65 - "notes"66oracle_supplied_guidance_files:67 - purpose: "Validate the fixed whole-task operation and single-approval contract before export or import."68 location: "ora-resource/ora_input_validation.md"69 - purpose: "Find the live task by its fixed name and validate the exact fixed TaskCode without depending on optional hierarchy fields."70 location: "ora-resource/ora_reference_lookups.md"71 - purpose: "Classify failures, preserve ProcessId diagnostics, and prevent unsafe resubmission."72 location: "ora-resource/ora_error_handling.md"73oracle_supplied_guidance_status: "Task-local validation, live lookup, and error-handling rules are compiled and ready."74state_updates:75 - "exports"76 - "reports"77 - "token_usage_records"78workspace_outputs:79 - artifact_type: "configuration_export"80 default_location: "project/{project_id}/exports/customer-data-management/trading-community-foundation/manage-address-formats/"81 versioning_policy: "append-only"82 - artifact_type: "report"83 default_location: "project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/current/"84 versioning_policy: "append-only"85 - artifact_type: "skill_run"86 default_location: "project/{project_id}/state/runs/"87 versioning_policy: "append-only"88 - artifact_type: "token_usage_record"89 default_location: "project/{project_id}/artifacts/shared/token-usage/current/token-usage-log.md"90 versioning_policy: "append-only"91applicability:92 industries:93 - "All"94 countries:95 - "All"96 fusion_releases:97 - "Current Oracle Fusion Cloud release"98side_effects:99 - "After explicit approval, creates and polls one whole-task FSM export process and writes its ZIP or process log to the project workspace."100 - "After explicit approval, imports one immutable whole-task FSM ZIP through the Data Loader-authorized shared task-level FSM adapter and can change address-format configuration in the target Fusion environment."101 - "Writes redacted preview, execution, diagnostic, run, artifact-registry, state, and token-usage records under the selected project workspace."102required_privileges:103 - "Fusion privileges to discover the setup task and run setup task CSV exports."104 - "Fusion privileges to submit, inspect, and retrieve logs for setup task CSV imports."105metadata:106 source: https://skillmd.com/skills/oracle/manage-address-formats-setup-task-guidance107---108109# Manage Address Formats Setup Task Guidance110111## Purpose and Boundary112113Export or import the complete FSM setup package for `Manage Address Formats`.114Fix the task identity to `HZ_MANAGE_ADDRESS_FORMATS` under `Trading Community115Foundation`.116117Do not use this skill for planning, standalone validation, template generation,118filtered exports, or individual address-style inspection or maintenance.119Validation is permitted only as mandatory preparation for an export or import.120121## Supported Operations1221231. `export`: export every setup-data object owned by the fixed task as one124 unfiltered, non-template FSM package through125 `shared.setup-export.task-level-export`.1262. `import`: import one complete, unchanged FSM ZIP for the fixed task through127 mandatory `core.data-loader` validation and approval, then execute only128 through this skill's `native-fsm-import` as the selected native FSM129 adapter.130131Treat a migration request as two operations. Complete and persist the source132export before starting a separate target import preflight and approval.133134## One Consolidated Approval135136Use exactly one conversational approval point for each export or import.137Gather and validate every detail before asking for approval. Project creation,138local task-context refresh, authentication, browser sign-in, source review,139metadata checks, preview generation, Task Hook validation, and approval-envelope140creation are preparation steps and require no business-operation approval.141142For an import, bind the approval to an initial submission with143`SourceTargetDiffOkFlag=N` and one conditional fallback with144`SourceTargetDiffOkFlag=Y` only if Fusion explicitly rejects the first145submission for a source-target revision mismatch. Disclose that bounded146two-submission behavior in the summary. The same approval authorizes the147conditional fallback because its target, task, archive bytes, hash, adapter,148and execution options remain immutable.149150The only approval or acknowledgement response this skill may ask the user to151send is the standalone word `approve`, and only after the complete immutable152execution summary is ready. Factual questions remain permitted only for a153genuinely missing value that cannot be resolved safely from durable context.154Never ask the user to reply with `ready`, `continue`, `approve`, or any other155acknowledgement to start, finish, or resume authentication. Never ask whether156the user approves opening a login page, starting the OAuth callback listener,157using the configured local token cache, refreshing authentication, or running158read-only preflight checks.159160## Authentication Is Unapproved Preparation161162Run authentication as one uninterrupted preparation phase before the execution163approval summary:1641651. Use the configured environment and the prescribed local, gitignored file166 token cache from the first authentication attempt. Reuse a valid cached167 token; otherwise start exactly one OAuth callback listener in a persistent168 execution session and open the configured identity-provider page.1692. If the identity provider requires interactive user input, provide only an170 informational update such as: `Complete the Oracle sign-in in the browser171 window; preparation will continue automatically.` Do not request a reply,172 confirmation, approval, or sentinel word.1733. Keep waiting on the same login process and callback. After authentication174 succeeds, continue environment identity, privilege, task, package, adapter,175 Task Hook, and preview validation automatically from the same waiting176 process, without a conversational handoff.1774. Do not launch repeated login flows merely because the first listener has not178 produced output yet. Poll or wait on that listener until it completes or its179 declared timeout is reached.1805. If authentication ultimately fails or times out, report an authentication181 blocker and the concrete remediation. Do not present an execution approval182 summary, do not ask for `approve`, and do not ask the user to reply `ready`.183 When authentication later becomes available, resume preparation directly.184185Authentication permission prompts imposed by the host runtime are platform186controls, not conversational approvals owned by this skill. Do not add a187second chat approval around them.188189Complete this preparation bundle first:1901911. Resolve the project, configured environment, fixed task, operation, scope,192 source or output path, execution options, and overwrite state from supplied193 inputs and durable context. Ask a factual question only when a value remains194 ambiguous or unsafe.1952. If no implementation project exists, create the repository-prescribed draft196 project. If its local task context is missing or stale, run the project197 workspace initializer's artifact-only refresh. Do not create or update a198 live Oracle Run Book.1993. Complete OAuth authentication and source or target identity checks under200 `Authentication Is Unapproved Preparation`. Treat interactive browser201 sign-in as authentication, never as a chat checkpoint or export/import202 approval.2034. Finish catalog, privilege, live task, path, overwrite, package, Data Loader,204 Task Hook, and immutable-preview checks that apply to the selected operation.205206After preparation succeeds, render the execution summary as a CommonMark bullet207list with one labeled detail per item, in this order:208209- Environment: source for export or target for import.210- Operation: `export` or `import`.211- Task name: `Manage Address Formats`.212- Task code: `HZ_MANAGE_ADDRESS_FORMATS`.213- Scope: the exact whole-task scope.214- File name: for export, the planned pattern `<environment>_setup_task_csv_export_hz_manage_address_formats_<ProcessId>.zip`215 and note that Fusion assigns `ProcessId`; for import, the exact ZIP basename.216- File path: output directory plus the planned pattern for export; exact absolute217 ZIP path for import.218- SHA-256: `Computed after download; unavailable before approval` for export;219 verified archive hash for import.220- Execution adapter: the selected shared adapter.221- Execution options: wait, polling, and applicable fallback settings.222- Revision mismatch fallback: import only; bounded initial `N` and exact-mismatch-only `Y` behavior.223- Side effect: the precise Fusion mutation and local artifacts produced.224Do not collapse these details into prose or a table, and do not omit the file225items merely because an export filename and hash are finalized after approval.226227Ask the user once to reply exactly `approve`. That single approval authorizes228only the immutable operation shown:229230- Export: one FSM export submission, polling, and result retrieval.231- Import: one initial `setupTaskCSVImports` submission of the validated FSM ZIP232 and, only for Fusion's explicit revision-mismatch rejection, one conditional233 override submission of those same immutable bytes, followed by polling and234 result retrieval through the selected shared adapter.235236Downstream approval records are internal representations of that same approval.237Do not prompt again at a task-local, Task Hook, adapter, upload, initiation, or238polling boundary. A change to any preview-bound value invalidates approval and239requires a new prepared summary.240241An `approve` message received before a ready immutable summary is not usable.242Continue or repair preparation without asking for another acknowledgement;243after preparation succeeds, present the one complete summary and make the244operation's single approval request.245246If a local failure provably happens before the first POST, permit one bounded247recovery without another approval only when the preview fingerprint and every248bound value are unchanged and audit evidence confirms no POST was attempted.249If a POST was attempted or its outcome is uncertain, approval is consumed and250automatic resubmission is forbidden, except for the exact revision-mismatch251fallback already disclosed and bound in the import preview.252253## Direct Export Trigger and Resume254255Treat `export manage address formats task`, `export fsm task Manage Address256Formats`, and equivalent whole-task wording as a complete export request. Infer257`operation=export`, the fixed task identity, `template_only=false`,258`export_criteria=[]`, `wait_seconds=300`, and `poll_interval=10`. Resolve the259single configured Fusion environment and project without an approval prompt.260261Run all safe preparation in the same turn. Persist the redacted ready preview:262263```text264project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/current/export-approval-preview.json265```266267The preview must have `status=ready_for_approval` and bind its fingerprint to:268269- project ID and source environment270- operation, task name, and task code271- whole-task, unfiltered, non-template scope272- output directory and shared export adapter273- empty export criteria274- wait and polling options275- exact live lookup artifact and lookup result276277Compute the fingerprint from a canonical JSON representation of those bound278values, excluding timestamps, status, and the fingerprint field itself. Never279persist a token, secret, authorization header, or token-cache content.280281Present the same values and ask exactly for `approve`. On the next standalone282`approve`, load the persisted preview, recompute its fingerprint, recheck all283bound values and the destination state, and immediately run the one shared284export command. Do not repeat discovery or request another approval. Capture285the `ProcessId`, poll it, retrieve `FileContent` or `ProcessLog`, verify and286register the artifact, update project state, append token usage, and report the287result. If no valid ready preview exists, repair preflight and present a new288summary; never treat an unbound approval as permission for a POST.289290## Fixed Task Context291292- Pillar: `CX`293- Offering: `Customer Data Management`294- Offering code: `ZCH_CDM`295- Functional area: `Trading Community Foundation`296- Functional area code: `ORA_HZ_CDM_FOUNDATION`297- Task name: `Manage Address Formats`298- Task code: `HZ_MANAGE_ADDRESS_FORMATS`299- CSV export/import supported: `Y`300- Data Loader import mode: `FSM`301302Never accept a task-code, offering, or functional-area override.303304## Whole-Task FSM Export3053061. Resolve or create the project, refresh missing local task-context artifacts,307 and select the configured source Fusion environment. Complete authentication,308 environment identity, privilege, destination-path, and overwrite checks as309 read-only preparation without a login approval or `ready` handshake.3102. Use the shared task-name lookup without hierarchy filters:311312 ```bash313 python3 shared/setup-export/task-level-export/scripts/find_setup_task_code.py \314 --task-name "Manage Address Formats" \315 --token-cache auto \316 --output project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/current/setup-task-search.json \317 --json \318 --print319 ```320321 Require exactly one returned row with the exact `TaskName`,322 `TaskCode=HZ_MANAGE_ADDRESS_FORMATS`, `AvailableFlag=Y`, and323 `CSVExportImportSupportedFlag=Y`. Live setup-task responses may omit offering324 and functional-area fields; validate hierarchy from the effective catalog325 and persisted task context. Fail closed on contradictory nonblank hierarchy326 data or zero/multiple exact rows. Never select the first search result merely327 because it appears first.3283. Fix `template_only=false` and `export_criteria=[]`. Refuse every record,329 country, address-style, business-object, attribute, and template filter.3304. Persist the immutable `export-approval-preview.json`, show the single331 execution summary, and ask once for `approve` as defined above. Do not route332 export preview creation through `core.data-loader`, its Task Hook, or any333 archive-verification command. An export has no ZIP or archive SHA-256 before334 Fusion completes it.3355. After approval verification, invoke the shared exporter exactly once:336337 ```bash338 python3 -u shared/setup-export/task-level-export/scripts/export_setup_task_csv.py \339 --data \340 --task-code HZ_MANAGE_ADDRESS_FORMATS \341 --offering-name "Customer Data Management" \342 --functional-area-name "Trading Community Foundation" \343 --project-id "{project_id}" \344 --output-dir project/{project_id}/exports/customer-data-management/trading-community-foundation/manage-address-formats/ \345 --token-cache auto \346 --wait-seconds 300 \347 --poll-interval 10348 ```349350 Use a persistent execution session with unbuffered output. Empty initial351 output is not failure and must not trigger another export.3526. Persist the returned `ProcessId` immediately, then poll and retrieve results353 only for that process. On `COMPLETED` or `COMPLETED_WARNINGS`, verify the ZIP,354 compute its SHA-256, register it, and update project state. On355 `COMPLETED_ERRORS`, retrieve and persist `ProcessLog` when available.3567. On timeout, preserve the same `ProcessId`, last status, and elapsed time.357 Resume only that process after a later status request; never submit a358 replacement export automatically.359360If execution ends after the POST but before the `ProcessId` is observable,361reconcile with a read-only export-process lookup using the environment, task362code, and run-start window. Resume exactly one matching process. Fail closed on363zero, multiple, or unidentifiable candidates; a new POST requires a new preview364and approval.365366## Whole-Task FSM Import Through the Data Loader-Authorized FSM Adapter3673681. Resolve or create the project and select the configured target environment.369 Require one explicit ZIP path; reject loose CSV files, multiple archives,370 directory scans, edited archives, and repacked archives.3712. Ensure the project has a current task-context entry resolving the sequence,372 exact task name/code, and this skill path. Refresh only local artifacts when373 needed; do not create a live Oracle Run Book.3743. Complete authentication under `Authentication Is Unapproved Preparation`,375 then target identity, privilege, route, and source-path checks before preview376 creation. Do not pause for a `ready` response after sign-in.3774. Verify a readable ZIP containing exactly one member whose basename is378 `ASM_SETUP_CSV_METADATA.xml`. Require its single `ObjectShortName` to equal379 `HZ_MANAGE_ADDRESS_FORMATS`. Preserve the archive byte for byte and compute380 its SHA-256.3815. Route the import through `core.data-loader` with the fixed task context and382 `dataloader_import_mode=FSM`. Data Loader owns source review, Task Hook383 validation, adapter selection, immutable preview, approval-envelope384 creation, and approved-payload release. It does not require its generic UCM385 uploader to be the execution adapter.3866. During adapter selection, inspect the target pod's live387 `dataLoaderDataSets/describe` action metadata. Never add `runID`,388 `sourceType`, or another property to an ADF action unless that exact action389 advertises the property. For this setup-task FSM package, select390 `cx.customer-data-management.trading-community-foundation.manage-address-formats.native-fsm-import` and its `setupTaskCSVImports` route.391 Do not select `core/data-loader/scripts/upload_and_initiate.py`; generic392 Data Loader upload/initiation is not the native setup-task CSV import393 contract for this package.3947. Build the Data Loader Task Hook preview over the exact immutable archive.395 Require it to retain `executionRoute=data-loader`,396 `executionAdapter=cx.customer-data-management.trading-community-foundation.manage-address-formats.native-fsm-import`,397 `packageType=FSM`, `revisionMismatchPolicy=auto_override_on_exact_mismatch`,398 `sourceTargetDiffOkFlagSequence=[N,Y_on_exact_revision_mismatch]`, the fixed task name/code,399 absolute archive path, archive SHA-256, `wholeTask=true`, `waitSeconds=180`,400 and `pollInterval=15`. The adapter and revision policy are preview-bound;401 changing either invalidates approval.4028. After every preflight check passes, display the one immutable-operation403 summary and ask once for the standalone response `approve`. On that message,404 record Task Hook approval internally, verify the archive hash again, persist405 the approved envelope, and release that exact payload to the selected task-local406 adapter without another prompt.4079. Invoke the task-local adapter exactly once:408409 ```bash410 python3 -u pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/scripts/import_manage_address_formats.py \411 --zip-file "{setup_data_zip_path}" \412 --task-validation-envelope project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/current/import-approval-envelope.json \413 --token-cache auto \414 --wait-seconds 180 \415 --poll-interval 15 \416 --output-dir project/{project_id}/artifacts/pillars/cx/customer-data-management/trading-community-foundation/manage-address-formats/imports/417 ```418419 This adapter owns the bounded `setupTaskCSVImports` submission sequence,420 immediate `ProcessId` capture, polling, and `ProcessLog` retrieval. Do not421 call its endpoint or scripts before Data Loader releases the approved payload.42210. The approved command sends `SourceTargetDiffOkFlag=N` first. If and only if423 Fusion returns the explicit HTTP 400 source-target revision-mismatch424 rejection without a `ProcessId`, continue automatically with425 `SourceTargetDiffOkFlag=Y` under the same approval. Permit no more than this426 one fallback submission. Stop on any other response, uncertain outcome, or427 failure, and never ask for a second approval for the preview-bound fallback.42811. Do not upload this FSM ZIP through `uploadDataLoaderFile`, call429 `initiateDataLoad`, or send `sourceType: FSM`. Any changed target, archive430 bytes, hash, task context, adapter, revision policy, or execution option431 invalidates approval.43212. Persist the accepted result and redacted diagnostics. If the adapter returns433 a `ProcessId`, resume or inspect only that process and never resubmit while434 its outcome is uncertain.435436## User Experience Contract437438Keep the workflow calm, predictable, and easy to resume:4394401. During preparation, send short progress updates only when the stage changes:441 authentication, package validation, live task validation, and approval-ready.442 Never expose endpoint trivia, raw JSON, Base64 content, or internal rule names.4432. Present exactly one approval summary using the labeled list defined above.444 Explain the revision fallback as a safety behavior, not as a second import:445 `Fusion is tried with revision protection first; only an explicit revision446 mismatch permits one retry of the same package.`4473. After approval, report `Import accepted` as soon as Fusion returns a448 `ProcessId`. State whether the revision fallback was `not needed` or `applied449 once`.4504. On completion, lead with the outcome and show only the target, task, status,451 ProcessId, immutable ZIP/hash, and artifact links. Put technical diagnostics452 after the outcome and only when they help resolve a failure.4535. On timeout, say `The import is still running; no new submission is needed`,454 show the same ProcessId and last status, and offer the status-only continuation.4556. On a blocked preflight, identify the single failed check and the concrete456 correction. Do not ask for approval until the full immutable summary is ready.4577. On an uncertain POST response, say that no retry was made and that the next458 action is read-only reconciliation. Never imply that the import failed merely459 because a ProcessId was not observable.460461## Error and Retry Contract462463Classify failures as `input_validation`, `catalog_or_metadata_mismatch`,464`auth_expired_or_invalid`, `authorization_or_privilege`,465`transport_or_environment`, `fusion_api_error`, `process_timeout`,466`process_failed`, `artifact_persistence`, or `approval_blocker`.467468- Refresh a cache-managed token once after a read-only 401 or 403. A second469 authentication response blocks execution. During the approved adapter POST470 sequence, a cache-managed 401/403 may also refresh once; resume the same `N`471 or `Y` stage and never restart from `N` after reaching `Y`.472- Treat HTTP 400 action error `27503` from generic `initiateDataLoad` as an473 adapter-contract defect. Stop, preserve whether UCM upload already succeeded474 and its content ID when available, and do not retry that generic route or475 upload the archive again.476- Never retry an export POST or an import POST automatically except for the477 preview-approved Manage Address Formats fallback from `N` to `Y` after478 Fusion's exact revision-mismatch rejection. Limit that fallback to one second479 submission of the same immutable operation.480- On timeout or failure, report environment, operation, task code, `ProcessId`481 or request ID, last status, elapsed time, diagnostic artifact, and one safe482 next action.483- Never print or persist tokens, secrets, authorization headers, token-cache484 contents, full Base64 payloads, or sensitive customer data.485486## Result Contract487488For export, report source environment, fixed task name/code, `ProcessId`, status,489ZIP or log path, enclosure type, and ZIP SHA-256 when available. For import,490return the Data Loader-authorized shared adapter result and report target, task491name/code, immutable ZIP path and hash, `ProcessId`, status, and available492process log. Lead with `Import accepted`, `Import completed`, `Import completed493with errors`, or `Import is still running`. State revision fallback as `not494needed` or `applied once`; never expose `N`/`Y` without the plain-language label.495Record the skill run and token usage for every durable project activity.496497## Refusal Rules498499- Refuse individual address-style creation, editing, deletion, reordering, or500 inspection.501- Refuse filtered, partial, criteria-based, and template/specification exports.502- Refuse task-code overrides, loose CSV files, edited or repacked ZIPs, and503 packages that Data Loader cannot confirm as the fixed FSM task.504- Refuse the generic `uploadDataLoaderFile` plus `initiateDataLoad` route when505 live action metadata does not advertise every proposed payload property.506- Refuse direct endpoint, script, or adapter execution that bypasses the507 operation-specific approval workflow.508509## Golden Scenarios510511| Request | Expected route |512|---|---|513| Export all address formats from the configured environment | Gather and validate all inputs, persist one export preview, ask once for approval, then run one shared FSM export and persist the ZIP, hash, and process result |514| Import the complete exported ZIP | Finish Data Loader and Task Hook preflight, select this skill's native FSM adapter, show one immutable summary, ask once for approval, and submit the bounded initial-plus-exact-mismatch-fallback sequence |515| Fusion rejects import for a revision mismatch | Under the already approved bounded fallback, immediately resubmit the same immutable operation once with `SourceTargetDiffOkFlag=Y`, then poll the returned ProcessId without another approval |516| Export only one country or address style | Refuse partial scope without making a Fusion call |517| Create or edit an address style | Refuse record-level maintenance without making a Fusion call |518| Export polling times out | Preserve the ProcessId and resume only that process after a later status request |519520## Sources521522- `knowledge/setup-task-catalog/effective/setupTasksAll.json`523- `shared/setup-export/task-level-export/SKILL.md`524- `shared/setup-import/fsm-csv-import/SKILL.md`525- `core/data-loader/SKILL.md`526- `https://docs.oracle.com/en/cloud/saas/applications-common/26c/farca/api-setup-task-csv-exports.html`527- `https://docs.oracle.com/en/cloud/saas/applications-common/26c/farca/api-setup-task-csv-imports.html`