ballerinax/oraclefusion.common.scheduler Ballerina library

Overview

Oracle Fusion Cloud Applications run their long-running background work — data imports, reports, period-close processes — as scheduled processes on the Enterprise Scheduler Service (ESS).

The generic Scheduler REST API (introduced in Oracle Fusion release 23B) is the entry point for that work. It submits job requests against a job definition, queries requests with a SCIM-style filter, and reports the execution state of an individual request.

Key Features

• Submit a scheduled process against a job definition, with its job-specific request parameters, priority, retries, request timeout, and log level
• Query job requests with SCIM-style filters (for example, state eq "RUNNING"), response field shaping via fields/excludeFields, request-ID selection, and ordering
• Poll an individual request for its execution state, state description, submission and processing timestamps, elapsed time, and the parameters it was submitted with
• Schedule recurring runs inline with iCal recurrence rules, a timezone, and date exclusions or inclusions — or reference an existing schedule by ID
• Register a callback subscription so the scheduler notifies your endpoint as the request changes state, as an alternative to polling
• Flexible authentication: HTTP Basic with Fusion integration user credentials, or OAuth2 client credentials against Oracle Identity Cloud Service (IDCS)
• GraalVM compatible for native image builds

Setup guide

Step 1: Identify your Fusion instance base URL

The Scheduler base URL is instance-specific and takes the form:

https://{fusionHost}/ess/rest/scheduler/v1

For example: https://acme.fa.us2.oraclecloud.com/ess/rest/scheduler/v1

Note: The generic Scheduler REST API is available from Oracle Fusion release 23B onwards. On earlier releases, use the product-specific ESS endpoints instead.

Step 2: Provision a user with the required privileges

1. Sign in to your Oracle Fusion Cloud instance as a user with security administration rights.
2. Create (or identify) the integration user that will submit and monitor the processes.
3. Grant the roles required for the scheduled processes you intend to run. Submitting a process requires the privileges of that specific job definition; monitoring requires the privileges to view scheduled processes. Consult your Fusion security administrator for the exact roles for your module.

Step 3: Identify the job definition to submit

Submitting a request takes a jobDefinitionId — the metadata object ID of the process, not its display name. It has the form:

oracle/apps/ess/financials/payables/invoices/transactions/ImportPayablesInvoicesJob

Find it in the Fusion UI under Tools > Scheduled Processes, or ask your functional administrator. The job-specific requestParameters are defined by the job definition, so confirm their names, order, and types for the process you intend to run.

Step 4: Choose an authentication scheme

The connector supports both of the schemes the service accepts. ConnectionConfig.auth is a union, so the choice is a configuration change rather than a code change.

HTTP Basic over HTTPS, using a Fusion integration user's credentials:

final scheduler:Client schedulerClient = check new ({auth: {username, password}}, serviceUrl);

OAuth2 client credentials, for instances that reject Basic auth. Register a confidential application in Oracle Identity Cloud Service (IDCS), grant it access to the Scheduler resource, and use its client id and secret:

final scheduler:Client schedulerClient = check new ({
    auth: {
        clientId,
        clientSecret,
        tokenUrl: "https://<your-idcs-host>.identity.oraclecloud.com/oauth2/v1/token"
    }
}, serviceUrl);

Ask your Fusion administrator which scheme the instance is configured for — some pods disable Basic auth for integration users.

Quickstart

To use the oraclefusion.common.scheduler connector in your Ballerina application, modify the .bal file as follows:

Step 1: Import the module

import ballerina/io;
import ballerinax/oraclefusion.common.scheduler;

Step 2: Instantiate a new connector

1. Create a Config.toml file and configure the obtained credentials in the above steps as follows:

   serviceUrl = "https://<fusionHost>/ess/rest/scheduler/v1"
   username = "<your-fusion-username>"
   password = "<your-fusion-password>"

2. Create a scheduler:Client with the configuration.

   configurable string serviceUrl = ?;
   configurable string username = ?;
   configurable string password = ?;
   
   final scheduler:Client schedulerClient = check new ({auth: {username, password}}, serviceUrl);

Step 3: Invoke the connector operation

Now, utilize the available connector operations. The following snippet lists the scheduled processes that are currently running:

public function main() returns error? {
    scheduler:RequestQueryResponse response = check schedulerClient->queryJobRequests(
        queries = {q: "state eq \"RUNNING\"", orderBy: "submissionTime:desc"}
    );
    io:println(response);
}

Step 4: Run the Ballerina application

bal run

Examples

The Oraclefusion.common.scheduler connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

1. Submit and track job - Submit a scheduled process and poll the resulting request until it reaches a terminal state, then report the final execution outcome.
2. Monitor scheduled processes - Build an operational view over scheduled processes: list running requests, find the ones in the ERROR state, and drill into the most recent of those for its parameters and error detail.