Manage Group Lookups Setup Task Guidance

Manage Group Lookups

Purpose

Provides task-specific setup planning, routing, export, import, and validation guidance for Manage Group Lookups under Trading Community Foundation.

Setup Task Skill Contract

• task_code: HZ_MANAGE_GROUP_LOOKUPS
• task_name: Manage Group Lookups
• parent_skill_id: cx.customer-data-management.trading-community-foundation
• pillar: CX
• offering: Customer Data Management
• functional_area: Trading Community Foundation
• functional_area_code: ORA_HZ_CDM_FOUNDATION
• available_flag: Y
• export_import_supported_flag: Y
• csv_export_import_supported_flag: Y
• source_catalog: knowledge/setup-task-catalog/effective/setupTasksAll.json

Usage

Use this skill when planning, sequencing, exporting, importing, or validating setup data for Manage Group Lookups under Trading Community Foundation.

Setup Task Metadata

• Task name: Manage Group Lookups
• Task code: HZ_MANAGE_GROUP_LOOKUPS
• Available: Y
• Export/import supported: Y
• CSV export/import supported: Y
• CSV export/import routing: supported

CSV Export, Import, and Validation Workflow

CSVExportImportSupportedFlag is Y for this task.

1. Export setup task data with shared.setup-export.task-level-export.
2. Validate setup task data with shared.validation.setup-data-validator.
3. Validate reference data with shared.validation.reference-data-validator.
4. Route every import exclusively through core.data-loader.
5. 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 to HZ_MANAGE_GROUP_LOOKUPS.
6. Let Core Data Loader prepare the final immutable upload artifact, then invoke its data-load Task Hook immediately before approval and upload. Require the Task Hook validation envelope to remain bound to that archive's SHA-256.
7. 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.
8. 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: Trading Community Foundation
• Setup task name: Manage Group Lookups
• Setup task code: HZ_MANAGE_GROUP_LOOKUPS

Inputs

• natural_language_request
• fusion_environment_context
• lookup_type_or_meaning
• lookup_code_and_named_changes
• setup_data_artifact
• project_id

Outputs

• lookup_result
• setup_data_result
• diagnostics
• skill_run_record
• token_usage_record

Implementation Notes

Use the parent functional-area skill cx.customer-data-management.trading-community-foundation for functional-area sequencing and scope decisions. Track token usage for any generated project artifact or skill-run record using the manifest policy.

Ownership and review

• Owner: CX Customer Data Management pillar team.
• Functional reviewer: CX Customer Data Management Pillar Lead or a Trading Community Foundation SME.
• Framework reviewer: FSCR A-Team/core reviewer.
• QA reviewer: required when lookup read, mutation, validation, export, or import behavior changes.

Reviewer guidance is in the body because the current manifest schema has owner_team but no reviewer field.

Task-specific lookup baseline

Task membership was read from the configured Fusion task page, and every exact member was independently retrieved from standardLookups on 2026-08-07. Reconfirm category and configuration level with a current GET. Do not extend this inventory by inference. See ora_reference_lookups.md.

Supported and unsupported operations

Never silently upsert. Reject a custom code beginning with ORA_. Treat CreatedBy == SEED_DATA_FROM_APPLICATION as seeded-origin evidence; use LastUpdatedBy only for audit and never guess seed status from a code name.

Configuration-level and manual mutation contract

• Extensible (HZ_HOUSEHOLD_DFLT_NAMES): protect seeded codes; permit REST-described Meaning, Description, and DisplaySequence, and permit state/date/create/delete operations only for a proven custom code. Do not change Tag.
• User (the other seven members): permit REST-described Meaning, Description, DisplaySequence, EnabledFlag, dates, and Tag; permit supported custom create/delete after seed checks.
• Protect lookup type/code identity, module, security, configuration level, category, and seeded identity. Current GET and describe metadata remain binding.

Every manual mutation must:

