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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Stop mutations and retain the consumed approval. Do not retry an uncertain operation, advance the stage, or submit the assistant.
- 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.
- 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.
- 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.
- 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.
| Use case |
Read evidence |
Allowed outcome |
| Assess an existing CPQ setup |
Assistant Status, Company Information, and CPQ-owned setup-progress tasks |
Report a customer-facing setup state from observed-state-branches.md: Complete, Not started or incomplete, Processing, Needs attention, or Indeterminate. Do not use Sales Setup Assistant tasks as CPQ completion criteria. |
| Read and report CPQ status |
User requests CPQ Setup Assistant status |
Identify the target environment, perform exactly one direct read-only status GET with a 30-second HTTP request timeout and no retry, and report the returned state. When it is complete, offer this ready-to-use next prompt: Publish Adaptive Search for oraclecpqo_transaction and oraclecpqo_transactionLine. When it reports an error, identify the affected CPQ setup step when returned, direct the user to the Run Setup Assistant ESS job logs in the Schedule Processes UI, and advise logging an Oracle Service Request (SR) if log review does not resolve it. For a timeout or read failure, report the deterministic unable-to-determine result. Then end the request without initialization, submission, resubmission, or another mutation. |
| Initialize CPQ for a configuration workflow |
The unauthenticated deployment-version lookup does not return 404, the pre-initialization status is SETUP_NOT_DONE, and the user explicitly approves initialization |
Initialize once, then immediately rediscover. Do not confirm Legal Entity, Business Unit, or other enterprise data first. |
| Reconcile existing company data |
Company Profile state, discovered profile ID, and Setup Assistant LOV data |
Explain the state in plain language. For EXISTS and EXISTS_WITH_BU, show the eligible Legal Entity display values upfront and require a selection from that list; ask for other required choices normally. Never expose the complete LOV response or overwrite by assumption. |
| Select existing legal entity and business unit |
Setup Assistant LOV list and discovered Company Profile values |
In EXISTS and EXISTS_WITH_BU, show eligible Legal Entity display values upfront and require an explicit selection from that returned list. Preselect a discovered value only where the UI permits it; if exactly one eligible value exists, retain it and show it to the customer. Preserve a discovered default business unit when the UI would lock it. |
| Configure company information |
One discovered Company Profile and complete, validated values |
Validate the UI-equivalent fields and PATCH only the discovered Company Profile ID. Do not send an unchanged field or a value that is absent from the applicable LOV response. |
| Provision CPQ administrators |
CPQUsers is empty and the user supplies one or more validated administrators |
Before creation, require a legal entity and business unit. On the first setup run, first ask whether the current logged-in user should be a CPQ administrator; if yes, collect their details. Then ask whether to add more administrators and collect each requested user's details. Require at least one administrator with first name, last name, and a valid, unique email address. Create only approved users, then rediscover to confirm them. If a person already exists, report whether they are already a CPQ administrator, have a different resource role, or need investigation; do not create a duplicate. |
| Review seeded CPQ roles |
CPQRoleMappings |
Report the discovered role mappings. This skill does not create, delete, or remap roles because that write contract has not been verified. |
| Assess starter-data readiness |
CPQStarterDataImport and CPQ starter-data progress |
Report whether starter-data processing is unavailable, ready, running, complete, or failed. Do not import or alter starter data through this API contract. |
| Submit and request status refresh |
Required child data is present, approval covers submission, and the CPQ-specific flow is not complete |
Submit once, then immediately perform exactly one bounded read-only progress request and report the customer-facing state. Later status refreshes require an explicit user request and perform exactly one bounded read-only progress request; neither path polls or retries. Any later submission independently rediscovers authoritative Fusion state before mutation. |
| Request a rerun |
A CPQ-specific task has failed or must be repeated |
Do not clear data or initiate a rerun through this skill. Explain that rerun eligibility is task-specific and requires an approved, separately verified API contract. |
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.
1---2skill_id: "cx.configure-price-quote.company-profile.cpq-setup-assistant"3name: cpq-setup-assistant-setup-task-guidance4description: "Validates CPQ Setup Assistant state and routes approved CPQ mutations through Fusion Data Loader under the Company Profile functional area."5layer: "pillar"6pillar: "CX"7offering: "Configure Price Quote"8functional_area: "Company Profile"9functional_area_code: "ORA_SVC_COMPANY_PROFILE"10task_code: "ORA_CPQ_SETUP_ASSISTANT"11task_name: "CPQ Setup Assistant"12parent_skill_id: "cx.configure-price-quote.company-profile"13available_flag: "Y"14export_import_supported_flag: "Y"15csv_export_import_supported_flag: "Y"16source_catalog: "knowledge/setup-task-catalog/effective/setupTasksAll.json"17type: "planning"18execution_mode: "hybrid"19owner_team: "CX configure price quote pillar team"20version: "0.4.36"21inputs:22 - "implementation_objective"23 - "project_context"24 - "setup_task_scope"25 - "setup_data_artifacts"26 - "cpq_stage_proposal_and_core_preflight"27 - "cpq_task_hook_preview_input"28outputs:29 - "setup_task_plan"30 - "setup_data_routing"31 - "validation_checkpoints"32 - "cpq_setup_assistant_execution_result"33 - "cpq_data_loader_handoff"34 - "sanitized_diagnostics"35 - "skill_run_record"36 - "token_usage_record"37depends_on:38 - "core.auth.fusion-oauth-authentication"39 - "core.fusion-api.rest-api-client"40 - "core.data-loader"41 - "shared.validation.setup-data-validator"42 - "shared.validation.reference-data-validator"43uses_core:44 - "core.auth.fusion-oauth-authentication"45 - "core.fusion-api.rest-api-client"46 - "core.data-loader"47 - "core.project-mgmt.artifact-version-manager"48 - "core.project-mgmt.artifact-registry-manager"49 - "core.project-mgmt.project-state-manager"50persists_project_state: true51token_usage_tracking:52 enabled: true53 granularity: "per_skill_run"54 artifact_type: "token_usage_record"55 default_location: "project/{project_id}/artifacts/shared/token-usage/current/token-usage-log.md"56 estimation_method: "chars/4 estimate unless exact tokenizer or API accounting is available"57 required_fields:58 - "activity_start_time"59 - "skill_id"60 - "task"61 - "trigger"62 - "artifacts_written"63 - "files_read"64 - "estimated_input_tokens"65 - "estimated_output_tokens"66 - "estimated_total_tokens"67 - "estimation_method"68 - "notes"69state_updates:70 - "setup_task_sequence"71 - "configuration_blueprints"72 - "validation_results"73 - "token_usage_records"74workspace_outputs:75 - artifact_type: "configuration_blueprint"76 default_location: "project/{project_id}/artifacts/pillars/cx/configure-price-quote/company-profile/cpq-setup-assistant/current/"77 versioning_policy: "major-new-version-minor-confirm-update"78 - artifact_type: "validation_result"79 default_location: "project/{project_id}/artifacts/pillars/cx/configure-price-quote/company-profile/cpq-setup-assistant/current/"80 versioning_policy: "major-new-version-minor-confirm-update"81 - artifact_type: "other"82 default_location: "project/{project_id}/artifacts/pillars/cx/configure-price-quote/company-profile/cpq-setup-assistant/current/"83 versioning_policy: "major-new-version-minor-confirm-update"84 - artifact_type: "other"85 default_location: "project/{project_id}/artifacts/pillars/cx/configure-price-quote/company-profile/cpq-setup-assistant/diagnostics/"86 versioning_policy: "append-only"87 - artifact_type: "skill_run"88 default_location: "project/{project_id}/state/runs/"89 versioning_policy: "append-only"90 - artifact_type: "token_usage_record"91 default_location: "project/{project_id}/artifacts/shared/token-usage/current/token-usage-log.md"92 versioning_policy: "append-only"93applicability:94 industries:95 - "All"96 countries:97 - "All"98 fusion_releases:99 - "Current Oracle Fusion Cloud release"100side_effects:101 - "Retains exact recovery snapshots in owner-private local storage outside the repository and project before approval consumption; historical commands reverify ledger fingerprints."102 - "Records approval fingerprints, expiry, and consumed nonces in the project CPQ approval ledger."103 - "Validates live registration, Task Hook readiness, current CPQ state and LOVs at routed preview and pre-upload steps."104 - "Reconciles exact completed initialization/child jobs and complete approved child outcomes; retains unresolved-stage markers."105 - "Locks the target before submission, rechecks current Fusion state, and permits explicit pre-handoff recovery through a read-only check."106 - "Reads CPQ Setup Assistant state through approved read-only Fusion lookups."107 - "Initializes, configures, and submits CPQ Setup Assistant through approved Fusion Data Loader imports after explicit approval."108required_privileges:109 - "Valid Fusion OAuth access for the selected CPQ Setup Assistant environment."110metadata:111 source: https://skillmd.com/skills/oracle/cpq-setup-assistant-setup-task-guidance112---113114# CPQ Setup Assistant Setup Task Guidance115116## Purpose117118Provides task-specific planning, readiness validation, and controlled Data Loader execution guidance for `CPQ Setup Assistant` under `Company Profile`.119120## Setup Task Skill Contract121122- task_code: `ORA_CPQ_SETUP_ASSISTANT`123- task_name: `CPQ Setup Assistant`124- parent_skill_id: `cx.configure-price-quote.company-profile`125- pillar: `CX`126- offering: `Configure Price Quote`127- functional_area: `Company Profile`128- functional_area_code: `ORA_SVC_COMPANY_PROFILE`129- available_flag: `Y`130- export_import_supported_flag: `Y`131- csv_export_import_supported_flag: `Y`132- source_catalog: `knowledge/setup-task-catalog/effective/setupTasksAll.json`133134## Usage135136Use 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`.137138Use it directly when the objective explicitly concerns CPQ Setup Assistant, CPQ139onboarding or initial setup, CPQ company profile setup, or CPQ administrator140setup. These signals resolve to the following scope:141142- Pillar: `CX`143- Offering: `Configure Price Quote`144- Functional area: `Company Profile`145- Setup task: `CPQ Setup Assistant`146147If company or administrator setup is requested without CPQ or Configure Price148Quote in scope, do not assume this skill applies; resolve the offering first.149For a matching CPQ objective, use this task skill as the next action and follow150its discovery, deployment-validation, and approval gates before any mutation.151152## Setup Task Metadata153154- Task name: `CPQ Setup Assistant`155- Task code: `ORA_CPQ_SETUP_ASSISTANT`156- Available: `Y`157- Export/import supported: `Y`158- CSV export/import supported: `Y`159- CSV export/import routing: `supported`160161## Data Loader Execution Model162163The CPQ Setup Assistant is a customer-impacting configuration action. The164validated Data Loader objects are `cpqSetupAssistantInitialize` and165`setupAssistants`. The `setupAssistants` object contains the parent `Status`166field plus the `CompanyProfiles` and `CPQUsers` child sections. The compiled167registry and REST client remain read-only; they must not perform a CPQ POST or168PATCH mutation.169170## Data Loader Handoff171172### Approval ordering for every stage173174For `INITIALIZE`, `IMPORT_COMPANY_AND_ADMINS`, and `SUBMIT`, use this order:175prepare the metadata-backed immutable archive through Core Data Loader; evaluate176Task Hook readiness; build the Task Hook preview and CPQ guard manifest; present177the exact stage preview; obtain one explicit approval; record that approval and178execute once through the guard. Complete deployment/status checks before179initialization preparation, and stage-specific discovery and reconciliation180before preparing later stages.181182Readiness is eligibility to build an approval preview, not authorization to183execute. Approval remains pending during Task Hook validation and manifest184construction. Missing approval alone must not block those read-only steps or be185recorded as a passed approval check. The current stage's manifest, reviewed186binding, actor attribution, approval record, expiry and nonce are produced or187checked at their prescribed preview/approve/execute steps, not required as inputs188to readiness. Prior-stage completion and reconciliation evidence remain required189where applicable. Missing data, unsafe state, unsupported capabilities, or invalid190artifacts still block preview; no waiver or fabricated approval is implied.191192For initialization preparation, read the193[initialization registration contract](references/data-loader-registration-contract.md#initialization)194before deciding that the live action is unsupported. Evaluate the current Core195metadata and validation result; do not require optional correlation or transport196columns, or treat fields absent from Core's metadata projection as proof that197the live action is missing. Unavailable action evidence remains indeterminate198and blocks execution; it is not permission to invent a route or payload.199200Task Hook's `ready` result selects the supported assisted rule-evaluation route.201Read its execution guide and evaluate applicable CPQ registry nodes, recording202node IDs, prerequisites, outcomes and sanitized evidence through the existing203project diagnostic workflow. Aggregate the results in Task Hook's existing204ordered `ruleResults` format. A separate evaluator executable or independently205authenticated evaluator is not required by this route. Registry readiness alone206is not a passed evaluation. Keep current-stage approval pending and unrelated207stage rules `not_applicable` only when their applicability excludes them; do not208mark a missing initialization contract as passed. Build the preview through the209existing Task Hook and CPQ guard commands without constructing their outputs210manually. Include evidence references in the existing stage preview's review211context so assisted evaluation can be reviewed without claiming independent212verification or changing the approval envelope.213214Only the guard's approval and execution steps authorize a mutation. They retain215exact binding, explicit confirmation, attribution, expiry, one-time consumption,216target, live-state and reconciliation checks. Never reuse approval across stages217or ask twice for the same stage. A changed or expired preview requires fresh218validation and approval under the existing guard contract.219220Before live approval, inspect `cpq_data_loader_guard.py capabilities`. The221pillar uses explicit local approval: `liveApprovalAvailable` is true, while222`authenticated-actor` remains false. Obtain the user's explicit approval of223the exact stage preview, then record it with `--confirmed`, the exact224`--reviewed-binding`, and a nonempty caller-supplied `--actor` for audit225attribution. The actor is not independently authenticated; do not describe it226as a verified session identity or infer approval from OAuth/OS credentials.227ATEAM-1461 recommendation 3 remains unmet. This mode does not constitute an228exemption or add independent approval verification inside Core.229Requirements for authenticated identity, server-side conditional writes,230cross-host coordination, or non-bypassable Core enforcement remain unsupported;231declare them in proposal `requiredGuarantees` and stop with the capability232blocker. Never fall back to direct Core upload. See233[live validation](references/live-validation.md) for the opt-in test procedure.234235Every mutation handoff must use [cpq_data_loader_guard.py](scripts/cpq_data_loader_guard.py)236after Core Data Loader preparation and Task Validator preview. Read237[CPQ approval guard](references/cpq-approval-guard.md) before preparing the238approval. The guard separates `INITIALIZE`, `IMPORT_COMPANY_AND_ADMINS`, and239`SUBMIT`, binds the exact preview and archive, and consumes approval before240delegating to Core's existing prepared-artifact upload. Do not invoke Core's241upload command directly for CPQ mutations. Capture the existing Data Loader242user approval through this guard; do not ask twice for the same stage.243Preview creates one canonical manifest containing the stage, exact target,244ordered operations, artifact digest, administrator set, generated redacted245business summary, expiry, and nonce. Approve and execute that unchanged246manifest; nonce and expiry are never regenerated at approval.247Preview now requires `--task-input` for the Task Hook preview input and performs248the declared live metadata/state/LOV reads before creating a version 3 manifest.249The exact effective initiation settings and discovered baseline are bound to it.250At upload, [cpq_execution.py](scripts/cpq_execution.py) rechecks that live binding251and verifies actual Core upload/initiation callbacks without allowing a252routing-changing retry or token-refresh replay. Explicit approval of the exact253manifest and the durable approval controls remain mandatory.254After accepted initialization, use `reconcile-initialization` on the explicit255completion continuation; unresolved initialization blocks further mutations.256After a child-import attempt, run the guard's `reconcile` step with its consumed257child manifest and approval record. This step invokes the already-declared258`resolve_cpq_setup_assistant_record` read through Core's standard Fusion client,259first verifies successful completion of the exact recorded child load, compares260the complete expected company/admin state against the baseline plus approved261operations, and generates a ledger-verified receipt. Unexpected administrators262and changes to retained business values block reconciliation. In the `EXISTS`263and `EXISTS_WITH_BU` branches, allow only Fusion's blank-to-populated264`Addressline`, `Country`, or `TaxRegNumber` derivation after an approved Legal265Entity selection; a replaced retained value or any other unapproved change266still blocks reconciliation. Pending earlier267stages remain recorded across process exit and block later mutations. Missing, ambiguous,268incomplete, or mismatched results stop submission. Build the final parent source269and a new final manifest only after success, pass that receipt using270`--reconciliation`, and obtain the separate final-submission approval. A manually271supplied verification flag or response fingerprint is not sufficient.272At final execution, acquire the durable target submission lock atomically with273approval consumption, then use that same declared read-only lookup to compare274current Company Profile, CPQ-user, and assistant identity/status fingerprints275with the approved receipt. Stop on changed or unreadable state; never rebuild276the manifest under the old approval. The target lock blocks competing approvals277and further mutations for this setup across projects using this checkout's278shared pillar-local registry. Retain it after279accepted or uncertain handoff. On an explicit recovery request, use280`recover-submission`; it may release only a lock that has not entered Core281handoff, after a successful read-only readiness check. Recovery invalidates the282old reconciliation and never restores the consumed approval. See the guard283reference for the external-change race and checkout-local coordination limits.284285For complete company/admin reconciliation and final-state verification, use the286bounded child-collection discovery declared in `ora_reference_lookups.md`.287Read all pages and bracket them with assistant identity/status checks; reject288malformed pages, duplicate identities, incomplete reads or changed targets.289This is a finite verification step, not progress polling.290291Execution retains its exact manifest/approval in protected local recovery storage292before consuming the nonce. Historical reconciliation and inspection can use293`--attempt-id <original-nonce>` after temporary files are removed. Retention does294not authorize execution or release an uncertain attempt. Preserve evidence for295outstanding and dependent workflows; use `retain-evidence` to migrate existing296consumed attempts before deleting their original files. See the approval guard297reference for storage, migration and closure requirements. Recovery storage298provides no independent approving-user authentication or Core approval-ID299verification; those ATEAM-1461 recommendation 3 guarantees remain unavailable.300301The compiled registry is a readiness and authenticated-read graph. Its302`CPQ.INITIALIZATION_READY` and `CPQ.CONFIGURATION_READY` terminals hand off a303redacted, immutable readiness record to Core Data Loader; the terminals neither304execute nor authorize a mutation.305306After readiness and the applicable explicit approval, hand off through the307CPQ guard to `core.data-loader`. Use `cpqSetupAssistantInitialize` for initialization,308`setupAssistants` with `CompanyProfiles` and `CPQUsers` child rows for company309and administrator changes, then a parent `setupAssistants` row for final310submission with `Status` set to `SUBMITTED`. Resolve `RestAction`, parent/child311linkage, keys, and writable fields from current Data Loader metadata; do not312infer them from retired REST payloads.313Preserve source-artifact fingerprints and approval binding, but never persist314raw mutation values, OAuth tokens, or authorization headers in project artifacts.315316For the supplied registered `setupAssistants` hierarchy, apply the explicit317parent and child write contracts in318[data-loader-registration-contract.md](references/data-loader-registration-contract.md).319This registration permits a Company Profile update only through its discovered320child identity, a new CPQ administrator only with first name, last name, and321email, and final submission only through the parent patch contract. Do not322infer a child create, update, identifier, or parent-link value that the current323registration does not establish.324325### CPQ user create-field rule326327For an approved new `CPQUsers` row, resolve the complete current child328attribute template—not merely a compact generated DAT sample. Treat every329attribute marked **Mandatory** or **Required for new records** as required when330the registered child action resolves to create. In the registered CPQ-user331contract, this requires `FirstName`, `LastName`, and `Email` for every proposed332administrator.333Use the registered parent link and the registered create `RestAction` for each334child row. Do not supply `CPQUserId`, `Id`, `PartyNumber`, or `UserName` for a335new administrator merely because a template displays it as a key, surrogate,336or response attribute.337338The CPQ-specific create contract treats generated identity attributes as339server-generated even when the generic template marks them Mandatory or340Required for new records. If separate route evidence requires a caller-supplied341generated identity, or current metadata omits a required designation for any of342the three administrator fields, stop before approval with a catalog/metadata343mismatch. Do not weaken the CPQ-user contract or substitute a direct REST344mutation.345346### Loader transport-field rule347348Treat `REST-Framework-Version` and `Content-Type` as registration-controlled349transport fields, not business configuration. A generated Data Loader sample350may display `SAMPLE_VALUE` for either optional string field; that value is a351generator placeholder and is never eligible for upload. Before building the352immutable archive, resolve whether each field must be omitted or populated353from the current registered business-object metadata/template. Do not copy the354client's request defaults into a loader row and do not guess a value from a355prior REST call. `RestAction` must likewise come from current metadata; for356the initialization object, use the live registered create action only when it357resolves unambiguously. If registration metadata does not establish a required358transport-field value, stop with a catalog/metadata mismatch before approval359or upload.360361## Access and Approval Gates362363Do not check for, request confirmation of, or persist evidence about the three364legacy initial-user roles. Authentication and authorization failures returned by a365direct HTTPS call are handled as `auth/authz` failures. The remaining user gates366are explicit approval to initialize CPQ and explicit approval of the exact367post-discovery change summary before any Company Profile update, administrator368creation, or submission.369370## CPQ Deployment Preflight371372Before a configuration workflow enters Setup Assistant initialization, verify that373CPQ is deployed in the selected environment. Use the documented unauthenticated374deployment-version lookup; do not attach OAuth credentials, an `Authorization`375header, or any other authentication material. A `404` result means CPQ is not376deployed: show “CPQ is not dpeloyed in this instance and hence cannot proceed with377Setups now.” and stop without initialization or any Setup Assistant call. Any other378HTTP response confirms that the deployment endpoint is present and permits the379workflow to continue directly to the separate initialization approval and initialization. Do not expose380the endpoint, HTTP status, or transport details in the customer-facing response.381382## Customer-Facing API Disclosure Rule383384In 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.385386When 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.387388## Address Line 1 Minimum-Data Rule389390For 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.391392Follow 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.393394## Mandatory Step-by-Step Workflow3953961. **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.3972. **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.3983. **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.3994. **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](references/observed-state-branches.md).4005. **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.4016. **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.4027. **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.4038. **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.4049. **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.40510. **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](references/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](references/api-flow.md).40611. **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](references/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.407408The Data Loader path bypasses wizard-page validation. Validate required values before submission and use only IDs returned by the discovery request.409410## Partial-Failure and Safe-Resume Contract411412This contract applies when a company-profile update or administrator creation fails or has an uncertain outcome before submission is accepted.4134141. **Stop mutations and retain the consumed approval.** Do not retry an uncertain operation, advance the stage, or submit the assistant.4152. **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.4163. **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.4174. **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.4185. **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.419420If 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.421422## Discovery-Driven Use Cases423424Read [observed-state-branches.md](references/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.425426| Use case | Read evidence | Allowed outcome |427|---|---|---|428| Assess an existing CPQ setup | Assistant `Status`, Company Information, and CPQ-owned setup-progress tasks | Report a customer-facing setup state from [observed-state-branches.md](references/observed-state-branches.md): Complete, Not started or incomplete, Processing, Needs attention, or Indeterminate. Do not use Sales Setup Assistant tasks as CPQ completion criteria. |429| Read and report CPQ status | User requests CPQ Setup Assistant status | Identify the target environment, perform exactly one direct read-only status GET with a 30-second HTTP request timeout and no retry, and report the returned state. When it is complete, offer this ready-to-use next prompt: `Publish Adaptive Search for oraclecpqo_transaction and oraclecpqo_transactionLine.` When it reports an error, identify the affected CPQ setup step when returned, direct the user to the `Run Setup Assistant` ESS job logs in the Schedule Processes UI, and advise logging an Oracle Service Request (SR) if log review does not resolve it. For a timeout or read failure, report the deterministic unable-to-determine result. Then end the request without initialization, submission, resubmission, or another mutation. |430| Initialize CPQ for a configuration workflow | The unauthenticated deployment-version lookup does not return `404`, the pre-initialization status is `SETUP_NOT_DONE`, and the user explicitly approves initialization | Initialize once, then immediately rediscover. Do not confirm Legal Entity, Business Unit, or other enterprise data first. |431| Reconcile existing company data | Company Profile state, discovered profile ID, and Setup Assistant LOV data | Explain the state in plain language. For `EXISTS` and `EXISTS_WITH_BU`, show the eligible Legal Entity display values upfront and require a selection from that list; ask for other required choices normally. Never expose the complete LOV response or overwrite by assumption. |432| Select existing legal entity and business unit | Setup Assistant LOV list and discovered Company Profile values | In `EXISTS` and `EXISTS_WITH_BU`, show eligible Legal Entity display values upfront and require an explicit selection from that returned list. Preselect a discovered value only where the UI permits it; if exactly one eligible value exists, retain it and show it to the customer. Preserve a discovered default business unit when the UI would lock it. |433| Configure company information | One discovered Company Profile and complete, validated values | Validate the UI-equivalent fields and PATCH only the discovered Company Profile ID. Do not send an unchanged field or a value that is absent from the applicable LOV response. |434| Provision CPQ administrators | `CPQUsers` is empty and the user supplies one or more validated administrators | Before creation, require a legal entity and business unit. On the first setup run, first ask whether the current logged-in user should be a CPQ administrator; if yes, collect their details. Then ask whether to add more administrators and collect each requested user's details. Require at least one administrator with first name, last name, and a valid, unique email address. Create only approved users, then rediscover to confirm them. If a person already exists, report whether they are already a CPQ administrator, have a different resource role, or need investigation; do not create a duplicate. |435| Review seeded CPQ roles | `CPQRoleMappings` | Report the discovered role mappings. This skill does not create, delete, or remap roles because that write contract has not been verified. |436| Assess starter-data readiness | `CPQStarterDataImport` and CPQ starter-data progress | Report whether starter-data processing is unavailable, ready, running, complete, or failed. Do not import or alter starter data through this API contract. |437| Submit and request status refresh | Required child data is present, approval covers submission, and the CPQ-specific flow is not complete | Submit once, then immediately perform exactly one bounded read-only progress request and report the customer-facing state. Later status refreshes require an explicit user request and perform exactly one bounded read-only progress request; neither path polls or retries. Any later submission independently rediscovers authoritative Fusion state before mutation. |438| Request a rerun | A CPQ-specific task has failed or must be repeated | Do not clear data or initiate a rerun through this skill. Explain that rerun eligibility is task-specific and requires an approved, separately verified API contract. |439440Never expose implementation status codes to users. Translate every returned state using [observed-state-branches.md](references/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.441442## Inputs443444- `implementation_objective`445- `project_context`446- `setup_task_scope`447- `setup_data_artifacts`448449## Outputs450451- `setup_task_plan`452- `setup_data_routing`453- `validation_checkpoints`454- `cpq_setup_assistant_execution_result`: the latest available overall Setup Assistant status and the latest available status for each individual CPQ-owned setup task.455- `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.456- `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.457- `skill_run_record`458- `token_usage_record`459460## Implementation Notes461462Use 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.463464Release the executable guard and complete test directory with this skill, and run the [release validation](references/cpq-approval-guard.md#release-validation) against the release candidate contents.