CPQ Setup Assistant Setup Task Guidance

CPQ Setup Assistant Setup Task Guidance

Purpose

Provides task-specific planning, readiness validation, and controlled Data Loader execution guidance for CPQ Setup Assistant under Company Profile.

Setup Task Skill Contract

• task_code: ORA_CPQ_SETUP_ASSISTANT
• task_name: CPQ Setup Assistant
• parent_skill_id: cx.configure-price-quote.company-profile
• pillar: CX
• offering: Configure Price Quote
• functional_area: Company Profile
• functional_area_code: ORA_SVC_COMPANY_PROFILE
• 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, validating, and executing CPQ Setup Assistant under Company Profile. Use direct REST only for the declared read-only deployment, status, discovery, reconciliation, and LOV checks. Route every initialization, Company Profile update, CPQ user creation, and submission mutation through core.data-loader.

Use it directly when the objective explicitly concerns CPQ Setup Assistant, CPQ onboarding or initial setup, CPQ company profile setup, or CPQ administrator setup. These signals resolve to the following scope:

• Pillar: CX
• Offering: Configure Price Quote
• Functional area: Company Profile
• Setup task: CPQ Setup Assistant

If company or administrator setup is requested without CPQ or Configure Price Quote in scope, do not assume this skill applies; resolve the offering first. For a matching CPQ objective, use this task skill as the next action and follow its discovery, deployment-validation, and approval gates before any mutation.

Setup Task Metadata

• Task name: CPQ Setup Assistant
• Task code: ORA_CPQ_SETUP_ASSISTANT
• Available: Y
• Export/import supported: Y
• CSV export/import supported: Y
• CSV export/import routing: supported

Data Loader Execution Model

The CPQ Setup Assistant is a customer-impacting configuration action. The validated Data Loader objects are cpqSetupAssistantInitialize and setupAssistants. The setupAssistants object contains the parent Status field plus the CompanyProfiles and CPQUsers child sections. The compiled registry and REST client remain read-only; they must not perform a CPQ POST or PATCH mutation.

Data Loader Handoff

Approval ordering for every stage

For INITIALIZE, IMPORT_COMPANY_AND_ADMINS, and SUBMIT, use this order: prepare the metadata-backed immutable archive through Core Data Loader; evaluate Task Hook readiness; build the Task Hook preview and CPQ guard manifest; present the exact stage preview; obtain one explicit approval; record that approval and execute once through the guard. Complete deployment/status checks before initialization preparation, and stage-specific discovery and reconciliation before preparing later stages.

Readiness is eligibility to build an approval preview, not authorization to execute. Approval remains pending during Task Hook validation and manifest construction. Missing approval alone must not block those read-only steps or be recorded as a passed approval check. The current stage's manifest, reviewed binding, actor attribution, approval record, expiry and nonce are produced or checked at their prescribed preview/approve/execute steps, not required as inputs to readiness. Prior-stage completion and reconciliation evidence remain required where applicable. Missing data, unsafe state, unsupported capabilities, or invalid artifacts still block preview; no waiver or fabricated approval is implied.

For initialization preparation, read the initialization registration contract before deciding that the live action is unsupported. Evaluate the current Core metadata and validation result; do not require optional correlation or transport columns, or treat fields absent from Core's metadata projection as proof that the live action is missing. Unavailable action evidence remains indeterminate and blocks execution; it is not permission to invent a route or payload.

Task Hook's ready result selects the supported assisted rule-evaluation route. Read its execution guide and evaluate applicable CPQ registry nodes, recording node IDs, prerequisites, outcomes and sanitized evidence through the existing project diagnostic workflow. Aggregate the results in Task Hook's existing ordered ruleResults format. A separate evaluator executable or independently authenticated evaluator is not required by this route. Registry readiness alone is not a passed evaluation. Keep current-stage approval pending and unrelated stage rules not_applicable only when their applicability excludes them; do not mark a missing initialization contract as passed. Build the preview through the existing Task Hook and CPQ guard commands without constructing their outputs manually. Include evidence references in the existing stage preview's review context so assisted evaluation can be reviewed without claiming independent verification or changing the approval envelope.

