ESS Job Submitter

ESS Job Submitter

Purpose

Provides the ESS job submitter core capability for Oracle Fusion Cloud implementation workflows.

Canonical ESS Delegation Contract

Accept only a validated approved_submission conforming to schemas/ess-delegation-contract.schema.json version 1.0. Require the approved immutable request_payload, job contract, target environment, polling options, and approval hash. This core skill does not classify FSM tasks, choose business defaults, construct a payload, or obtain approval; it submits and tracks the exact approved payload.

When to Use

Use this core skill when another router, shared, or pillar skill needs to run an Oracle Fusion ESS scheduled process and track its result. Any implementation activity that submits, monitors, or resumes tracking an ESS job should call this skill instead of duplicating REST authentication, request submission, or polling logic.

REST API Contract

This skill uses the Oracle Fusion Scheduler REST API:

• Submit: POST /ess/rest/scheduler/v1/requests
• Track: GET /ess/rest/scheduler/v1/requests/{requestId}

The submit response returns an ESS request identifier as id; the tracking call uses that value as requestId. The payload supports the Oracle request fields such as jobDefinitionId, requestParameters, application, description, priority, retries, requestTimeout, schedule, scheduleId, startTime, and endTime.

Do not use callbackSubscription for now. The implementation rejects payloads that include it so all callers use the async submit-and-poll flow consistently.

Project Scripts

Run from the repository root:

bashCopy code
python3 core/fusion-api/ess-job-submitter/scripts/ess_job_submitter.py \
  --job-definition-id oracle/apps/ess/somePackage/someJob \
  --application someApplication \
  --parameter Param1=STRING=value1 \
  --wait-seconds 600 \
  --poll-interval 15 \
  --token-cache auto

Submit with an exact Oracle payload:

bashCopy code
python3 core/fusion-api/ess-job-submitter/scripts/ess_job_submitter.py \
  --payload-file request.json \
  --wait-seconds 600 \
  --token-cache auto

Resume tracking an existing ESS request:

bashCopy code
python3 core/fusion-api/ess-job-submitter/scripts/ess_job_submitter.py \
  --request-id 123456789 \
  --wait-seconds 300 \
  --token-cache auto

The script reads the default Fusion environment properties file:

textCopy code
core/auth/fusionEnv.properties

It imports OAuth helpers from:

textCopy code
core/auth/fusion-oauth-authentication/scripts/fusion_auth.py

If the cached token is missing, expired, or rejected by Fusion with HTTP 401 or 403, the script invokes core.auth.fusion-oauth-authentication to obtain a fresh token, saves it to the requested cache, and retries the ESS API call once.

Inputs

• ess_delegation_contract: a validated approved_submission envelope conforming to schemas/ess-delegation-contract.schema.json version 1.0. The core adapter extracts its fusion_environment_context, exact request_payload, and execution_options only after validation; callers must not provide those as independent skill-level inputs.

Script-level adapter inputs (internal mapping from the validated envelope):

• --payload or --payload-file: complete JSON submit payload.
• --job-definition-id: convenience input for jobDefinitionId.
• --application, --description, --product, --request-category, --request-log-level, --priority, --retries, --request-timeout, --start-time, --end-time, and --schedule-id: convenience inputs mapped into the submit payload.
• --parameter: repeated parameter as name=value or name=TYPE=value, where TYPE is BOOLEAN, LONG, INTEGER, DATETIME, or STRING.
• --request-id: track an existing ESS request instead of submitting a new one.
• --find-recent-job-definition with --since-minutes: read-only lookup for recent requests matching one exact job definition. Use only when the active workflow selects recovery lookup and the user explicitly asks to check.
• --wait-seconds: maximum polling time, default 300.
• --poll-interval: seconds between status calls, default 10.
• --submit-only: submit the request and return the requestId without polling.
• --full-status: return the full tracking payload rather than a compact field set.
• --output: write structured result JSON to a file.
• --token-cache: file token cache path, defaulting to the managed external profile cache.
• --force-login, --auth-code, --redirect-url, and browser flags passed to the shared OAuth flow when login is required.

Outputs

• execution_result
• diagnostics
• audit_summary

Script-level outputs:

• Structured JSON with execution_result, diagnostics, and audit_summary.
• When --output is supplied, the submitter writes a redacted structured failure result even when it cannot obtain an ESS request ID. Callers must collect that artifact before classifying an outcome as indeterminate.
• execution_result.requestId contains the ESS request identifier.
• execution_result.status contains a compact status summary with state, process phase, cause, completion time, elapsed time, ECID, and any error or warning message returned by Fusion.
• Exit code 0: submitted/tracked successfully or non-terminal status returned when no wait was requested.
• Exit code 3: wait timeout elapsed before a terminal ESS status.
• Exit code 4: Fusion reported a terminal unsuccessful ESS status.

Implementation Notes

Use the bundled script or import core/fusion-api/ess-job-submitter/scripts/ess_job_submitter.py from consuming skills instead of writing endpoint-specific ESS code.

The implementation records the target environment, submit response, requestId, status summary, and polling diagnostics. It does not print access tokens, refresh tokens, client secrets, .fusionaim_token.json contents, or Authorization headers.

Authenticated REST requests are restricted to HTTPS hosts configured by restBaseUrl or *_restBaseUrl in core/auth/fusionEnv.properties; other hosts and redirects to them are rejected.

For mutating invocations, consuming skills must include the ESS requestId, job definition, request purpose, target environment, and terminal status in their own audit artifacts.