Managing Oracle Enterprise Scheduler Requests

4 Managing Oracle Enterprise Scheduler Requests

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:

Introduction to Managing Oracle Enterprise Scheduler Job Requests

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.

Managing Oracle Enterprise Scheduler Requests

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:

Submitting an Oracle Enterprise Scheduler Job Request

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:

Creating a Job Request

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.
1. Under Job Definition, click the search button next to the Job Definition text field.
2. 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.
3. From the search results table, select the job definition name.
4. Click OK.
In the Parameters region, optionally define any parameters you want to use with the scheduled job request.
1. In the Job Parameters region, click Add to add a parameter.
  
  Fill in a name and value for the parameter.
2. 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.

Specifying a Job Request Schedule

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:

In the Schedule region, select Specify schedule.
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 also use the Time Zone dropdown to specify time zones.
Select the Save Schedule check box to save this schedule for later use by this or other job requests, then enter the following:
- Name: Enter a name for the schedule. This is the name that appears when you assign the schedule to a job request.
- Display Name: Enter a value that is played to users for this schedule.
- 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.

Searching for Oracle Enterprise Scheduler Job Requests

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:

Searching for a Job Request Using Simple Search

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:

Navigate to the Request Search page by clicking the Scheduling Service menu and selecting Job Requests, then selecting Search Job Requests.
Select the scope of the job request search by selecting one of the following options:
- Current Scheduling Service: Select this option to search for job requests submitted only to the scheduling service with which you are currently working.
- All Scheduling Services sharing the ESS repository: Select this option to search for job requests submitted to all scheduling services sharing the repository -- for example, all scheduling services in a cluster of scheduling services.
  
  The repository -- the Oracle Enterprise Scheduler run-time database that holds jobs requests -- can be shared across multiple domains with Oracle Enterprise Scheduler. This might be useful to see jobs running across domains that might be stressing a shared resource, such as a database.
To run a fast search, from the Quick Search dropdown list, select a pre-configured search option as shown in the following list.
- Requests submitted in the last hour
- Pending requests submitted in the last 24 hours
- Errored requests submitted in the last 24 hours
- All running requests
- All pending requests
- Requests currently being retried
- Requests retried in the last 24 hours
- Requests that resulted in System Error in the last 24 hours
- Requests that resulted in Business Error in the last 24 hours
- Ready requests for selected Work Assignment.
- Asynchronous requests that require manual recovery.
To run a regular job request search, skip this step.
Enter or select the criteria by which to search for job requests.
- Request ID: Enter the ID of the job request for which you want to search.
- Application: From the Application dropdown list, select the name of the application related to the job request for which you want to search. Alternatively, select All to search for job requests in all applications.
- Status: Select the status of the job request for which you want to search. Alternatively, select All to search for job requests with all statuses.
  
  The job request statuses are:
  - Blocked
  - Cancelled
  - Cancelling
  - Completed
  - Error
  - Error Auto Retry
  - Error Manual Recovery
  - Expired
  - Finished
  - Hold
  - Paused
  - Pending Validation
  - Ready
  - Running
  - Schedule Ended
  - Succeeded
  - Unknown
  - Validation Failed
  - Wait
  - Warning
- Execution Type: Options include Java Type, SQL Type, and Process Type.
- Submitted: From the dropdown list, select the time period in which the job request to be searched has been submitted. Options include Last Hour, Last 24 Hours, Last 7 Days, and Last 31 Days.
- Submitted By: In the text field, enter the name of the user who submitted the job request you want to find.
- Submission Notes: In the text field, enter any notes associated with the submission.
- Job Definition: Click the search button next to the text field and select the relevant job definition name.
- Job Location: Specify an abstract location for EJB and web services jobs. See Job Location Properties for more information.
- Work Assignment: Click the search button next to the text field and select a work assignment from the list.
- Product: In the text field, enter the name of the product using the job request.
Optionally, conduct an advanced search by clicking the Advanced button. For more on advanced search, see Searching for a Job Request Using the Advanced Search Feature.
Click Search to submit the job request search.

Searching for a Job Request Using the Advanced Search Feature

An advanced search is available in the Request Search page by clicking the Advanced button.

To search for a job request:

Enter a basic search for a job request. Navigate to the Request Search page by clicking the Scheduling Service menu and selecting Job Requests, then selecting Search Job Requests.
Select the scope of the job request search by selecting one of the following options:
- Current Scheduling Service: Select this option to search for job requests submitted only to the scheduling service with which you are currently working.
- All Scheduling Services sharing the ESS repository: Select this option to search for job requests submitted to all scheduling services sharing the repository, for example all scheduling services in a cluster of scheduling services.
  
  The repository -- the Oracle Enterprise Scheduler run-time database that holds jobs requests -- can be shared across multiple domains with Oracle Enterprise Scheduler. This might be useful to see jobs running across domains that might be stressing a shared resource, such as a database
