Run Trading Community Current Record Information Maintenance
Purpose
Accept the parameters for Run Trading Community Current Record Information Maintenance in plain business language, normalize them into the fixed
five-position ESS contract, validate and preview the effective scope, and use
the existing ESS core service to submit or resume the process after all gates
pass.
Oracle displays the scheduled process as Maintain Party and Location Current Record Information. It updates the current effective profile for people,
organizations, and locations, or synchronizes HCM workers to person parties.
Setup Task and ESS Contract
- Task code:
HZ_RUN_TRADING_COMM_CURRENT_RECORD_INFO_MAINTENANCE - Application:
CrmEss - Job definition:
JobDefinition://oracle/apps/ess/cdm/foundation/parties/CurrentDateRecordSync - Submit endpoint:
POST /ess/rest/scheduler/v1/requests - Track endpoint:
GET /ess/rest/scheduler/v1/requests/{requestId} - Parameter count: exactly five positional
STRINGparameters - Client safety:
retries: 0, one POST per approval, checkpoint before polling - CSV export/import: not supported by the effective setup-task catalog
- Submission isolation: validate and submit only the request described by the current preview. Do not list, inspect, poll, or gate submission on unrelated Scheduler requests.
Use the fixed application, job definition, argument order, and transport codes. Do not derive them from display labels or the FSM task code.
| Position | Canonical field | Fixed transport contract |
|---|---|---|
submit.argument1 |
synchronization_type |
ORA_PARTY_DENORM for Party and location; ORA_PERSON_SYNC for Worker |
submit.argument2 |
person_type |
EMP, CWK, PWK, EX_EMP, EX_CWK, EX_PWK, NONW, EX_NONW, PURGED, or blank |
submit.argument3 |
from_date |
Valid YYYY-MM-DD date or blank |
submit.argument4 |
to_date |
Valid YYYY-MM-DD date or blank |
submit.argument5 |
person_numbers |
One or more comma-separated person numbers, or blank |
Preserve all five positions. For an unset value, include the parameter object
without a value property. Do not send JSON null, an empty string, or #NULL.
Inputs
job_parameters_text: plain-language process settings.fusion_environment_context: exact target Fusion environment; resolve it only when exactly one configured environment is active.project_id: required for live submission so the approval preview, payload, and request checkpoint survive interruption.execution_intent:previeworexecute. Retain an initial run instruction while collecting missing parameters, but do not treat it as final approval.execution_approval: explicit confirmation given after the consolidated preview. Bind it to the target environment, operation, payload fingerprint, and correlation description.execution_options: optional boundedwait_secondsandpoll_interval.request_id: optional positive ESS request ID used only to resume tracking.
Plain-Text Normalization
Normalize the user's text into this canonical model before invoking the builder:
| Canonical field | Requirement | Accepted canonical values |
|---|---|---|
synchronization_type |
Required | ORA_PARTY_DENORM, ORA_PERSON_SYNC |
person_type |
Optional; Worker only | One fixed person-type code |
from_date |
Optional pair; Worker only | ISO YYYY-MM-DD |
to_date |
Optional pair; Worker only | ISO YYYY-MM-DD |
person_numbers |
Optional; Worker only | Comma- or whitespace-separated values |
Use these conventional English mappings:
| Conventional label | Fixed code |
|---|---|
| Employee | EMP |
| Contingent Worker | CWK |
| Pending Worker | PWK |
| Ex-Employee | EX_EMP |
| Ex-Contingent Worker | EX_CWK |
| Ex-Pending Worker | EX_PWK |
| Nonworker | NONW |
| Ex-Nonworker | EX_NONW |
| Purged Worker | PURGED |
The first eight visible person-type labels come from the environment's
PER_PERSON_TYPES_TL.USER_PERSON_TYPE and can vary by customer and language.
Treat the codes as fixed. Use the conventional mappings only when the English
label is unambiguous; for an unfamiliar localized or configured label, request
the fixed code rather than guessing. PURGED and its Purged Worker label are
defined directly by the process view object.
Normalize spaces and commas between person numbers to one comma. Preserve the token text and order, including leading zeroes. Do not deduplicate or expand ranges.
Parameter Intake
On a bare invocation, ask once:
Please provide the maintenance settings.
- Synchronization: Party and location, or Worker
- For Worker only, optionally provide one of these scopes:
- Person type
- From and To dates in YYYY-MM-DD format
- One or more person numbers
Apply these rules:
- Require an explicit synchronization type for predictable automation. Although Fusion technically accepts a blank value and runs both branches, do not use that implicit combined scope in an automated request.
- Do not ask for Worker filters when Party and location is selected.
- Do not ask a second round of optional questions after the required synchronization type is known. Unspecified Worker filters remain blank.
- Preserve an initial execution intent while collecting missing values, but require approval after showing the resolved preview.
- Stop and clarify ambiguous dates, localized person-type labels without a fixed code, or an unresolved target environment.
Deterministic Payload Builder
Write the canonical object to a temporary or project-local JSON file and run from the repository root:
python3 pillars/cx/customer-data-management/trading-community-foundation/run-trading-community-current-record-information-maintenance/scripts/build_current_record_request.py \
--input <canonical-parameters.json> \
--description "FDOS:current-record-maintenance:<project_id>:<run_id>" \
--payload-output <ess-request.json> \
--report-output <request-preview.json>
The builder writes the executable Scheduler payload separately from the full
preview. It fails closed when an output exists. Use a new run path, or use
--force only after explicit overwrite approval. Never let an output replace
the canonical input or let the payload and report share a path.
Validation and Effective-Scope Rules
- Require
synchronization_typeand accept only the two fixed codes. - For
ORA_PARTY_DENORM, require arguments 2 through 5 to remain blank. - For
ORA_PERSON_SYNC, allow person type, date range, and person numbers to remain blank; that means all applicable worker types without those filters. - Require From Date and To Date together or leave both blank.
- Require valid ISO dates and
from_date <= to_date. - Treat To Date as inclusive. Send the entered value unchanged; disclose that the package internally adds one day.
- Validate person type against the nine fixed codes.
- When person numbers are supplied, treat them as the effective selection.
Person type and date values may remain in their positional arguments, but
report them in
ignored_parametersand disclose that the package gives person numbers precedence. - Reject unknown canonical fields, empty person-number lists, ambiguous synchronization values, and unsupported argument combinations before any side effect.
Preview and Approval
Always persist and show one consolidated business preview before submission:
Maintain Party and Location Current Record Information
- Environment: <environment name and host>
- Synchronization: <Party and location or Worker> (<fixed code>)
- Person type: <conventional label and code, or Not specified>
- Date range: <from> through <to> inclusive, or Not specified
- Person numbers: <normalized values, or Not specified>
- Effective selection: <party/location, worker filters, all applicable workers, or listed person numbers>
- Ignored because person numbers take precedence: <fields, or None>
- Status tracking: <bounded wait and poll interval>
Submit this exact ESS request to the environment above? Reply Yes to approve this one submission, or tell me what to change.
Do not expose application names, job-definition paths, positional argument names, core skill IDs, or checkpoint paths in the normal business preview. Persist them in the technical preview and show them on request or for diagnosis.
Require explicit approval after presenting the exact target, operation, and
payload-derived scope. An earlier run, submit, or proceed instruction is
execution intent, not approval for the final payload. Invalidate approval when
the environment, any parameter, the payload fingerprint, or the correlation
description changes.
Preflight Gates
Before live submission:
- Require the exact environment identity, required role or privilege, project path, canonical input, payload, approval binding, and writeable artifact paths.
- Do not query the Scheduler collection or inspect any existing request before submission. Existing, queued, running, or completed requests are outside this skill run and must not block the approved request.
- When active current/past Employee or Contingent Worker synchronization is
explicitly intended, surface the Full Mode prerequisite: both
ORA_HZ_ENABLE_MPLCRI_ACTIVE_WORKERandHRC_DISABLE_HCM_EVENTS_PROCESSINGmust be enabled. Do not modify these profile options in this skill. Warn that enablingHRC_DISABLE_HCM_EVENTS_PROCESSINGdisables HCM events and should be limited to a tightly controlled interval. - Never substitute browser automation, direct REST, a loader, or an import route for the declared ESS workflow.
Live Execution
Use the two-phase pattern:
- Treat the approved payload as the only request in scope. Do not list or inspect other Scheduler jobs before the POST.
- Persist normalized parameters, effective selection, ignored parameters, exact payload, payload fingerprint, correlation description, environment, approval evidence, and UTC submission window under the declared artifact folder.
- Invoke
core.fusion-api.ess-job-submitterwith the generated--payload-file,--submit-only,--retries 0, and--outputpointing toess-submission-checkpoint.json. - Require one positive
execution_result.requestId. Persist and report it before polling. - Invoke the core skill separately with
--request-id <requestId>, bounded--wait-seconds,--poll-interval, and--outputpointing toess-execution-result.json. - Poll only the request ID returned by this submission. Never query or track a different request as part of the current run.
- Never combine submission and long polling in one process. Never automatically repeat the submission POST.
- On timeout, retain the same request ID and resume tracking only when asked.
- When
request_idis supplied, reconcile it to this exact application and job definition, then track only. Do not rebuild or resubmit the request.
Uncertain Submission Recovery
If submission may have reached Fusion but the checkpoint is missing or
unreadable, do not submit again. Use core.fusion-api.rest-api-client for a
workflow-selected read-only Scheduler query using:
- exact correlation description
- application
CrmEss - exact
CurrentDateRecordSyncjob definition - UTC submission window
- complete five-position parameter contract
Accept recovery only when exactly one request matches. Persist its request ID
before polling. Treat zero or multiple matches as approval_blocker; do not
issue a replacement POST.
Errors and Diagnostics
Classify failures as input_validation, catalog_or_metadata_mismatch,
auth_expired_or_invalid, authorization_or_privilege,
transport_or_environment, fusion_api_error, process_timeout,
process_failed, artifact_persistence, or approval_blocker.
On timeout or failure, persist and report the environment, stage, task code, application, job definition, request ID and ECID when available, last ESS state, elapsed time, safe Fusion message, artifact references, and recommended resume or correction action. Retrieve and persist the process log or status payload when available.
Refresh a cache-managed token after 401 or 403 at most once. Never retry a live POST without reconciliation and new explicit approval. Never print or persist credentials, tokens, token-cache contents, authorization headers, private keys, or sensitive worker data.
References
- Oracle scheduled-process behavior and parameters:
https://docs.oracle.com/en/cloud/saas/sales/fasqa/maintain-party-and-location-current-record-information.html - Oracle Scheduler REST submission contract:
https://docs.oracle.com/en/cloud/saas/applications-common/26b/farca/op-ess-rest-scheduler-v1-requests-post.html