Only the guard's approval and execution steps authorize a mutation. They retain exact binding, explicit confirmation, attribution, expiry, one-time consumption, target, live-state and reconciliation checks. Never reuse approval across stages or ask twice for the same stage. A changed or expired preview requires fresh validation and approval under the existing guard contract.

Before live approval, inspect cpq_data_loader_guard.py capabilities. The pillar uses explicit local approval: liveApprovalAvailable is true, while authenticated-actor remains false. Obtain the user's explicit approval of the exact stage preview, then record it with --confirmed, the exact --reviewed-binding, and a nonempty caller-supplied --actor for audit attribution. The actor is not independently authenticated; do not describe it as a verified session identity or infer approval from OAuth/OS credentials. ATEAM-1461 recommendation 3 remains unmet. This mode does not constitute an exemption or add independent approval verification inside Core. Requirements for authenticated identity, server-side conditional writes, cross-host coordination, or non-bypassable Core enforcement remain unsupported; declare them in proposal requiredGuarantees and stop with the capability blocker. Never fall back to direct Core upload. See live validation for the opt-in test procedure.

Every mutation handoff must use cpq_data_loader_guard.py after Core Data Loader preparation and Task Validator preview. Read CPQ approval guard before preparing the approval. The guard separates INITIALIZE, IMPORT_COMPANY_AND_ADMINS, and SUBMIT, binds the exact preview and archive, and consumes approval before delegating to Core's existing prepared-artifact upload. Do not invoke Core's upload command directly for CPQ mutations. Capture the existing Data Loader user approval through this guard; do not ask twice for the same stage. Preview creates one canonical manifest containing the stage, exact target, ordered operations, artifact digest, administrator set, generated redacted business summary, expiry, and nonce. Approve and execute that unchanged manifest; nonce and expiry are never regenerated at approval. Preview now requires --task-input for the Task Hook preview input and performs the declared live metadata/state/LOV reads before creating a version 3 manifest. The exact effective initiation settings and discovered baseline are bound to it. At upload, cpq_execution.py rechecks that live binding and verifies actual Core upload/initiation callbacks without allowing a routing-changing retry or token-refresh replay. Explicit approval of the exact manifest and the durable approval controls remain mandatory. After accepted initialization, use reconcile-initialization on the explicit completion continuation; unresolved initialization blocks further mutations. After a child-import attempt, run the guard's reconcile step with its consumed child manifest and approval record. This step invokes the already-declared resolve_cpq_setup_assistant_record read through Core's standard Fusion client, first verifies successful completion of the exact recorded child load, compares the complete expected company/admin state against the baseline plus approved operations, and generates a ledger-verified receipt. Unexpected administrators and changes to retained business values block reconciliation. In the EXISTS and EXISTS_WITH_BU branches, allow only Fusion's blank-to-populated Addressline, Country, or TaxRegNumber derivation after an approved Legal Entity selection; a replaced retained value or any other unapproved change still blocks reconciliation. Pending earlier stages remain recorded across process exit and block later mutations. Missing, ambiguous, incomplete, or mismatched results stop submission. Build the final parent source and a new final manifest only after success, pass that receipt using --reconciliation, and obtain the separate final-submission approval. A manually supplied verification flag or response fingerprint is not sufficient. At final execution, acquire the durable target submission lock atomically with approval consumption, then use that same declared read-only lookup to compare current Company Profile, CPQ-user, and assistant identity/status fingerprints with the approved receipt. Stop on changed or unreadable state; never rebuild the manifest under the old approval. The target lock blocks competing approvals and further mutations for this setup across projects using this checkout's shared pillar-local registry. Retain it after accepted or uncertain handoff. On an explicit recovery request, use recover-submission; it may release only a lock that has not entered Core handoff, after a successful read-only readiness check. Recovery invalidates the old reconciliation and never restores the consumed approval. See the guard reference for the external-change race and checkout-local coordination limits.

For complete company/admin reconciliation and final-state verification, use the bounded child-collection discovery declared in ora_reference_lookups.md. Read all pages and bracket them with assistant identity/status checks; reject malformed pages, duplicate identities, incomplete reads or changed targets. This is a finite verification step, not progress polling.