Select your basic search criteria. For more information, see Searching for a Job Request Using Simple Search.
Click Advanced to display the fields for the advanced search.
In the Date Range section, configure the date range in which to search for job requests. The date on the left is the beginning date and the date on the right is the end date. For each date, click the Calendar button to the right of the text field to select the date and time.
- Submitted between: Enter the start and end dates during which the job request was submitted.
- Scheduled between: Enter the start and end dates during which the job request is scheduled to run.
- Completed between: Enter the start and end dates during which the job request finished running.
In the Run Time/Wait Time section, select the run or wait time of the job request for which you are searching, such as long or short running requests.
- None: Select if no run or wait time is to be specified.
- Long running requests: Select to search for requests running longer than a specified number of seconds, minutes, hours or days.
  
  In the Minimum Run Time text field, enter the lower limit of the time period for which the job request runs. From the dropdown list, select the required unit of time.
- Short running requests that waited: Select to search for job requests running longer than a specified period of time and waiting less than a specified period.
  
  In the Maximum Run Time text field, enter the upper limit of the time period for which the job request runs. From the dropdown list, select Seconds, Minutes, Hours or Days.
  
  In the Minimum Wait Time text field, enter the lower limit of the time period during which the job request waits to run. From the dropdown list, select Seconds, Minutes, Hours or Days.
- Waiting requests by time: Select to search for job requests waiting to run for a specified time period.
  
  In the Minimum Wait Time text field, enter the lower limit of the time period during which the job request waits to run. From the dropdown list, select Seconds, Minutes, Hours or Days.
  
  In the Maximum Wait Time text field, enter the upper limit of the time period during which the job request waits to run. From the dropdown list, select Seconds, Minutes, Hours or Days.
In the Retry of Failed Runs section, use the Number of Retries dropdown list to select an operator such as equal to, greater than, greater than or equal to, and so on.

In the text field, enter the number of retries.
In the Error Type section, use the dropdown list to select the type of error:
- Business: A job ends in a business error when it must abort prematurely due to unforeseen conditions, but is otherwise able to exit with its data in a consistent state. A job request might end in a business error as a result of an application setup or configuration condition, a functional conflict that requires an early exit or corrupt or inconsistent data. You cannot retry running a job request that ends in a business error.
- System: A job ends in a system error when a technical problem occurs from which the job cannot recover, but otherwise exits on its own. Alternatively, the computer running the job crashes. Examples include table space issues and unhandled run-time exceptions. You can retry running a job request that ends in a system error.
In the Request ECID/Correlation Flow ID section, use the Request ECID and Correlation Flow ID fields to specify the values for your request.
Click Search to submit the job request search.

Configuring the Display of Columns in the Search Results Table

After running a search for job requests, you can configure the display of columns in the search results table.

To configure job request search results table display columns:

Display the main Oracle Enterprise Scheduler Request search page and display the search interface.
Show or hide columns.

Click the View dropdown list and select Columns. then click column names to add check marks for the ones you want and remove check marks for those you do not.

You can also instead click Manage Columns to view the Manage Columns dialog box, through which you can show or hide columns. Use the arrows between the columns to move column names from the Visible to the Hidden column, or vice versa.
Sort columns.

You can sort selected columns in ascending or descending order by clicking on the View dropdown list and selecting Sort. Click on Advanced to sort columns using multiple criteria.
Reorder columns.
You can reorder the columns in the table two ways:
- Select View > Columns > Manage Columns
- Select View > Reorder Columns
Alternatively, display all columns by clicking the View dropdown list and select Columns, then Show All.

Creating or Editing Predefined Job Schedules

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:
  1. From the Application dropdown list, select the name of the application for which you want to create a schedule.
  2. Click Create.
  3. 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.
  4. 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.
  5. Click OK.
- To view details for an existing schedule:
  1. In the Results area, locate the schedule whose details you want to view.
  2. From the Application dropdown list, select the name of the application whose schedules you want to view.
  3. In the Name column, click the schedule's name.
  4. From the Schedule Details page, you can remove schedule times or click the Edit button to edit schedule details.
- To edit an existing schedule:
  1. In the Name and Package fields, enter values to search for.
  2. Click Go to search.
  3. In the Results area, locate the schedule you want to edit.
  4. Select the schedule you want to edit, then click Edit.
  5. On the Edit Schedule page, edit details about the schedule.
  6. Click OK.

