Add Other Data Sources Setup Task Guidance
Purpose
Provides task-specific setup planning, routing, export, import, and validation guidance for Add Other Data Sources under Add Other Data Sources.
Setup Task Skill Contract
- task_code:
ORA_GTG_ADD_OTHER_DATA_SOURCES - task_name:
Add Other Data Sources - parent_skill_id:
erp.risk-and-security.add-other-data-sources - pillar:
ERP - offering:
Risk and Security - functional_area:
Add Other Data Sources - functional_area_code:
ORA_GTG_ADD_OTHER_DATA_SOURCES - available_flag:
Y - export_import_supported_flag:
UNKNOWN - csv_export_import_supported_flag:
UNKNOWN - dataloader_import_mode:
REST - source_catalog:
knowledge/setup-task-catalog/effective/setupTasksAll.json
Usage
Use this skill when planning, sequencing, exporting, importing, or validating setup data for Add Other Data Sources under Add Other Data Sources.
Setup Task Metadata
- Task name:
Add Other Data Sources - Task code:
ORA_GTG_ADD_OTHER_DATA_SOURCES - Available:
Y - Export/import supported:
UNKNOWN - CSV export/import supported:
UNKNOWN - CSV export/import routing:
not catalog-supported - Data Loader import mode:
REST
CSV Export, Import, and Validation Workflow
CSVExportImportSupportedFlag is UNKNOWN, so this task is not marked as CSV export/import supported in the effective setup-task catalog.
Do not route CSV export work to shared.setup-export.task-level-export or CSV import work to core.data-loader unless live Fusion metadata or Oracle guidance confirms support. Use shared.validation.setup-data-validator only when a setup data artifact is available for review. Use shared.validation.reference-data-validator when the task depends on cross-pillar reference data.
Hybrid Execution Preflight Checks
Complete these checks before the preview creates an approval artifact and repeat the execution-specific checks immediately before the REST POST. Stop on any failed, missing, or ambiguous check; do not use another client, endpoint, or target as a fallback.
- Confirm
project_contextresolves to an initialized FSCR project workspace when preview, execution, Run Book completion, or durable artifacts are in scope. Confirm the declared project artifact paths are writable without an unapproved overwrite. - Confirm the connector type has one valid local profile and a matching
sourceTypeNameandsourceTypeCodeinconnector-source-types.json. Confirm the documentation-backed OpenAPI input and extracted REST Operations pass their respective validation before payload generation. - Confirm the target is an explicit HTTPS Fusion base URL, the only mutation
route is
POST /api/risk-cloud/rc-tools-ms/dataintegration/v1/dataIntegratorConnectorDefinitions, and the approved Risk Cloud client,rmc_scope, and create/read privileges are available for the target environment. - Confirm the generated payload is credential-free, recursively rejects prohibited fields, uses only profile-allowlisted setup keys, and contains no undocumented setup values. Preview may write only review artifacts; it must not call Fusion.
- Before execution, confirm a clear, contextual user approval exists for the exact persisted artifact. Recalculate the approval-envelope digest and require the target, method, endpoint, and payload to match the approval artifact.
- Before execution, require
restBaseUrlin the supplied properties file to equal the approval-bound target after URL normalization. The runner fails closed on mismatch before it writes a request body or sends the POST. - Before Run Book completion, confirm the exact registered connector is
COMPLETEDandACTIVE, the project task context resolves the exact task code, and the originating request includes configuration or task completion.
Failure Handling and Redaction
Classify every failure using the task-local
ora_error_handling.md contract. On an
input, catalog, target-binding, privilege, payload, or approval failure, stop
before the POST, retain only sanitized diagnostic metadata, and report the next
safe action. Refresh a cached token at most once for a recoverable 401/403
read-only check; never retry a connector-definition POST or an indeterminate
Run Book PATCH without fresh approval or an idempotency guarantee. On an
uncertain POST, use the declared read-only BOSS verification path before any
new preview.
Redact and never print or persist credentials, authenticationDetails, client
secrets, bearer or refresh tokens, private keys, complete authorization
headers, token-cache contents, or full untrusted response bodies. Persist only
the approved credential-free payload, digest, target, method, endpoint,
sanitized HTTP status, connector identifier, and next safe action in the
declared project artifacts.
REST connector-definition workflow
This task uses the Risk Cloud REST connector-definition POST. It does not use a Data Loader business object or Data Loader upload/initiation.
Resolve the connector type and load its profile from
connector-profiles/. New connector types add a profile rather than a new orchestration branch. ResolvesourceTypeNameandsourceTypeCodefrom the parent functional area'sconnector-source-types.json; do not accept either value as a task-local runtime input.Use
references/generate-openapi-spec.mdto discover and validate the connector's OpenAPI JSON. OCI is a temporary, explicitly scoped exception: use the validated pinned document atreferences/oci-openapi-spec.jsonas directed by that workflow. For every other connector, if discovery cannot establish a usable, documentation-backed specification, stop and request the required documentation or clarification; do not use a local sample or fallback.Use
references/extract-operations.mdto derive the completeREST Operationscontract from the validated OpenAPI JSON. Keep both contracts in memory until preview creates the approval-bound payload artifact.Convert the extracted operations into connector extraction objects and source endpoints, then build the connector-definition payload:
python3 scripts/run_connector_definition.py format \ --operations <rest-operations.json> \ --output <formatted-operations.json>Validate the complete credential-free payload, target environment, and endpoint before any write. Reject credentials,
authenticationDetails, bearer tokens, refresh tokens, private keys, and undocumented setup keys. Persist the exact payload, canonical target URL, method, endpoint, resolved project workspace, approval version, and approval-envelope SHA-256 digest as an approval-bound project artifact. Do not POST during preview:python3 scripts/run_connector_definition.py preview \ --operations <rest-operations.json> \ --openapi-spec <discovered-openapi.json> \ --profile connector-profiles/<connector-type>.json \ --connector-name <connector-name> \ --connector-setup-json <connector-setup.json> \ --target-url <fusion-base-url> \ --project-root <project-root>After a later clear approval, execute the unchanged approval artifact once:
python3 scripts/run_connector_definition.py execute \ --approval-state <approval-state> \ --approve-digest <approved-digest> \ --project-root <project-root> \ --properties <fusion-properties-file>Return the sanitized HTTP result and server request/connector identifier. When an exact connector identifier is returned, present the connector setup page for the user to enter credentials:
{restBaseUrl}/fscmUI/redwood/rc-dataintegration/rc-ai-datasource/connector-authentication?connectorId=<connector_id>&connectorType=OCINever retry an uncertain POST. Instead, use the exact read-only BOSS registration recovery query below to reconcile the original attempt.
Predefined Data Source Readiness
Use the following GET through the approved BOSS client for predefined-source
readiness. Resolve source_type_name from the selected connector type in the
central registry; only this value is dynamic. The existing OCI prerequisite
applies to OCI; USER-DEFINED continues to skip that seeded-source prerequisite.
GET /api/boss/data/objects/ora/riskMgmtRisk/dataIntegration/v1/connectorDefinitions?$filter=creationStatus='COMPLETED' and connectorStatus='ACTIVE' and sourceTypeName='<source_type_name>'&$includeTotalItems=true&$limit=1&$fields=id
python3 core/fusion-api/rest-api-client/scripts/boss-rest_client.py \
/api/boss/data/objects/ora/riskMgmtRisk/dataIntegration/v1/connectorDefinitions \
--method GET \
--query "\$filter=creationStatus='COMPLETED' and connectorStatus='ACTIVE' and sourceTypeName='${source_type_name}'" \
--query '$includeTotalItems=true' \
--query '$limit=1' \
--query '$fields=id' \
--properties <boss-properties-file> \
--output <seeded-query-response.json>
Use boss_scope and its separate local token cache. A successful response with
at least one record containing an id confirms the selected predefined data
source is set up. The server filter establishes readiness, so status fields
need not appear in the projected record. This is an existence check: no
pagination or unique-match requirement applies once a record is returned.
An empty items array means no ready match was found. Stop downstream work and
ask the user to complete setup in the Data Integration UI. It does not prove
that a pending connector is absent. A failed request, missing or malformed
items, or a record without an id blocks readiness. Neither hasMore nor a
total count alone proves setup.
Connector Registration Verification and Recovery
The predefined-source query above does not verify a newly registered connector: it can return an unrelated ready connector and it excludes unfinished records. Never use its result to authorize recreation or Run Book completion.
After an uncertain POST or a user-requested post-setup status check, use the approved BOSS client for a separate GET collection read filtered only by the centrally resolved source type. Include unfinished records:
python3 core/fusion-api/rest-api-client/scripts/boss-rest_client.py \
/api/boss/data/objects/ora/riskMgmtRisk/dataIntegration/v1/connectorDefinitions \
--method GET \
--query "\$filter=sourceTypeName='${source_type_name}'" \
--query '$includeTotalItems=true' \
--query '$limit=100' \
--query '$fields=id,name,creationStatus,connectorStatus' \
--properties <boss-properties-file> \
--output <connector-verification-response.json>
The BOSS resource does not support name in its server-side filter; perform
name matching locally. Match the retained registration ID when available; otherwise select an exact
approved connector-name match locally. Require valid records and explicit
Boolean hasMore=false before deciding from this collection. Missing identity,
malformed results, hasMore=true, or multiple exact matches block recovery;
do not select arbitrarily or replay the POST. If the required read contract is
rejected by the service, report the contract gap and stop without a fallback.
- No exact match: the outcome remains unresolved. Keep the task open and retain sanitized diagnostics for read-only reconciliation. Do not infer that the original POST failed or rebuild a creation preview based on this result.
- One exact match not both
COMPLETEDandACTIVE: present the existing connector's setup URL, keep the task open, and wait for setup and a later user-requested status check. Do not submit another registration. - One exact match both
COMPLETEDandACTIVE: verification succeeds; continue to Run Book completion only when the originating request includes it.
Persist only the exact connector ID, status fields, HTTP status, target and next safe action. Any subsequent creation requires independent reconciliation of the original attempt and fresh approval; neither query authorizes an automatic retry.
Run Book Completion Handoff
After the final REST workflow result is verified successful, invoke
core.runbook to complete the linked Add Other Data Sources task. This step
applies when the originating request asks to configure or complete the task;
preview-only, readiness-only, and contract-only requests stop after their
declared result.
Resolve the active Run Book and the exact task code
ORA_GTG_ADD_OTHER_DATA_SOURCES from the initialized project's task context.
Set the task status to completed and completion percentage to 100, then
persist the refreshed task detail and the update result in the skill-run
record. A successful HTTP response alone is not sufficient when the connector
registration result is uncertain or the required verification artifact is
missing.
If the Run Book PATCH fails or is indeterminate, preserve the successful REST result, record that the Run Book task was not updated, and do not retry the PATCH automatically.
The generic reference procedures are in references/: OpenAPI generation,
operation extraction, connector authentication configuration, mapping, and
function generation. They are connector-neutral and may be reused by every
profile.
The REST execution route owns approval immediately before the mutation. Do not request a second Data Loader approval or upload a loader artifact.
Inputs
implementation_objectiveproject_contextsetup_task_scopesetup_data_artifacts
Outputs
setup_task_plansetup_data_routingvalidation_checkpointsskill_run_recordtoken_usage_record
Implementation Notes
Use the parent functional-area skill erp.risk-and-security.add-other-data-sources for functional-area sequencing and scope decisions. Track token usage for any generated project artifact or skill-run record using the manifest policy.
Approval envelope integrity
The runner hashes the canonical version-2 approval envelope: target URL
(the environment identity), HTTP method, endpoint, resolved project workspace
path, and complete credential-free payload. The digest field itself is excluded.
Execution requires --project-root <selected-project-root> alongside
--approval-state, --approve-digest, and --properties. The selected workspace
must match the envelope, and the selected connection's restBaseUrl must match
the approved target immediately before dispatch. Changed envelopes, mismatched
connections, and legacy payload-only approvals fail closed. Regenerate the
preview and obtain fresh approval; never upgrade an old approval in place.
Retained approval previews
Each preview creates a new current/approvals/preview-<unique-id>/ directory
containing its approval JSON and Markdown summary (and the EPM OpenAPI file
when applicable). Files are created exclusively and never replaced by another
preview. Existing files at the old fixed paths are left intact.
Only current/latest-approval.json is replaced atomically, after every file in
the new preview has been written successfully. It points to the latest preview
for discovery; it is not an approval artifact or an execution input. Link the
versioned files returned by the runner, retain the exact approvalState path
and digest that the user reviewed, and execute that path even if a later
preview changes the pointer. A later preview does not grant approval, revoke
an earlier approval, or authorize replay of a submitted operation.
Artifact path and overwrite protection
Both connector runners use the functional-area ../scripts/connector_artifacts.py
helper. Preview and execution artifacts must remain inside the selected initialized
project workspace. Symlinked artifact directories, approval files, payload files,
and current pointers are rejected, including links that point inside the workspace.
Directories are opened without following symlinks, and artifact files are created
exclusively with mode 0600. Only the regular current pointer is replaced atomically.
Execution creates the derived .payload.json beside the approved versioned JSON.
If that destination already exists, execution stops before dispatch and preserves
the existing file. Do not delete it to retry a possibly submitted POST. Reconcile
the prior result through the documented recovery route; obtain a new preview and
approval only when a new submission has been established as appropriate.