Execution retains its exact manifest/approval in protected local recovery storage before consuming the nonce. Historical reconciliation and inspection can use --attempt-id <original-nonce> after temporary files are removed. Retention does not authorize execution or release an uncertain attempt. Preserve evidence for outstanding and dependent workflows; use retain-evidence to migrate existing consumed attempts before deleting their original files. See the approval guard reference for storage, migration and closure requirements. Recovery storage provides no independent approving-user authentication or Core approval-ID verification; those ATEAM-1461 recommendation 3 guarantees remain unavailable.

The compiled registry is a readiness and authenticated-read graph. Its CPQ.INITIALIZATION_READY and CPQ.CONFIGURATION_READY terminals hand off a redacted, immutable readiness record to Core Data Loader; the terminals neither execute nor authorize a mutation.

After readiness and the applicable explicit approval, hand off through the CPQ guard to core.data-loader. Use cpqSetupAssistantInitialize for initialization, setupAssistants with CompanyProfiles and CPQUsers child rows for company and administrator changes, then a parent setupAssistants row for final submission with Status set to SUBMITTED. Resolve RestAction, parent/child linkage, keys, and writable fields from current Data Loader metadata; do not infer them from retired REST payloads. Preserve source-artifact fingerprints and approval binding, but never persist raw mutation values, OAuth tokens, or authorization headers in project artifacts.

For the supplied registered setupAssistants hierarchy, apply the explicit parent and child write contracts in data-loader-registration-contract.md. This registration permits a Company Profile update only through its discovered child identity, a new CPQ administrator only with first name, last name, and email, and final submission only through the parent patch contract. Do not infer a child create, update, identifier, or parent-link value that the current registration does not establish.

CPQ user create-field rule

For an approved new CPQUsers row, resolve the complete current child attribute template—not merely a compact generated DAT sample. Treat every attribute marked Mandatory or Required for new records as required when the registered child action resolves to create. In the registered CPQ-user contract, this requires FirstName, LastName, and Email for every proposed administrator. Use the registered parent link and the registered create RestAction for each child row. Do not supply CPQUserId, Id, PartyNumber, or UserName for a new administrator merely because a template displays it as a key, surrogate, or response attribute.

The CPQ-specific create contract treats generated identity attributes as server-generated even when the generic template marks them Mandatory or Required for new records. If separate route evidence requires a caller-supplied generated identity, or current metadata omits a required designation for any of the three administrator fields, stop before approval with a catalog/metadata mismatch. Do not weaken the CPQ-user contract or substitute a direct REST mutation.

Loader transport-field rule

Treat REST-Framework-Version and Content-Type as registration-controlled transport fields, not business configuration. A generated Data Loader sample may display SAMPLE_VALUE for either optional string field; that value is a generator placeholder and is never eligible for upload. Before building the immutable archive, resolve whether each field must be omitted or populated from the current registered business-object metadata/template. Do not copy the client's request defaults into a loader row and do not guess a value from a prior REST call. RestAction must likewise come from current metadata; for the initialization object, use the live registered create action only when it resolves unambiguously. If registration metadata does not establish a required transport-field value, stop with a catalog/metadata mismatch before approval or upload.

Access and Approval Gates

Do not check for, request confirmation of, or persist evidence about the three legacy initial-user roles. Authentication and authorization failures returned by a direct HTTPS call are handled as auth/authz failures. The remaining user gates are explicit approval to initialize CPQ and explicit approval of the exact post-discovery change summary before any Company Profile update, administrator creation, or submission.

CPQ Deployment Preflight

Before a configuration workflow enters Setup Assistant initialization, verify that CPQ is deployed in the selected environment. Use the documented unauthenticated deployment-version lookup; do not attach OAuth credentials, an Authorization header, or any other authentication material. A 404 result means CPQ is not deployed: show “CPQ is not dpeloyed in this instance and hence cannot proceed with Setups now.” and stop without initialization or any Setup Assistant call. Any other HTTP response confirms that the deployment endpoint is present and permits the workflow to continue directly to the separate initialization approval and initialization. Do not expose the endpoint, HTTP status, or transport details in the customer-facing response.