Viewing Job Request Details

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:

Search for the relevant job requests as described in Searching for a Job Request Using Simple Search
In the table displaying the job request search results, select the job request whose details you want to view.
To view job request details, click the job request ID. Alternatively, click the parent ID associated with the job request to view the details of the job set with which the job is associated.
In the job request details page, you can take any of the following actions.
- Request Log: Select Action and then select Request Log to display log information for the job request.
- SOA Composite Flow Trace: Select Action and then select SOA Composite Flow Trace to display the user interface for the flow of messages through composite and component instances. Use this command in cases when request status has not been updated from the SOA composite. The request's flow trace provides information related to activity in the composite.
  
  This action is available for asynchronous Java jobs where everything is in the same domain. If the job happens not to be a SOA composite web service invocation, then the flow trace user interface displays a "Trace not found" message.
- Request Tree: Select Action and then select Request Tree to display the parent job set along with all related child jobs.
- Cancel: Select Action and then select Cancel to cancel the job request.
- Hold: Select Action and then select Hold to temporarily suspend the job request.
- Resume: Select Action and then select Resume to resume a suspended job request.
- Recover Stuck Request: Select Action and then select Recover Stuck Request to recover an incomplete job request that cannot continue.
- Change Priority: Select Action and then select Change Priority to raise or lower the priority of the job request. Job requests with a higher priority are dispatched prior to job requests with lower priority.
- Change Schedule: Select Action and then select Change Schedule to assign a different schedule to the job request.
- Submit Like: Select Action and then select Submit Like to submit a job or job set with parameters similar to this one.

Holding and Resuming Oracle Enterprise Scheduler Job Requests

You can hold or resume a job request after it has been submitted.

To hold and resume a job request:

Search for a job request. For more information, see Searching for a Job Request Using Simple Search.
In the table of job request search results, select the job request you want to hold.
Click the Hold button.

You can also hold a job request from the Request Details page by selecting Select Action, then Hold.
To resume the paused job request, select the job request and click Resume.

You can also resume a job request from the Request Details page by selecting Select Action, then Resume.

Canceling Oracle Enterprise Scheduler Job Requests

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
`WAIT`	`CANCELLED`
`READY`	`CANCELLED`
`HOLD`	`CANCELLED`
`BLOCKED`	`CANCELLED`
`PENDING_VALIDATION`	`CANCELLED`
`ERROR_AUTO_RETRY`	`CANCELLED`
`PAUSED`	`CANCELLING`
`RUNNING`	`CANCELLING`
`COMPLETED`	`CANCELLING`
Any terminal state	No state change
`CANCELLING`	No state change
`ERROR_MANUAL_RECOVERY`	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:

Initiating Cancellation During Pre-Process Handler Execution

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
`PROCEED`	`CANCELLED`
`DELAY`	`CANCELLED`
`WARN`	`CANCELLED`
`SYSTEM_ERROR`	`ERROR`
`BIZ_ERROR`	`ERROR`

Initiating Cancellation During Synchronous Java Job Execution

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)	`CANCELLED`
`ExecutionWarningException`	`CANCELLED`
`ExecutionPausedException`	`CANCELLED`
`ExecutionBizErrorException`	`ERROR`
`ExecutionErrorException`	`ERROR`

Initiating Cancellation During Asynchronous Java Job Execution

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
`SUCCESS`	`CANCELLED`
`PAUSE`	`CANCELLED`
`WARNING`	`CANCELLED`
`ERROR`	`ERROR`
`CANCEL`	`CANCELLED`
`UPDATE`	No state change. Wait for further updates.
`BIZ_ERROR`	`ERROR`
`ERROR_MANUAL_RECOVERY`	`ERROR_MANUAL_RECOVERY`

Initiating Cancellation During PL/SQL Job Execution

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
`SUCCESS`	`CANCELLED`
`WARNING`	`CANCELLED`
`PAUSE`	`CANCELLED`
`BIZ_ERROR`	`ERROR`
`SYSTEM_ERROR`	`ERROR`

Initiating Cancellation During Spawned Job Execution

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
`SUCCESS`	`CANCELLED`
`WARNING`	`CANCELLED`
`PAUSE`	`CANCELLED`
`BIZ_ERROR`	`CANCELLED`
`SYSTEM_ERROR`	`CANCELLED`

Canceling Parent Job Requests

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.

Canceling a Child Job Request

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:

Search for a job request.
In the table of job request search results, select the job request you want to cancel.
Click the Cancel button.

