| Oracle® Fusion Applications Extensibility Guide 11g Release 1 (11.1.1.5) Part Number E16691-02 |
|
|
View PDF |
| Oracle® Fusion Applications Extensibility Guide 11g Release 1 (11.1.1.5) Part Number E16691-02 |
|
|
View PDF |
This chapter describes how to use JDeveloper or Oracle Enterprise Manager Fusion Applications Control to create and extend Oracle Enterprise Scheduler jobs.
This chapter includes the following sections:
Section 14.1, "About Customizing and Extending Oracle Enterprise Scheduler Jobs"
Section 14.2, "Extending Custom Oracle Enterprise Scheduler Jobs"
Section 14.3, "Customizing Existing Oracle Enterprise Scheduler Jobs"
Enterprise applications require the ability to respond to many real-time transactions requested by end users or web services. However, they also require the ability to offload larger transactions to run at a future time, or automate the running of application maintenance work based on a defined schedule.
Oracle Enterprise Scheduler provides the ability to run different job types, including: Java, PL/SQL and spawned processes, distributed across nodes in a server cluster. Oracle Enterprise Scheduler runs these jobs securely, and provides monitoring and management through Fusion Applications Control.
Oracle Enterprise Scheduler provides scheduling services for the following purposes:
Distributing job request processing across a cluster of servers,
Running Java, PL/SQL and binary jobs,
Scheduling job requests based on recurrence,
Managing job requests with Fusion Applications Control.
Oracle Enterprise Scheduler provides the critical requirements in a service-oriented environment to automate processes that must recur on a scheduled basis and to defer heavy processing to specific time windows. Oracle Enterprise Scheduler lets you:
Support sophisticated scheduling and workload management,
Automate the running of administrative jobs,
Schedule the creation and distribution of reports,
Schedule a future time for a step in a business flow for business process management.
Extending Oracle Enterprise Scheduler jobs involves the following main steps:
Develop the code that implements the job logic.
Create a metadata file for the job definition.
Grant permissions to the job, such that only those with the proper permissions can request job submission.
Enable job request submission, using an existing hosting application, a pre-configured user interface or a new customized application.
Customizing Oracle Enterprise Scheduler jobs involves editing job properties using Oracle Enterprise Manager Fusion Applications Control. The job properties that you can modify are described in Table 14-4.
Before you extend and customize Oracle Enterprise Scheduler jobs, you should be familiar with the Oracle Fusion application architecture that enables customization, as described in Chapter 1, "Customizing and Extending Oracle Fusion Applications." You should also understand the typical workflow for working with customizations, as described in Chapter 2, "Understanding the Customization Development Lifecycle."
You will need to do the following before you can begin extending Oracle Enterprise Scheduler jobs:
For developers:
Set up JDeveloper. For more information, see Section 1.3.2, "Installing Customization Tools."
For administrators:
Install Oracle Fusion Applications, making sure to provision Oracle Enterprise Scheduler services. For more information, see the Oracle Fusion Applications Installation Guide.
Start Fusion Applications Control. For more information about starting up and using Fusion Applications Control, see the chapter "Getting Started with Managing Oracle Fusion Applications" in Oracle Fusion Applications Administrator's Guide.
There are two main use cases for creating Oracle Enterprise Scheduler jobs.
Oracle Enterprise Scheduler Administrator
Administrators can create a new job definition using Oracle Enterprise Manager Fusion Applications Control console, using an existing hosting application. Scheduled jobs typically required by administrators include database maintenance tasks using PL/SQL or running spawned jobs or scripts such as SQL*Plus scripts to load data into the database. Once you have defined the job, use Oracle Enterprise Manager Fusion Applications Control to submit the job request.
Developer or System Integrator
When using an existing hosting application, use Fusion Applications Control to create Oracle Business Intelligence Publisher, PL/SQL and spawned jobs. Use JDeveloper to create Java jobs and develop a new hosting application that executes a set of jobs. A Java job might invoke an Oracle ADF Business Components service or a SOA composite, for example.
In cases where there is no need to repackage the hosting application, PL/SQL, binary, Oracle BI Publisher and Java jobs can be added to any hosting application. Optionally, you can execute Java jobs from a custom hosting application.
System integrators may want to use Fusion Applications Control to develop a job, while developers may prefer JDeveloper. Jobs are typically submitted using the scheduled request submission UI. Alternatively, it is possible to develop an Oracle ADF application with screens for submitting Oracle Enterprise Scheduler jobs.
Task: Implement the Logic for the Oracle Enterprise Scheduler Job
An Oracle Enterprise Scheduler job is a request to execute a specific task written in code or a script, such as Java, PL/SQL, spawned jobs, and so on.
An example of logic to be implemented by a scheduled job is writing particular data to a database under certain conditions, for example, daily shift schedules for a given sub-set of employees.
Task: Create a Job Definition Metadata File
An Oracle Enterprise Scheduler job definition specifies the type of job to be run (such as Java, PL/SQL type jobs, and so on), the hosting application that will run the job, and any additional required or optional parameters and properties for the job.
It is possible to create a job definition in Oracle Enterprise Manager Fusion Applications Control or JDeveloper.
The minimum required properties and parameters for each job type are as follows:
Oracle BI Publisher jobs: Specify the reportid parameter. Specify Oracle BI Publisher parameters as job parameters with required validation. These can be entered by end users during request submission using the request submission user interface.
If the report is a bursting report, identify it as such by selecting the bursting check box.
PL/SQL jobs: In the job definition, specify the PL/SQL procedure that includes the job logic implementation.
All input arguments to the PL/SQL procedure can be specified as parameters with required validation. These can be entered by end users during request submission using the request submission user interface.
All other job types: Specify the name of the implementation logic and parameters in the job definition.
For more information about creating a job definition in Oracle Enterprise Manager Fusion Applications Control, see the chapter "Managing Oracle Enterprise Scheduler Service and Jobs" in Oracle Fusion Applications Administrator's Guide.
For more information about creating a job definition in JDeveloper, see the chapter "Working with Extensions to Oracle Enterprise Scheduler" in Oracle Fusion Applications Developer's Guide for Oracle Enterprise Scheduler.
Task: Grant Relevant Permissions
Grant the appropriate permissions for the application using the Oracle Authorization Policy Manager.
An example of the use of relevant permissions is to grant execution permissions to a role so that users belonging to that role can submit the job.
For more information about granting relevant permissions to a deployed application, see Oracle Fusion Middleware Oracle Authorization Policy Manager Administrator's Guide (Oracle Fusion Applications Edition).
Task: Enable Job Request Submission
You can enable job request submissions through an Oracle ADF user interface using JDeveloper or Fusion Applications Control.
When using JDeveloper to enable job request submissions through an Oracle ADF user interface, you must define a view object to capture properties filled in by end users.
If a job is defined with properties that must be filled in by end users, the user interface allows end users to fill in these properties prior to submitting the job request. For example, if the job requires a start and end time, end users can fill in the desired start and end times in the space provided by the user interface.
The properties that are filled in by end users are associated with a view object, which in turn is associated with the job definition itself. When the job runs, Oracle Enterprise Scheduler accesses the view object to retrieve the values of the properties.
You could, alternatively, submit job requests using Fusion Applications Control. Using Fusion Applications Control to enable job request submissions through an Oracle ADF user interface does not require you to create a view object for capturing end user data.
Note:
Suppose a parameter view object is VLinked to another view object (VO1). If you customize the view object using JDeveloper, then the Oracle Enterprise Scheduler job submission UI list of values reflects this customization, if the customization is in the MDS runtime database.For more information about submitting job requests using Fusion Applications Control, see the chapter "Managing Oracle Enterprise Scheduler Service and Jobs" in Oracle Fusion Applications Administrator's Guide.
For more information about defining a view object for use with a job submission interface, see the chapter "Working with Extensions to Oracle Enterprise Scheduler" in Oracle Fusion Applications Developer's Guide for Oracle Enterprise Scheduler.
Extending a custom PL/SQL Oracle Enterprise Scheduler job involves creating a PL/SQL package and defining job metadata.
Task: Implement the Logic for the PL/SQL Job
Implementing a PL/SQL scheduled job involves creating a PL/SQL package and defining the job metadata using the PL/SQL job type.
To implement the logic for a PL/SQL job:
Create a PL/SQL package, including the required errbuf and retcode arguments. A sample PL/SQL package is shown in Example 14-1.
Example 14-1 Sample PL/SQL package
CREATE OR REPLACE PACKAGE XxSamplePkg AUTHID CURRENT_USER AS
Procedure SampleJob (
errbuf out NOCOPY varchar2,
retcode out NOCOPY varchar2,
name in varchar2 );
END XxSamplePkg;
/
CREATE OR REPLACE PACKAGE BODY XxSamplePkg AS
Procedure SampleJob (
errbuf out NOCOPY varchar2,
retcode out NOCOPY varchar2,
name in varchar2 )
IS
begin
-- Write log file content using the FND_FILE API.
FND_FILE.PUT_LINE(FND_FILE.LOG, 'Running Stored procedure SampleJob..........');
FND_FILE.PUT_LINE(FND_FILE.LOG, 'FND USERNAME : ' || FND_GLOBAL.USER_NAME);
-- Write log file content using the FND_FILE API.
FND_FILE.PUT_LINE(FND_FILE.OUTPUT,' Name : ' || name );
FND_FILE.PUT_LINE(FND_FILE.OUTPUT, 'Job Request id : ' || FND_JOB.REQUEST_ID );
errbuf := fnd_message.get_string('FND', 'COMPLETED NORMAL');
retcode := 0;
end SampleJob;
END XxSamplePkg;
/
Deploy the package to Oracle Database.
Grant the required permissions, and perform any other necessary tasks in the database.
grant execute on xxSampleJob to FUSION_APPS_EXECUTE;
For more information about granting permissions for the execution of a PL/SQL job, see the section "Performing Oracle Database Tasks for PL/SQL Stored Procedures" in the chapter "Creating and Using PL/SQL Jobs" in Oracle Fusion Applications Developer's Guide for Oracle Enterprise Scheduler.
Test the package.
Task: Create a Job Definition Metadata File for the PL/SQL Job
Use Functional Setup Manager to define a job definition metadata file for the PL/SQL job. The job definition metadata file may also include user properties for the PL/SQL job as well as UI parameters to be displayed at runtime.
For more information about creating an Oracle Enterprise Scheduler metadata file, see the section "Creating a Job Definition" in the chapter "Managing Oracle Enterprise Scheduler Service and Jobs" in Oracle Fusion Applications Administrator's Guide.
To create a job definition metadata file for a PL/SQL job:
Login to Functional Setup Manager as a user with the role ASM_IMPLEMENTATION_MANAGER_DUTY. For example, you can login with the username APPLICATION_IMPLEMENTATION_CONSULTANT.
The URL for Functional Setup Manager is as follows.
https://<HOST>/setup/faces/TaskListManagerTop
In Functional Setup Manager, select the Setup and Maintenance work area and click the All Tasks tab. Search for all tasks.
From the list of tasks that displays, select the relevant UI application you will use to host the job definitions and parameter view objects. This Fusion application is the portlet producer application for the job.
Click the Go to Task button.
The Manage Job Definitions tab displays, as shown in Figure 14-1.
In the Manage Job Definitions tab, click the New button.
In the Create Job Definition tab, click Show More to display all parameters and enter the values for the job shown in Table 14-1.
Table 14-1 PL/SQL Job Definition Values
| Field | Description |
|---|---|
|
Display Name |
Enter a display name for the job. |
|
Name |
Enter a name for the job definition. |
|
Path |
Specify the trailing package name for the job definition metadata. The default namespace or path for custom job definitions begins with |
|
Job Application Name |
From the dropdown list, select the name of the hosting application running the Oracle Enterprise Scheduler job. |
|
Job Type |
Select the job type from the dropdown list, namely the PlsqlJobType. |
|
Procedure Name |
Enter the name of the stored procedure to run as part of the PL/SQL job execution. |
|
Standard request submission flag |
Check this box to indicate that the job request is to be submitted in the standard manner. |
At the bottom of the pane, click the User Properties tab. Define the following user properties by clicking the New button, as shown in Table 14-2.
Table 14-2 PL/SQL User Properties
| Name | Data Type | Default Value | Read Only |
|---|---|---|---|
|
|
String |
For the default value, enter the name of the web module which Functional Setup Manager will use as a portlet when submitting the job request. |
N/A |
|
|
String |
Set the number of job submission arguments, including |
N/A |
Note:
Typically, the web context is registered as the web module name. Verify with your applications administrator the value of the registered web module name in the Topology Manager of Functional Setup Manager. Registering the correct web module name enables the correct remote rendering of the Fusion application job request parameters from the Oracle Enterprise Scheduler central UI.Click the <Job Definition Name>: Parameters tab and specify UI parameters as required. The UI parameter fields are described in Table 14-3.
Table 14-3 PL/SQL Job UI Parameters
| Field | Description |
|---|---|
|
Prompt |
Enter the text to be displayed at the prompt that displays during run time. |
|
Data Type |
From the dropdown list, select the relevant data type. |
|
Page Element |
From the dropdown list, select the UI page element you want to use to display the parameter, for example, a text box. |
Click Save and Close to create and save the new Oracle Enterprise Scheduler PL/SQL job definition.
Implementing a Oracle BI Publisher scheduled job involves creating a Oracle BI Publisher report on the Oracle BI Publisher Server and defining the Oracle Enterprise Scheduler job metadata.
Task: Implement the Logic for the Oracle BI Publisher Job
For information about implementing an Oracle BI Publisher job, see the chapter "Using BI Publisher with Oracle JDeveloper" in the Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence Publisher (Oracle Fusion Applications Edition).
Task: Create a Job Definition Metadata File for the Oracle BI Publisher Job
Using Functional Setup Manager, create an Oracle BI Publisher type job definition.
To create a job definition metadata file for an Oracle BI Publisher job:
Follow the instructions in "Task: Create a Job Definition Metadata File for the PL/SQL Job".
From the Job Type dropdown list, select BinaryJobType.
In the User Properties tab, define only the EXT_PortletContainerWebModule property.
Implementing a Java scheduled job involves implementing the Java business logic and defining the relevant Oracle Enterprise Scheduler job metadata. Use JDeveloper to implement a Java job and deploy the job as a shared library. Modify the deployment descriptor of the deployed user interface or hosting application EAR file so that it points to the shared library. Redeploy the file.
Deploying the job as a shared library allows you to add additional jobs in the future without having to redeploy the hosting application. For more information about deploying Oracle ADF applications, see the chapter "Deploying Fusion Web Applications" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Task: Implement the Logic for the Java Job
In order to develop an application that runs a Java class under Oracle Enterprise Scheduler, you must define the Java class that implements the Oracle Enterprise Scheduler executable interface. The executable interface defines the contract that enables using Oracle Enterprise Scheduler to invoke a Java class.
To create a Java class for an existing Oracle Enterprise Scheduler Fusion application, take the following steps:
Create an application in JDeveloper.
Create a project in JDeveloper.
Develop the application code that uses the Oracle Enterprise Scheduler Java APIs.
To implement the logic for an Oracle Enterprise Scheduler Java job:
In JDeveloper, create an application and project. Make sure to include EJB and Java technologies in the project.
Add the Oracle Enterprise Scheduler extensions to the project.
In the Application Navigator, right-click the project you just created. Select Project Properties and then select Libraries and Classpath.
In the Libraries and Classpath pane, click Add Library.
In the Add Library window, in the Libraries field, select Enterprise Scheduler Extensions and click OK.
Create a Java class using the Oracle Enterprise Scheduler package.
In the project overview tab, click the Java Files link.
In the Java Files pane, click the New button. From the Create New in Project menu, select Project Name and then select Java Class.
The Create Java Class window displays.
In the Create Java Class window, enter a name for the Java class and the package name oracle.apps.financials.ess.program in the fields provided. Accept the remaining default values.
In the Java class, develop the code that will do the work of the Java job. Example 14-2 shows sample code which illustrates the use of an Oracle Enterprise Scheduler job request file handle and writes a job request parameter submitted to the request log and output files.
Example 14-2 Sample Java code
package oracle.apps.financials.ess.program;
import java.io.IOException;
import oracle.as.scheduler.Cancellable;
import oracle.as.scheduler.Executable;
import oracle.as.scheduler.ExecutionCancelledException;
import oracle.as.scheduler.ExecutionErrorException;
import oracle.as.scheduler.ExecutionPausedException;
import oracle.as.scheduler.ExecutionWarningException;
import oracle.as.scheduler.RequestExecutionContext;
import oracle.as.scheduler.RequestParameters;
import oracle.as.scheduler.SystemProperty;
import oracle.as.scheduler.cp.exec.ProcessHelper;
import oracle.as.scheduler.cp.file.LogFile;
import oracle.as.scheduler.cp.file.OutputFile;
public class XxSampleJob implements Executable, Cancellable {
private OutputFile requestOutput;
private LogFile requestLog;
private boolean m_isCancelled = false;
private long request_id = 0L;
private String requestParameter1 = null;
public XxSampleJob() {
super();
}
public void execute(RequestExecutionContext ctx,
RequestParameters params) throws ExecutionErrorException,
ExecutionWarningException,
ExecutionCancelledException,
ExecutionPausedException {
request_id = ctx.getRequestId();
System.out.println("XxSampleJob Running, Request ID: " +
ctx.getRequestId());
try {
String userFileDir =
(String)params.getValue(SystemProperty.USER_FILE_DIR);
String sysPropUserName =
(String)params.getValue(SystemProperty.USER_NAME);
// Read the job request parameter.
requestParameter1 = (String) params.getValue("submit.argument1");
requestOutput = ProcessHelper.getOutputFile();
requestOutput.writeln("Sample ESS Java job execution OUTPUT");
requestOutput.writeln("USER_NAME as SystemProperty: " +
sysPropUserName);
requestOutput.writeln("ESS Job requestID: " + request_id);
requestOutput.writeln("ESS Job request parameter: "
+ requestParameter1);
requestLog = ProcessHelper.getLogFile();
requestLog.writeln("Sample ESS Java job execution LOG");
requestLog.writeln("ESS requestFileDirectory: " + userFileDir);
requestLog.writeln("ESS Job requestID: " + request_id);
requestLog.writeln("ESS Job request parameter: "
+ requestParameter1);
} catch (Exception ex) {
System.out.println("Exception running XxSampleJob: " +
ex.getMessage());
ex.printStackTrace();
} finally {
try {
// Close all open job request log and output files.
ProcessHelper.closeAllFiles();
} catch (IOException ioe) {
System.out.println("Exception closing files: " +
ioe.getMessage());
ioe.printStackTrace();
}
}
}
@Override
public void cancel() {
m_isCancelled = true;
}
}
Task: Deploy the Java Business Logic
In order to deploy the Java logic of an Oracle Enterprise Scheduler Java job, identify an existing Fusion application as the target hosting application.
Next, update the Java business logic for an existing Fusion application as follows:
Package the Java application in a JAR file.
Update JAR module in the Fusion application classpath.
Bounce the server instance to load the Java program logic in the Fusion application class loader.
To deploy the Java business logic:
Create a deployment profile for the project.
In JDeveloper, from the Application Navigator, select the project you created. Build the project to ensure that the Java class successfully compiles.
Right-click the project, select Project Properties and Deployment.
In the Deployment Profiles field, click New to create a deployment profile for the JAR file.
The Create Deployment Profile window displays.
In the Create Deployment Profile window, enter a name for the deployment profile and click OK.
In the Edit JAR Deployment Profile Properties window, verify that the Java job class is included in the JAR module output and click OK.
Package the Oracle Enterprise Scheduler Java class into a JAR file and deploy it.
From the Application Navigator, right-click the project you created. Select Deploy and then select the JAR file you just created.
The Deployment Action window displays.
In the Deployment Action window, click Finish to create a packaged JAR archive.
The archive module is deployed to the default project deployment path, for example, $JDEV_HOME/<PROJECT_NAME>/deploy/<JAR_NAME>.jar.
Note:
All custom JAR files must begin with the prefixXx, for example XxMyJar.jar.Update the JAR module in the application classpath of the Oracle Enterprise Schedulerhosting application.
Locate the expanded deployment directory of the EAR file for the existing Fusion application, for example $MW_HOME/fusionapps/applications/fin/deploy/EarFinancialsEss.ear/APP-INF/lib.
Copy the deployed custom jar file to the expanded directory.
In the domain to which the Oracle Enterprise Scheduler hosting application is deployed, restart Oracle Enterprise Scheduler.
The Oracle Enterprise Scheduler job executes the updated Java class once the application class loader successfully loads the updated class.
For more information about restarting the Oracle Enterprise Scheduler, see the section "Starting and Stopping an Oracle Enterprise Scheduler Service Instance" in the chapter "Managing Oracle Enterprise Scheduler Service and Jobs" in Oracle Fusion Applications Administrator's Guide.
Task: Create a Job Definition Metadata File for the Java Job
Using Functional Setup Manager, create a Java type job definition.
To create a job definition metadata file for a Java job:
Follow the instructions in "Task: Create a Job Definition Metadata File for the PL/SQL Job".
In the Create Job Definition window, from the Job Type dropdown list, select JavaJobType.
In the Create Job Definition window, in the Class Name field, enter the fully qualified class name of the Java business logic.
In the Create Job Definition window, In the User Properties tab, define only the EXT_PortletContainerWebModule property.
Click the <Job Definition Name>: Parameters tab and specify UI parameters as required. The UI parameter fields are described in Table 14-3.
Click Save and Close to create and save the new Oracle Enterprise Scheduler Java job definition.
You can use Oracle Fusion Applications to submit Oracle Enterprise Scheduler jobs.
To submit Oracle Enterprise Scheduler jobs:
In the main area of Oracle Fusion Applications, access the Schedule Processes page by clicking the Navigator menu and then selecting Tools and Schedule Processes.
Click Schedule New Process.
The Search and Select: Process Name window displays.
In the Process Name field, enter the name of the Oracle Enterprise Scheduler job you want to schedule and click Search.
The job name displays in the search results table.
From the search results table, select the job name and click OK.
The Process Details page displays.
In the Process Details page, in the Parameters field, specify any required parameters.
Click Submit to request that the Oracle Enterprise Scheduler instance execute the job. Click Close to return to the Scheduled Processes page.
In the Scheduled Processes page, refresh the Search Results table to monitor the status of submitted job.
You can customize Oracle Enterprise Scheduler jobs that are associated with Fusion applications. Customizing existing Oracle Enterprise Scheduler jobs involves editing job properties using Oracle Enterprise Manager Fusion Applications Control.
An example of a customization is to set the time-out value for a scheduled job to be run asynchronously. When the job takes longer than the time-out, you can find the job that timed out in Fusion Applications Control and manually complete the job.
The job properties that can be edited are shown in Table 14-4.
For more information about editing scheduled job properties, see the chapter "Managing Oracle Enterprise Scheduler Service and Jobs" in Oracle Fusion Applications Administrator's Guide.
Table 14-4 Job Properties
| API | Description |
|---|---|
|
|
This property specifies the request processing priority, from 0 to 9, where 0 is the lowest priority and 9 is the highest. If this property is not specified, the system default value used is |
|
|
This property defines the numerical value that specifies the retry limit for a failed job request. If job execution fails, the request retries up to the number of times specified by this property until the job succeeds. If the retry limit is zero, a failed request will not be retried. If this property is not specified, the system default used is |
|
|
This property specifies an application-specific label for a request. The label, defined by an application or system administrator, allows administrators to group job requests according to their own specific needs. |
|
|
This property specifies the time in minutes that the job request processor waits for an asynchronous request after it has begun execution. After the time elapses, the job request times out. |
|
|
The property specifies a numerical value that indicates the level of tracing control for the job. Possible values are as follows:
|
|
|
This property enables or disables the accumulation of time statistics. |
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|