Customer-Facing API Disclosure Rule

In every API invocation flow, keep transport and request implementation details internal. Customer-facing responses must not include an API endpoint or path, HTTP method, request headers, query parameters, request body, payload field names, identifiers, or raw request/response content. This applies to success, approval, progress, validation, and error messages. Communicate the business action, affected configuration, plain-language outcome, and safe next action instead. Store any required operational diagnostics only in the approved project workspace, with sensitive values redacted.

When values are retrieved from the Setup Assistant LOV service, retain the complete response internally for validation only. Ask the customer for each required business value first. The exception is an existing-company branch: when IsDataExisting is EXISTS or EXISTS_WITH_BU, show the eligible Legal Entity display values before asking the customer to select one, so the selection comes from the verified list rather than an arbitrary value. For all other choices, provide possible values only if the customer explicitly asks for them, and then show only the display values for that single relevant LOV category (Country, Corporate Currency, Legal Entity, or Business Unit). Never show the complete LOV response, unrelated LOV categories, record metadata, or identifiers.

Address Line 1 Minimum-Data Rule

For a new-company flow, Addressline represents required Legal Address Address Line 1 only. Request a single street, building, premises, or locality line—not a complete postal address. Do not collect or include a city, state/province, postal or PIN code, country text, additional address lines, or other address components; country is selected separately from its LOV. If the customer provides a complete address or includes those components in the proposed line, ask them to provide Address Line 1 alone before validation and submission. Collect no additional address detail during this initial setup unless a separately approved workflow requires it.

Follow the mandatory workflow below. Do not ask for an administrator until the company-profile branch and required company details are resolved. Do not submit before reporting the discovered role mappings and starter-data state.

Mandatory Step-by-Step Workflow