Managing Purge Policies

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.

In SaaS, the default purge frequency is monthly for production and stage PODs with a retention period of 60 days. The purging removes all the completed ESS jobs older than 60 days.

This section contains the following topics:

Setting Up a New Purge Policy

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:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Purge Policies.
To configure a new policy, click Setup New.

In the Setup Purge Policy page, configure the purge policy.
In the Description text field, enter a description for the purge policy.
In the Request Criteria for Purge section, configure the characteristics of the job requests to be purged.
- Application: From the dropdown list, select the application for which you want to create a purge policy.
- Product: Enter the name of the product.
- Job Definition: Click the browse button next to the Job Definition text field.
  
  In the Select Job Definition window, enter the name of the job definition in the Name text field.
  
  Click Go to search, then select the relevant job definition from those that display. Click OK.
- Execution Type: From the dropdown list, select the job type required: All, Java Type, SQL Type, or Process Type.
- Submitted by: Enter the name of the job submitter.
In the Retention Criteria for Purge section, configure the characteristics of the job requests to be retained.
- Default Retention Period (in days): Enter the default period, in days, during which requests are to be retained.
- Retention Period - Success (in days): Enter the period, in days, during which successful job requests are retained.
- Retention Period - Error (in days): Enter the period, in days, during which errored job requests are retained.
- Retention Period - Warning (in days): Enter the period, in days, during which job requests ending in a warning status are retained.
- Retention Period - Cancelled (in days): Enter the period, in days, during which canceled job requests are retained.
In the Schedule section, set a schedule for the job request purge policy.
- To run the purge policy only one time, select Once. Click the Calendar button to select the date and time you want the purge policy to run.
- To set a schedule for the purge policy, select Use Existing Schedule. Click the browse button to search for a schedule.
  
  In the Select Schedule window, select a schedule and click OK.
In the Advanced section, in the Maximum requests to be processed text field, enter the maximum number of job requests to be processed.
Click OK to save the purge policy.

Physically Purging Job Requests from the Database

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);

Viewing Purge Policies

You can view all purge policies defined for the scheduling service.

To display purge policies for the scheduling service:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Purge Policies.

Updating a Purge Policy

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:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Purge Policies.
From the Purge Policies table, select the policy you want to update and click Update.
Edit the purge policy accordingly and click OK.

Deleting 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:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Purge Policies.
From the Purge Policies table, select the policy you want to delete and click Delete.

Configuring Simple Data Security for Job Requests

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.

Oracle Simple Data Security Actions

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
`ESS_REQUEST_READ`	Read the request, get request state, and get details.
`ESS_REQUEST_UPDATE`	Update the request.
`ESS_REQUEST_HOLD`	Hold request execution.
`ESS_REQUEST_CANCEL`	Cancel a request execution.
`ESS_REQUEST_LOCK`	Lock a request.
`ESS_REQUEST_RELEASE`	Release the lock on a request.
`ESS_REQUEST_DELETE`	Delete a request.
`ESS_REQUEST_PURGE`	Purge a request.
ESS_REQUEST_OUTPUT_CREATE	Create the output of a request.
`ESS_REQUEST_OUTPUT_READ`	View the output of a request.
`ESS_REQUEST_OUTPUT_DELETE`	Delete the output of a request.
`ESS_REQUEST_OUTPUT_UPDATE`	Update the output of a request.

How to Create Data Security Policies for Oracle Enterprise Scheduler Components

You can use Enterprise Manager to create functional and data security policies for Oracle Enterprise Scheduler.

From the navigation pane, expand the WebLogic Domain folder and select the domain for which you're creating policies.
From the WebLogic Domain menu, select Security and then select Application Policies.

The Application Policies page displays.
In the Search section, from the Application Stripe dropdown, select the application stripe with which you want to work.
Click Create to begin granting permissions to certain users, groups, or application roles.

The Create Application Grant page appears.
In the Create Application Grant page, in the Grantee section, click Add.
In the Add Principal window, from the Type dropdown, select a type of principal, then enter a principal name or display name and click the search button to find the principal you want to add.
Under Search Principals, click the principal you want, then click OK.
In the Permissions section, click Add.
In the Search section, click Permissions or Resource Types depending on which you wish to search.
If you searched permissions, select oracle.as.scheduler.security.RuntimeDataPermission from the Permission Class dropdown. If you searched resource types, select ESSRequestSimpleResourceType from the Resource Type dropdown.
Click the Search button.
Under Search Results, select a resource, then click Continue.
In the Add Permission dialog, select the permission actions you want to grant.
Click Select.