Manage Hierarchy Lookups
Purpose and routing
Manage the lookup values used by Customer Data Management hierarchy setup. Resolve an unambiguous natural request directly. Reuse core.fusion-api.apps-common for lookup operations, shared.setup-export.task-level-export for export, the shared validators for validation, and core.data-loader for every import. Do not implement task-local OAuth, HTTP transport, CSV processing, polling, or generic lookup CRUD.
Setup Task Skill Contract
- task_code:
HZ_MANAGE_HIERARCHY_LOOKUPS - task_name:
Manage Hierarchy Lookups - 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:
Y - csv_export_import_supported_flag:
Y - source_catalog:
knowledge/setup-task-catalog/effective/setupTasksAll.json
Ownership and review
- Owner: CX Customer Data Management pillar team.
- Required functional reviewer: CX Customer Data Management Pillar Lead or hierarchy SME.
- Required framework reviewer: FSCR A-Team/core reviewer.
- Required functional-behavior reviewer: FSCR QA when read, mutation, validation, export, or import behavior changes.
Reviewer metadata is kept in the body because the current manifest schema permits owner_team but has no reviewer field.
Task-specific lookup baseline
| Lookup type | Meaning | Configuration level | Evidence and restrictions |
|---|---|---|---|
PARTY_HIERARCHY_TYPE | Party Hierarchy Type | Extensible in the tested baseline; verify with the target GET | Oracle documents this type as the list updated after creating a hierarchy type. Protect seeded codes and require evidence from Manage Tree Structures before adding a custom code. |
HZ_TREE_STATUS | Hierarchy Status | System in the tested baseline; verify with the target GET | Oracle documents this lookup as the Active/Inactive hierarchy-status LOV. Its association with this task comes from the developer-provided tested task scope, not from its HZ_ prefix. |
Use the tested task-scope baseline for direct retrieval and require a current GET before claiming that either lookup or configuration level remains available in the target environment. Report a missing type as a baseline discrepancy and never infer additional task members from prefixes or modules. Adding a lookup value does not create a hierarchy definition, version, node, or hierarchy data. Read ora_reference_lookups.md for the official Oracle sources and evidence boundaries.
Supported operations
| Natural request | Support |
|---|---|
| Show hierarchy lookup types or values | Read-only through the exact category resolved by core.fusion-api.apps-common; no approval required. |
| Retrieve one exact type or code | Read-only; require an exact match. |
| Add a hierarchy type code | Conditional for a permitted custom PARTY_HIERARCHY_TYPE code after dependency, configuration-level, seed, and describe checks. |
| Change meaning, dates, or enabled state | Conditional only for fields and custom codes permitted by current metadata. |
| Delete a custom hierarchy type code | Conditional after destructive preview and approval. |
| Export setup data | Supported; route to shared.setup-export.task-level-export. |
| Validate setup data | Route to both shared validators and apply task-local rules. |
| Import validated setup data | Supported through core.data-loader only after Task Hook validation of the exact immutable archive and separate explicit approval. |
Never silently upsert. Reject custom codes beginning with ORA_. Never alter lookup identity, module, category, or seeded-code identity.
Manual field and operation restrictions
| Target | Create | Update | Enable or disable | Delete |
|---|---|---|---|---|
PARTY_HIERARCHY_TYPE Extensible custom code | Permit only after exact hierarchy-type evidence, duplicate check, GET, and current describe validation | Permit Meaning, Description, StartDateActive, EndDateActive, EnabledFlag, or DisplaySequence only when both Oracle configuration rules and current describe metadata allow the named field | Permit only for a non-seeded custom code and a current writable EnabledFlag | Permit only for a non-seeded custom code after destructive preview and approval |
PARTY_HIERARCHY_TYPE seeded code | No | Permit only a wording change that current Oracle rules and describe metadata explicitly allow; otherwise refuse | No | No |
HZ_TREE_STATUS System code | No | At most a Meaning wording change, and only when current describe metadata confirms the field is writable | No | No |
The REST schema lists more writable-looking attributes than a particular lookup's configuration level permits. Apply the stricter intersection of task scope, configuration-level rules, seeded-data protection, current describe metadata, and the user's named change. Do not update Tag or Module for Extensible or System lookups. Treat LookupType and LookupCode as immutable identity.
Treat a code as predefined seed data when current evidence reports LastUpdatedBy as SEED_DATA_FROM_APPLICATION; do not substitute naming conventions or CreatedBy guesses for that check.
CSV Export, Import, and Validation Workflow
CSVExportImportSupportedFlag is Y for this task.
- Export setup task data with
shared.setup-export.task-level-export. - Validate setup task data with
shared.validation.setup-data-validator. - Validate reference data with
shared.validation.reference-data-validator. - Route every import exclusively through
core.data-loader. - For an FSM ZIP, preserve the archive unchanged, require the exact case-sensitive member basename
ASM_SETUP_CSV_METADATA.xml, and require exactly one metadata task identity equal toHZ_MANAGE_HIERARCHY_LOOKUPS. - Let Core Data Loader prepare the final immutable upload artifact, then invoke its
data-loadTask Hook immediately before approval and upload. Require the Task Hook validation envelope to remain bound to that archive's SHA-256. - Require the user's separate explicit approval of the exact immutable preview. Any source, archive, environment, task identity, validation result, or approval change restarts the Core Data Loader and Task Hook lifecycle.
- Core Data Loader owns UCM upload, initiation payload construction, endpoint and FSM routing selection, accepted-request reporting, and later status diagnostics. This pillar skill must not select an adapter, endpoint, loader routing field, or retry policy.
Use this task metadata:
- Offering:
Customer Data Management - Functional area / Setup Object:
Enterprise Profile - Setup task name:
Manage Hierarchy Lookups - Setup task code:
HZ_MANAGE_HIERARCHY_LOOKUPS
Manual lookup workflow
- Resolve exactly one configured Fusion environment.
- GET the exact lookup type and exact code when applicable.
- Resolve the resource category and retrieve current describe metadata.
- Validate configuration level, seeded-code protection, hierarchy-type dependency, dates, reserved prefixes, and supported fields.
- Show one exact redacted method, endpoint, and payload preview.
- Require explicit approval for the named mutation.
- Send exactly one POST, PATCH, or DELETE through the shared REST transport. Never automatically retry a mutation.
- Verify with a separate GET and distinguish verified success, unverified success, refusal, and classified failure.
For create, explicitly send Upsert-Mode: false or omit the header so its documented default remains false. Never set it to true.
Privilege preflight
Before a live operation, verify all applicable access instead of relying on a role name alone:
- Require
ORA_ASM_FUNCTIONAL_SETUPS_USER_ABSTRACTand access to the exact setup task for UI-backed setup work. - Require the target role's task-specific Manage Hierarchy Lookups privilege. Current public Oracle documentation does not publish its code; use
core.diagnostics.role-access-checkor target-environment security evidence and fail closed when it cannot be confirmed. - Require
ORA_ASM_EXPORT_IMPORT_FUNCTIONAL_SETUPS_USERfor task CSV export or import. - Require authorization for the Standard Lookups REST resource and the exact lookup type. Treat a secured or unauthorized lookup as an authorization failure, not as an absent lookup.
Natural prompts
Show the Hierarchy Lookups in the configured environment.Show the values for Party Hierarchy Type.Show the hierarchy status values.Add hierarchy type lookup code MY_CUSTOM_HIERARCHY with meaning My Custom Hierarchy.Change the meaning of MY_CUSTOM_HIERARCHY to My Customer Hierarchy.Disable MY_CUSTOM_HIERARCHY in Party Hierarchy Type.Delete custom lookup code MY_CUSTOM_HIERARCHY from Party Hierarchy Type.Export Manage Hierarchy Lookups setup data.Validate and import this Manage Hierarchy Lookups export.
Error handling contract
Failure modes
| Failure class | Example | Recoverable behavior |
|---|---|---|
input_validation | Missing environment, invalid code, invalid date order, or changed artifact | Correct locally and restart from preflight; no side effect occurred. |
catalog_or_metadata_mismatch | Task flags, task scope, configuration level, or describe metadata differs | Stop and reconcile authoritative metadata; do not broaden scope. |
approval_blocker | Core Data Loader Task Hook did not issue a current validation envelope bound to the exact immutable archive SHA-256 | Stop before upload or initiation; rebuild and approve the immutable Data Loader preview. |
auth_expired_or_invalid | Cached-token 401 or 403 | Refresh a repository-managed cached token once; never replace an explicitly supplied token. |
authorization_or_privilege | 403 persists or task-specific privilege is absent | Stop and report the missing access; do not retry the operation. |
transport_or_environment | DNS, VPN, connection, or environment-resolution failure | Retry only a read with bounded shared-client policy; never retry a mutation automatically. |
fusion_api_error | Fusion rejects an approved request | Report redacted status, endpoint path, response summary, and ECID when available; stop. |
process_timeout | Export or import exceeds the owning executor's wait window | Stop polling and report TaskCode, ProcessId, last status, elapsed time, and the safe next-check path. |
process_failed | Export or import completes with errors | Retrieve and preserve ProcessLog or status evidence when available; return failure or partial failure. |
artifact_persistence | ZIP, validation result, run record, or token log cannot be saved | Preserve safe diagnostics in a temporary location and report the intended project path. |
approval_blocker | Preview is missing, stale, declined, or changed | Do not submit; regenerate the exact preview when inputs change. |
Preflight, retry, timeout, and recovery
- Preflight the exact environment, task code, catalog CSV flags, task membership, lookup type and code when applicable, configuration level, seeded evidence, supported fields, date order, privileges, immutable artifact hash, ZIP member safety, exact
ASM_SETUP_CSV_METADATA.xmlmember, metadata task identity, current Task Hook validation envelope, destination path, and approval requirement. - Permit at most one cached-token refresh for a read. Use bounded retries only for read-only transient transport failures. Never automatically retry POST, PATCH, DELETE, CSV import, loader, or ESS submission.
- Core Data Loader owns endpoint selection and any documented recoverable initiation behavior; this task skill must not override or duplicate that policy.
- Delegate polling windows to the owning export or Data Loader service. On timeout, preserve the external identifier and safe resume stage rather than submitting a replacement process.
- A manual lookup mutation has no automatic rollback. Reconcile uncertain completion with a separate GET. Request a new preview and approval for any compensating mutation.
- For failed CSV work, preserve the immutable source ZIP, validation result, ProcessId, ProcessLog/status payload, successful business-object results, and an
errorsarray when safe and whenproject_idis supplied.
Diagnostics, redaction, and approvals
Return status, stage, failure_class, message, recommended_action, environment identity, skill and task identity, redacted endpoint path, artifact references, ProcessId or ECID when available, completed checks, and verified side effects. Never print or persist credentials, tokens, authorization headers, token caches, full sensitive payloads, opaque signed URLs, or customer data. Require explicit approval bound to the displayed environment, operation, exact lookup identity or immutable ZIP, before/after values, expected impact, and preview fingerprint. Deletion, overwrite, force, mutation retry, import, and replacement submission always require fresh approval.
Synthetic golden scenarios
| Scenario | Synthetic request | Expected result |
|---|---|---|
| Read baseline | Show the Hierarchy Lookups in the configured environment | Resolve one environment, GET the documented/tested types, report configuration levels and any task-scope discrepancy; no approval. |
| Protect System status | Disable ACTIVE in HZ_TREE_STATUS | Refuse before preview because System codes can't have enabled state changed. |
| Missing hierarchy dependency | Add MY_CUSTOM_HIERARCHY without Manage Tree Structures evidence | Return an approval blocker before preview; do not invent or call an undocumented hierarchy-type endpoint. |
| Update custom meaning | Change MY_CUSTOM_HIERARCHY meaning to My Customer Hierarchy | GET exact code, prove it is non-seeded, validate writable Meaning, preview one PATCH, require approval, submit once, and verify separately. |
| CSV validation failure | Import a ZIP whose task identity isn't HZ_MANAGE_HIERARCHY_LOOKUPS | Refuse before core.data-loader and report the task-identity mismatch. |
| Task-local import route selection | Import an exact-task FSM ZIP through a route selected by this pillar skill | Refuse before POST; Core Data Loader owns endpoint, adapter, routing-field, and retry selection. |
| Missing Task Hook validation envelope | Import an exact-task FSM ZIP without an envelope bound to its current SHA-256 | Stop with approval_blocker; do not upload, initiate, or reconstruct an envelope. |
| Valid CSV route | Validate and import an immutable export for the exact task | Validate the exact archive and task identity, complete Core Data Loader Task Hook validation and separate approval, then let Core Data Loader execute once. |
Persistence
Fail closed on ambiguity or missing task, category, dependency, describe, configuration-level, source-guidance, privilege, or import-readiness evidence. When project_id is supplied, register durable artifacts, record the skill run, update applicable project state, and append token usage using the manifest policy. Repository-only authoring does not create a project workspace.