1. Verify CPQ deployment. Before any Setup Assistant call, use the unauthenticated deployment-version lookup for the selected environment. If it returns 404, show “CPQ is not dpeloyed in this instance and hence cannot proceed with Setups now.” and stop. For any other HTTP response, continue with the read-only status check.
2. Check status before initialization. Read the CPQ Setup Assistant status once. If it is complete, in progress, reports an error, or is indeterminate, report the matching customer-facing outcome and stop without initialization. For a COMPLETED result, offer this ready-to-use next prompt: Publish Adaptive Search for oraclecpqo_transaction and oraclecpqo_transactionLine. Only SETUP_NOT_DONE proceeds to initialization approval.
3. Initialize CPQ only when needed. When the pre-initialization status is SETUP_NOT_DONE, prepare the immutable initialization archive, complete Task Hook readiness with approval pending, and build the guard preview. Present that exact initialization effect and obtain one explicit stage approval before initializing CPQ once. Do not assess Legal Entity, Business Unit, or other enterprise setup data before initialization. Do not repeat initialization automatically.
4. Rediscover and classify the initialized state. Immediately after the approved one-time initialization, read the CPQ Setup Assistant, Company Profile, CPQ Users, role mappings, starter-data child, and CPQ-owned progress. Treat Status and IsDataExisting as read-only discovery values and use them only to select the workflow branch. A post-initialization SETUP_NOT_DONE result proceeds to Company Profile input collection; IN_PROGRESS, ERROR, COMPLETED, and unknown results report their matching customer-facing outcome and stop. The sole exception is the governed final submission: after all required data, notices, and explicit approval are complete, submit exactly Status to SUBMITTED. Never include IsDataExisting in a payload or make any other Status change. Then translate the result with observed-state-branches.md.
5. Collect company details by existing-data branch. Retrieve Setup Assistant LOV data internally, then ask for each required Country, Corporate Currency, Legal Entity, or Business Unit value without preemptively displaying lists, except for Legal Entity in the EXISTS and EXISTS_WITH_BU branches: show its eligible display values upfront and require the customer's explicit selection from that list. If the customer explicitly asks for possible values for another category, show only the display values for that requested category; never show the complete LOV response. Explain, when needed, that the unique CPQ Company Identifier (also called CPQ Company Name) maps to the REST CompanyName field, while Enterprise Name maps separately to the Fusion EnterpriseName field. When IsDataExisting is DOESNT_EXIST, first inspect the returned configurable Company Profile fields: enterprise name, CPQ company identifier, Address Line 1, country, corporate currency, and, when applicable, tax registration number. If any are populated, tell the user that values are already present despite the new-company state, show the current values (redacting tax registration number), and ask whether to retain them or provide updates; collect only missing required values and requested changes. A retained country or currency must still be present in the current LOV response. Otherwise, collect enterprise name, currency, country, Address Line 1 only, and CPQ company identifier. Do not collect a complete address, postal or PIN code, state/province, city, country text, or additional address lines. In either case, do not ask for Legal Entity or Business Unit because Company Profile Setup creates them. When it is EXISTS, keep enterprise name read-only, do not collect address or country, require the user to provide the CPQ company identifier and select Legal Entity and Business Unit, and allow currency to be updated or require it when absent. When it is EXISTS_WITH_BU, apply the EXISTS flow, including the required CPQ company identifier, but preserve the discovered Business Unit as read-only. If IsDataExisting reports a partial setup or an active LDAP job, stop with the task-specific customer message instead of collecting changes.
6. Validate the company proposal. Confirm that every selected country, currency, legal entity, and business unit exists in the current lists of values, and retain the discovered Company Profile ID. Do not prepare a Data Loader row at this stage.
7. Collect CPQ administrators. Only after the company details are ready, first ask whether the current logged-in user should be created as a CPQ administrator. If yes, collect that user's first name, last name, and valid email address; do not assume or expose identity values from the session. Then ask whether additional CPQ administrators should be added. If yes, collect first name, last name, and valid email address for each additional user. Reconcile every requested user against discovered CPQ users and resource records; do not create duplicates. Initial setup requires at least one valid administrator, which may be a discovered administrator or an approved, validated new administrator. If discovery already confirms one or more valid administrators and no addition is requested, do not create a user; reconcile that existing state before submission.
8. Notify before submission. Report the discovered CPQ role mappings as seeded read-only information and report starter-data readiness as unavailable, ready, running, complete, or failed. Do not create, delete, remap, import, or rerun either resource through this skill. If starter data is running or failed, stop submission and explain the safe next action.
9. Validate, preview, then obtain approval. For each stage, prepare its immutable source through Core Data Loader, complete Task Hook readiness with approval pending, and build the Task Hook preview and CPQ guard manifest. Show a redacted summary of the changed company fields, selected legal entity and business unit, every proposed administrator, target environment, role/starter-data notice, and intended submission. The customer summary must describe the business change only; never include a loader source, endpoint, request payload, or other implementation detail. Obtain explicit approval for that exact summary before each immutable Data Loader submission.
10. Execute once in order. Use cpqSetupAssistantInitialize, then one immutable pre-submission setupAssistants source containing the changed CompanyProfiles row and every approved CPQUsers row, then a final parent setupAssistants source with Status set to SUBMITTED. Apply the registered child patch/create contracts in data-loader-registration-contract.md: the combined child source must update only the discovered Company Profile and create every new administrator with FirstName, LastName, and Email, treating both Mandatory and Required for new records as required for that create action. Do not create a Company Profile or supply a generated CPQ-user identity. Bind the exact combined child source, ordered operation set, and redacted change summary to approval. Validate each exact metadata-backed source and immutable archive through core.data-loader; reject any SAMPLE_VALUE transport-field placeholder and resolve optional transport fields from the current business-object registration before approval; never retry an upload or initiation automatically. After the combined child import is accepted or uncertain, rediscover both Company Profile and CPQ-user state before any final submission. Once final submission is accepted, tell the user: “CPQ Setup Assistant has been submitted. It typically completes in approximately 12–15 minutes. You can track progress in the Schedule Processes UI by monitoring the Run Setup Assistant process.” This is advisory timing, not a completion guarantee. Immediately after final submission, perform exactly one read-only status and progress retrieval, translate its CPQ-owned result for the user, then end the execution. Follow api-flow.md.
11. Refresh status later only on request. After the required immediate post-submission retrieval, do not automatically poll, retry, resubmit, or make another status read. A later status refresh starts only when the user explicitly requests it: identify the target environment, perform exactly one read-only status GET with a 30-second HTTP request timeout and no retry, translate the returned CPQ-owned progress and Company Information prerequisite state using the user-facing status messages in observed-state-branches.md, then end the request. Do not mention Adaptive Search in processing or incomplete status messages; offer its invocation prompt only for an overall successful completion. A timeout or read failure returns “CPQ setup status could not be determined safely”; retain sanitized diagnostics when available, do not infer completion, and do not mutate. Any later setup submission must independently rediscover the authoritative Fusion state before mutation.