1. Resolve exactly one configured Fusion environment.
2. GET the exact lookup type and exact code when applicable.
3. Retrieve or use current cached describe metadata for the resolved resource family.
4. Validate task membership, configuration level, CreatedBy seeded-origin evidence, dates, reserved prefix, and named writable fields.
5. Show one exact redacted preview containing environment, method, endpoint, before/after values, payload, impact, and preview fingerprint.
6. Require explicit approval bound to that environment, target, method, payload, and fingerprint.
7. Send exactly one POST, PATCH, or DELETE through core.fusion-api.apps-common and core.fusion-api.rest-api-client.
8. Never automatically retry a mutation and never enable upsert.
9. Verify with a separate GET.
10. Report verified success, unverified success, refusal, or classified failure distinctly.

Read-only listing and retrieval require no approval.

Task CSV export contract

Route export to shared.setup-export.task-level-export with exact TaskCode: HZ_MANAGE_GROUP_LOOKUPS. The owning exporter must create one task CSV export, capture and monitor its ProcessId, download immutable FileContent only after success, retrieve ProcessLog after failure, and save the ZIP or diagnostic under the supplied project workspace. Do not implement export HTTP, polling, or ZIP processing here.

FSM ZIP validation and import contract

1. Run shared.validation.setup-data-validator and shared.validation.reference-data-validator for task-local setup and reference checks.
2. Route the import only to core.data-loader; this pillar skill supplies the exact task context and rules but never selects or invokes an import adapter or endpoint.
3. Detect an FSM ZIP only when a member has the exact case-sensitive basename ASM_SETUP_CSV_METADATA.xml.
4. Reject missing, duplicate, unreadable, encrypted, unsafe-path, or ambiguous metadata.
5. Parse metadata without rewriting the archive and require exactly one task identity equal to HZ_MANAGE_GROUP_LOOKUPS.
6. Preserve the archive bytes and SHA-256 through validation, Task Hook preview, approval, and execution.
7. After Core Data Loader prepares the final immutable upload artifact, require its data-load Task Hook to evaluate this task's compiled ora-resource rules and issue the validation envelope bound to the exact archive SHA-256.
8. Require a later standalone explicit approval of that exact immutable preview. A changed source, archive, environment, task identity, rule result, or approval invalidates the envelope and restarts validation.
9. Let Core Data Loader own UCM upload, FSM initiation routing and payload construction, accepted-request reporting, and any later status or ProcessLog retrieval. Do not reconstruct its envelope or locally choose an endpoint, adapter, routing field, or retry behavior.
10. Submit only once under the current Core Data Loader contract. If Task Hook validation or approval is missing, stale, or mismatched, stop with approval_blocker before any POST.
11. Treat a later Run Book or Journey updateProgress failure as a separate synchronization result. Do not change an accepted FSM import to failed, and never retry or resubmit the import because progress synchronization failed.

Natural prompts

• Show the Group Lookups in the configured environment.
• Show the values for <lookup meaning or exact lookup type>.
• Add lookup code <code> with meaning <meaning> to <lookup type>.
• Change the meaning of <code> in <lookup type>.
• Disable <code> in <lookup type>.
• Delete custom lookup code <code> from <lookup type>.
• Export Manage Group Lookups setup data.
• Validate and import this Manage Group Lookups export.

Resolve an unambiguous request directly; do not ask the user to choose an internal operation name.

Error and diagnostic contract

Durable diagnostics include status, stage, failure class, message, recommended action, environment, redacted endpoint, artifact references, ProcessId/ECID, completed checks, and verified side effects. Never persist credentials, tokens, authorization headers, customer data, signed URLs, or sensitive payloads.

Synthetic behavior checks

Persistence

When project_id is supplied, persist artifacts under the manifest paths, append a run record under project/{project_id}/state/runs, and append token usage under the shared token log. Repository-only authoring does not create a project workspace. Fail closed when required authority, membership, category, metadata, privilege, adapter, approval, or safe destination evidence is absent.