This chapter describes how to manage Oracle Enterprise Scheduler job requests, creating and submitting them, as well as holding and canceling them as required.
Job requests do work on behalf of an application. A job request consists of the job execution type, such as Java job or PL/SQL job, a job definition that associates metadata for specifics about the request, and a schedule that guides when the job runs. Managing job requests can mean creating and submitting them, but also holding and canceling them, as well as doing clean-up by purging requests from the database.
Note:
You can also use Oracle WebLogic Scripting Tool to perform request management tasks. For more information, see "Enterprise Scheduler Custom WLST Commands" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
This chapter includes the following sections:
Using Fusion Middleware Control Console, you can manage the job requests that do work on behalf of applications for which Oracle Enterprise Scheduler is providing services. Tasks related to managing job requests include creating job requests and specifying the schedules on which they run. You can submit the requests, as well as hold and cancel them.
Job request administration tasks you might need to perform include:
Creating job requests by associating request-specific metadata as job definitions, then defining schedules that guide when the job runs.
Holding, resuming, and canceling requests.
Purging job requests from the database.
An application uses Oracle Enterprise Scheduler to execute jobs on the application's behalf. When the application wants to execute a job, it sends a job request to Oracle Enterprise Scheduler. You configure those jobs by using job definitions that specify the job's parameters and associate them with the application. When you want to group together a collection of job requests, you create a job set.
The work of administering job requests includes submitting requests, searching for existing requests and viewing information about them, and pausing and canceling requests. You can do these tasks with Fusion Middleware Control Console.
This section contains the following topics:
You can submit a job request by choosing a job definition that defines the metadata you want and by defining a schedule that guides when the job runs.
This section contains the following topics:
You create a job request by selecting a job definition for the job request, then selecting or creating a schedule.
You may want to configure system properties for the job request, such as the number of retries to attempt in the event of an execution error and a time out value for the job.
To submit a job request:
Use a pre-existing job definition. You can also first create a new job definition, as described in Creating or Editing a Job Definition.
Navigate to the Submit Job Request page by clicking the Scheduling Service menu selecting Job Requests, then selecting Submit Job Request.
Select the application for which you want to submit the job request.
From the Application dropdown list, select the application deployment name.
Under Job Request Details, enter a description of the job request in the Submission Notes text field.
Select a job definition.
Under Job Definition, click the search button next to the Job Definition text field.
Search for the required job definition.
In the Name text field, enter the name of the job definition you want to find. You can also enter the job definition's package in the Package field.
Click Go to search for the job definition.
From the search results table, select the job definition name.
Click OK.
In the Parameters region, optionally define any parameters you want to use with the scheduled job request.
In the Job Parameters region, click Add to add a parameter.
Fill in a name and value for the parameter.
You can set a value for any of the system properties available.
For example, you may want to configure the number of permissible retries for the job (SYS_retries), or a time out value (SYS_request_timeout).
Select a schedule by which the job is to run.
Once: Select a single date and time by clicking the Calendar button.
Use existing schedule: Click the search button to search for and select an existing schedule. For more on defining saved schedules, see Creating or Editing Predefined Job Schedules.
Specify schedule: Create your own schedule on the fly. Follow the instructions in Specifying a Job Request Schedule
Click OK.
In the Submit Job Request page, selecting Specify schedule enables configuring your own schedule for a job request. You can configure a recurring job request using a job request schedule. Alternatively, you can configure a job request to run immediately or before a specified end date. Use a pre-existing job definition, or create a new job definition, as described in Creating or Editing a Job Definition.
To specify a schedule:
The Request Search page enables searching for job requests. Using the Request Search page, you can:
Conduct a quick search by selecting a pre-configured search option from the Quick Search dropdown menu.
Conduct a basic search that returns a list of job request details, including job request ID, executing application, job request status, and so on.
Conduct an advanced search based on Run Time/Wait Time, Retry of Failed Runs, Date Range, Error Type and Request ECID/Correlation Flow ID along with the fields available as part of Basic Search.
Modify the column display in the search results table.
This section contains the following topics:
Basic search allows you to find a job request according to particular criteria such as job request ID, related application, job request status, and so on, or by any one of a number of pre-configured quick searches.
To search for a job request:
An advanced search is available in the Request Search page by clicking the Advanced button.
To search for a job request:
You can define and save schedules for later use in submitting job requests.
Navigate to the Schedules page by clicking the Scheduling Service menu, selecting Job Requests, then selecting Define Schedules.
On the Schedules page, you can choose one of the following actions:
To create a new schedule:
From the Application dropdown list, select the name of the application for which you want to create a schedule.
Click Create.
Enter the following information:
Name: Enter a name for the schedule. This is the name that appears when you assign the schedule to a job request.
Package: Optionally enter the name of a Java package related to this schedule if it helps you find or group schedules.
Description: Optionally enter a description.
From the Frequency dropdown, select how often you want job requests using this schedule to run. Each frequency option has its own way to specify details for the option As you specify details, note that you can click Select date and time icons to specify time zones as well.
Click OK.
To view details for an existing schedule:
In the Results area, locate the schedule whose details you want to view.
From the Application dropdown list, select the name of the application whose schedules you want to view.
In the Name column, click the schedule's name.
From the Schedule Details page, you can remove schedule times or click the Edit button to edit schedule details.
To edit an existing schedule:
In the Name and Package fields, enter values to search for.
Click Go to search.
In the Results area, locate the schedule you want to edit.
Select the schedule you want to edit, then click Edit.
On the Edit Schedule page, edit details about the schedule.
Click OK.
You can view detailed information about an individual job request by clicking the job request ID or the request parent ID in job request search results. If the job is in an error state, an information box displays details regarding the error that occurred. For more on searching for job requests, see Searching for Oracle Enterprise Scheduler Job Requests.
You can take the following actions on an individual job request:
Display log information for the job request.
Display the job set and all child job requests.
Submit a job or job set request with parameters similar to those of a given job request.
Recover an incomplete job request.
To view job request details:
You can hold or resume a job request after it has been submitted.
To hold and resume a job request:
You can cancel an executable job request after it has been submitted. Executable job requests include job sets and job requests submitted without schedules. A job request can be canceled when it is not in a state of execution.
When initiating a job request cancellation, the resulting cancellation state depends on the current state of the job request. A job request that is not executing is set directly to CANCELLED state. A job request in RUNNING, PAUSED or COMPLETED states are placed in CANCELLING state following the initiation of request cancellation.
The final state of a request depends on the processing stage the job request at the point when cancellation has been initiated.
Table 4-1 displays the cancellation states applied to each executable request depending on its state when initiating cancellation.
Table 4-1 Executable Requests and Cancellation States
| Job State When Initiating Cancellation | New Cancellation State |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Any terminal state |
No state change |
|
|
No state change |
|
|
No state change |
An executable request is processed in three major stages: pre-processor, executable and post-processor. Requests can be canceled at any of these stages. If the job request cannot complete all three stages, it transitions to CANCELLED.
This section contains the following topics:
When initiating cancellation during the pre-processor stage, the state to which the job request transitions depends on the status returned by the pre-processor.
Table 4-2 displays the job state following cancellation initiation.
Table 4-2 Pre-processor States and States Following Cancellation Initiation
| State Returned by the Pre-Processor | State Following Cancellation Initiation |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When initiating cancellation during the job execution stage, the state to which the request transitions depends on the manner of completion.
Table 4-3 displays the job state following cancellation initiation.
Table 4-3 Returned Synchronous Java Job States and States Following Cancellation Initiation
| State Returned by the Job | State Following Cancellation Initiation |
|---|---|
|
Normal return (success) |
|
|
|
|
|
|
|
|
|
|
|
|
|
When initiating cancellation during the job execution stage, the state to which the request transitions depends on the manner of completion.
Table 4-4 displays the job state following cancellation initiation.
Table 4-4 Returned Asynchronous Java Job States and States Following Cancellation Initiation
| State Returned by the Job | State Following Cancellation Initiation |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
No state change. Wait for further updates. |
|
|
|
|
|
|
If the job executable is executing, Oracle Enterprise Scheduler attempts to kill the running RDBMS Scheduler job. If the job is successfully killed, the request transitions to CANCELLED state. If the RDBMS Scheduler job completes before it can be killed, the state to which the job request transitions depends on the result of the job execution.
Table 4-5 displays the job state following cancellation initiation.
Table 4-5 Returned PL/SQL Job States and States Following Cancellation Initiation
| State Returned by the Job | State Following Cancellation Initiation |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If the spawned job is executing, Oracle Enterprise Scheduler attempts to kill the running process. If the process is successfully killed, the request transitions to a CANCELLED state. If the process completes before it can be killed, the state to which the request transitions depends on the result of the process execution.
Table 4-6 displays the job state following cancellation initiation.
Table 4-6 Returned Spawned Job States and States Following Cancellation Initiation
| State Returned by the Job | State Following Cancellation |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A parent job request that is canceled transitions to a CANCELLING state until all child requests complete or have been canceled. The cancellation operation propagates to all eligible child job requests. For example, job set steps are canceled when the job set is canceled, sub-requests are canceled when the parent request is canceled and recurring executable job requests are canceled when the recurring parent is canceled. If a child job request is executable, it is subject to the rules described in the preceding sections. When all the child requests have completed, the parent request transitions to CANCELLED state.
A child job request may be an executable or a parent job request. When canceling a sub-request that completes in CANCELLED or another terminal state, the parent job request resumes as usual as long as the parent job request has not been canceled as well. The state of the sub-request does not affect the state of the parent request.
When canceling a step within a job set, the job set transitions to a CANCELLED state when the job set step transitions to a CANCELLED state. However, the job set may not revert to CANCELLED state if another job set step results in an error.
To cancel a job request:
Purge policies allow the scheduling service to remove completed jobs according to specified criteria. For example, a purge policy might specify the retention of all Java type job requests using a particular job definition submitted executed by a given application for three days. Another purge policy might retain a particular type of job request, say, all SQL job requests in a successful state, for only one day. You can also specify the frequency at which the purge policy is to run.
This section contains the following topics:
A purge policy determines which job requests are to be purged and which retained. Defining a purge policy involves:
Selecting the jobs to be purged: Selection criteria include the related application or product, a particular job definition or job type, the job submitter or a maximum number of requests.
Specifying retention criteria: Decide how long job requests are to be retained depending on their status.
Specifying purge frequency: Decide how often you want the purge policy to run.
Note:
After a purge policy has run, it is necessary to physically delete purged job requests from the database. For more information, see Physically Purging Job Requests from the Database.
To set up a new purge policy:
Job request data is kept in the Oracle Enterprise Scheduler run-time store as records in the run-time store tables. These job requests records are kept in the run-time store until they are physically purged by a database administrator using SQL purge scripts. You must logically delete a job request before physically purging it.
Use the method esspurge.purge_requests on the Oracle Enterprise Scheduler schema to delete purged job requests from the database. In an Oracle Fusion Applications environment, the schema is typically called FUSION_ORA_ESS.
The ESSPURGE package contains a stored procedure which you can use to purge completed job requests. The package is normally loaded when the Oracle Enterprise Scheduler schema is created or updated. The stored procedure is shown in Example 4-1.
The basic syntax of esspurge.purge_requests is shown in Example 4-2, where FUSION_ORA_ESS is the name of the Oracle Enterprise Scheduler schema and password is the password.
Additional examples are shown in the following list.
To purge job requests completed earlier than the current time, at a maximum of 50000 job requests, execute the following command:
execute esspurge.purge_requests(systimestamp, 50000);
To purge job requests completed 30 days earlier, at a maximum of 50000 job requests, execute the following command:
execute esspurge.purge_requests(systimestamp - 30, 50000);
To purge job requests that completed before June 01, 2010 at 15:00:00 (UTC), at a maximum of 50000 job requests, execute the following command:
execute esspurge.purge_requests(TIMESTAMP '2010-06-01 15:00:00 -00:00', 50000);
Example 4-1 ESSPURGE Stored Procedure for Purging Completed Job Requests
--- Purges job requests that have completed. --- --- p_older_than : Purge only job requests that have completed after this time. --- p_max_count : The maximum number of job requests to purge. --- p_max_runtime : The maximum time, in minutes, the purge should run. --- If null (default), this defaults to one day which effectively means --- there is no time limit. --- procedure purge_requests ( p_older_than in timestamp, p_max_count in number, p_max_runtime integer default null );
Example 4-2 Purging Job Requests from the Database
sqlplus FUSION_ORA_ESS/password set serveroutput on size unlimited set timing on execute esspurge.purge_requests(systimestamp, 1000000);
You can view all purge policies defined for the scheduling service.
To display purge policies for the scheduling service:
You can edit the request or retention criteria of an existing purge policy, as well as the purge policy schedule as long as the purge policy is not in the "Succeeded" or "Cancelled" state.
To update a purge policy:
You can delete a given purge policy as long as it is not in the "Wait" or "Hold" state.
To delete a purge policy:
Oracle Simple Data Security enforces security authorizations for access and modification of specific data records. Oracle Simple Data Security integrates with Oracle Platform Security Services (OPSS) by granting actions to OPSS principals. The grant defines who (the principals) can do what (the actions) on a given resource. A grant in Oracle Simple Data Security can use any enterprise user or enterprise group as principals.
In the context of Oracle Enterprise Scheduler, a job request access control data security policy comprises a grant, a grantee and a set of oracle.as.scheduler.security.RuntimeDataPermission privileges for a set of job requests as follows:
A grantee, represented by grantee ID such as a user or application role. The ID should match the user GUID or application role GUID retrieved from Oracle Fusion Middleware.
You can manage the job request access control data security policy using Oracle Enterprise Manager Fusion Middleware Control.
The following behaviors are in place by default:
A user by default can see only the requests they submitted.
If a user can see a request, then they can see the request logs.
If a user can see a request, and if the request does not run as elevated privilege, then the user sees the request output.
If a user can see a request, and if the request run as elevated user, the user is not able to see the request output.
A request run-as user (elevated user, if specified) is able to see the request, request log, and request output.
An Administrators group user (for example, "weblogic") is able to see all the requests and request logs.
Administrators user is not able to see request output unless the requests were submitted and run as himself.
You can use Enterprise Manager to create functional and data security policies for Oracle Enterprise Scheduler. There, you can associate actions with roles to create a policy.
Table 4-7 lists available Simple Data Security actions.
Table 4-7 Grant Actions for Data Security
| Action | Effect |
|---|---|
|
|
Read the request, get request state, and get details. |
|
|
Update the request. |
|
|
Hold request execution. |
|
|
Cancel a request execution. |
|
|
Lock a request. |
|
|
Release the lock on a request. |
|
|
Delete a request. |
|
|
Purge a request. |
|
ESS_REQUEST_OUTPUT_CREATE |
Create the output of a request. |
|
|
View the output of a request. |
|
|
Delete the output of a request. |
|
|
Update the output of a request. |