The Data Loader path bypasses wizard-page validation. Validate required values before submission and use only IDs returned by the discovery request.

Partial-Failure and Safe-Resume Contract

This contract applies when a company-profile update or administrator creation fails or has an uncertain outcome before submission is accepted.

1. Stop mutations and retain the consumed approval. Do not retry an uncertain operation, advance the stage, or submit the assistant.
2. Inspect without replay. Use inspect-child-outcome with the original consumed manifest and approval record. It verifies the recorded completion evidence when available and reads current company/admin state. Its classifications are matches_approved, not_observed, and uncertain. An absent record does not prove that the original job cannot apply later.
3. Retain pending markers. The sanitized diagnostic records observations, completion/state verification, and one next action; it never grants retry authority. Only ordinary full reconcile can advance a successfully completed child load after every expected result is verified.
4. Recover proven zero-write attempts only. recover-prewrite requires a durable pre-write phase, no remote identifiers, eligible unchanged assistant identity, and the execution lock. The nonce stays consumed. A released child attempt is excluded from latest-import selection; fresh reconciliation of the last actual import is required before final approval. If there was no actual child import, the verified existing-state route may be used.
5. Escalate partial or uncertain writes. This skill does not provide automated remaining-work retry. Resolve the original job through the supported operational process. Enabling resume requires a separately verified contract proving original-job finality and safe retry/idempotency. Fresh approval alone cannot clear uncertainty or authorize replay.

If submission was accepted or its acceptance is uncertain, do not use this pre-submission resume flow. Never submit again. Perform the one required immediate read-only status retrieval, then allow later status refresh only when user-triggered. If a retrieval reports an error, stop, retain the sanitized diagnostic, identify the affected CPQ setup step in plain language when the returned progress identifies one, and direct the user to the Run Setup Assistant ESS job logs in the Schedule Processes UI. If the log review does not resolve the issue, advise the user to log an Oracle Service Request (SR). If no affected step is returned, say that the affected step could not be determined safely; never infer one.

Discovery-Driven Use Cases

Read observed-state-branches.md after the discovery request. Treat the returned state as authoritative for the target environment; do not infer a branch from a prior run.

Never expose implementation status codes to users. Translate every returned state using observed-state-branches.md. Underlying company/business-unit data is not CPQ completion; determine completion from assistant status and only the CPQ-owned progress tasks.

Inputs

• implementation_objective
• project_context
• setup_task_scope
• setup_data_artifacts

Outputs

• setup_task_plan
• setup_data_routing
• validation_checkpoints
• cpq_setup_assistant_execution_result: the latest available overall Setup Assistant status and the latest available status for each individual CPQ-owned setup task.
• cpq_data_loader_handoff: a redacted, immutable readiness record for Core Data Loader; it contains operation IDs, source-artifact fingerprints, and digests, never mutation values or credentials.
• sanitized_diagnostics: internal project-workspace audit and recovery evidence only. Never include diagnostics, endpoint details, payloads, identifiers, or raw API data in customer-facing output.
• skill_run_record
• token_usage_record

Implementation Notes

Use the parent functional-area skill cx.configure-price-quote.company-profile for functional-area sequencing and scope decisions. Before execution, load the compiled ora_rule_registry.json, obtain a planned execution plan, and use its readiness terminal only as the handoff record for Core Data Loader. Core Data Loader independently validates current metadata, source structure, immutable archive, and approval immediately before upload and initiation. Track token usage for any generated project artifact or skill-run record using the manifest policy.

Release the executable guard and complete test directory with this skill, and run the release validation against the release candidate contents.