Oracle Enterprise Scheduler job metadata refers to the components that form the basis of scheduled job requests.
These include the following:
Job definition: A job definition is the smallest unit of work performed in the context of the application that executes the job. A job definition is defined by a job type, such as a Java or SQL job type.
Job set: A job set is a sequential or parallel set of job steps, where a job step can be a single job or another job set. A job set and each of its job set steps can have additional parameters, the values for which are provided when the job or job set is submitted as a job request.
Incompatibility: An incompatibility allows you to specify job definitions and job sets that cannot run concurrently.
Note:
When you use Oracle Enterprise Manager Fusion Middleware Control or WLST commands to search for metadata, be sure to search for the actual name of the job definition, job set, or incompatibility rather than the display name. Display names are not found during searches.
This section contains the following topics:
The Job Definitions page in Fusion Middleware Control allows you to view, create, edit, delete and search for job definitions.
This section contains the following topics:
Note:
For a detailed description about how to use Oracle JDeveloper and Oracle Enterprise Manager Fusion Middleware Control to create job definitions for web service jobs, see Developer's Guide for Oracle Enterprise Scheduler, "Using Oracle Enterprise Manager Fusion Middleware Control or Oracle JDeveloper to Create a Job Definition."
You can view the job definitions created for a given application. The table of job definitions displays details about the jobs related to an application such as the job definition name, the full path to which it is saved, the job type, and so on.
To display job definitions:
You can create or edit a job definition. With a job definition created, you can create a job request for a particular application. The job definition includes the directory path of the job to be run, the name of the application with which the job definition is associated and the job type used for the job definition. If the job is one of the web service types, the WSDL URL can also be specified.
Additional properties can be defined for a job definition as follows:
Parameters. You can configure editable or read-only parameters to be submitted to the job request.
User properties. You can configure properties to be filled in by end users at runtime, such as boolean, number and string values.
This section contains the following topics:
To create or edit a job definition:
You use a parameter to pass data to the job request. In the job submission user interface, parameters can be passed using a number of display controls, such as a text box, date picker, choice list or list of values.
To configure parameters for a job definition:
System properties are parameter names that are known to and used by the system. You can specify that certain system properties should be used in your metadata.
Note:
If you modify the value of a system property, be sure that the modified value of the system property is correct. An incorrect system property value might cause the job definition to not work as expected.
To configure system properties for a job definition:
On the Create Job Definition page, expand the System Properties section.
Click the Add button.
The Add System Property dialog box displays.
From the Name dropdown list, select the system property you want to specify. Possible system properties are shown in Table 5-1.
In the Initial Value text field, enter the value you want to assign to the system property.
Select the Read Only check box to have this property be read-only to the user.
Click OK.
Table 5-1 System Properties
System Property | Description |
---|---|
|
For a process job type, this specifies a string representing the command line command on Unix. If the SYS_cmdLine property is defined, this property is ignored. |
|
For a process job type, this specifies a string representing the command line command on Windows. If the SYS_cmdLine property is defined, this property is ignored. |
[ |
Optional for EJB jobs. Specifies a pass-through parameter used by the EJB implementation to branch to the appropriate business methods. Example: |
|
For a process job, this specifies the directory where the process executable is located on Unix. |
|
For a process job, this specifies the directory where the process executable is located on Windows. |
|
For a process job, this specifies the name of the process executable. |
|
Specifies the suffix for SYS_EXT_executableName on Unix. The default is ".sh". |
|
Specifies the suffix for SYS_EXT_executableName on Windows. The default is ".cmd". |
|
For process and Java job types, this specifies a value that prompts Oracle Enterprise Scheduler to automatically export any previously imported output files to the request's output directory at the start of the execute stage. Using this property assumes that the request sets the SYS_EXT_supportOutputFiles property to "output" and the SYS_EXT_executeAutoExport property to "true". This can be useful in the case that RequestFileDirectory is a local directory and the execute stage requires access to output files that were created in the pre-processor or during a previous execution attempt, in case of retry. |
|
Set this to "true" to specify that the current job is Fusion Applications CP job type. |
|
The XML submit message used to invoke the web service. |
[ |
For EJB jobs, specifies the JNDI mapped name of Oracle Enterprise Scheduler's AsyncRequest bean defined in the hosting application and bound to Oracle Enterprise Scheduler server's JNDI tree. This property is required only if:
|
[ |
Optional for EJB jobs. Specifies the CSF key alias of the authenticated Oracle Enterprise Scheduler server. This property is required only if the Oracle Enterprise Scheduler JNDI tree is authenticated. Example: |
[ |
For EJB jobs, specifies the JNDI mapped name of Oracle Enterprise Scheduler's MetadataService bean defined in the hosting application and bound to the Oracle Enterprise Scheduler server's JNDI tree. This property is required only if you use a hosting application other than |
[ |
For EJB jobs, specifies the JNDI mapped name of Oracle Enterprise Scheduler's RuntimeService bean that is defined in the hosting application and bound to the Oracle Enterprise Scheduler server's JNDI tree. This property is required only if you use a hosting application other than |
[ |
Required for EJB jobs only if the JNDI tree of the EJB server is secured. Points to the CSF alias that is mapped to the user name and password in the keystore. This specific user name/password pair is the credential required to access the secured JNDI for JndiMappedName lookup. This property can be added to either the RequestParameters object or to the Oracle Enterprise Scheduler configuration of the hosting application. |
[ |
Optional for EJB jobs. Specifies the URL of the remote server. Required only if the EJB is remotely located. |
[ |
Required for EJB jobs. Specifies the JNDI lookup name of a remote EJB implementation. Example: |
|
For a process job, this specifies the arguments. |
|
Specifies the log level for Java and PL/SQL request loggers. The default is "INFO". |
|
For a process job type, after the job is successfully started, this property provides a place for Oracle Enterprise Scheduler to save the actual command line (with substitution performed). This property is for diagnostic purposes only. It is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. |
|
Specifies a string indicating whether the job creates files in the file system. The following values are supported:
|
|
Set this to "copy" to have Oracle Enterprise Scheduler upload request log and output files from its content store to a separate repository (UCM). The request log and output content remain in the content store, but are also available to user interfaces and tools that expect log/output in UCM. |
|
Set this to "true" to get environment properties from Fusion Applications-style files. The default is "false". |
|
Set this to "true" to have Oracle Enterprise Scheduler set up extended functionality, such as ApplSession, for each stage of the request if that functionality is available. |
|
For process and Java job types that may create files in the file system, this prompts Oracle Enterprise Scheduler to save in the request the configured RequestFileDirectory and RequestFileDirectoryShared from the ess-config.xml file. These values are saved as the properties SYS_userFileDir and SYS_EXT_userFileDirShared, respectively. Oracle Enterprise Scheduler uses these properties to create the request work and output directories, depending on SYS_EXT_supportOutputFiles. This for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. |
|
Optional. The XML message for the web service cancel operation. |
|
Optional. The cancel operation name. |
|
The base URL part of WSDL URL. |
|
The relative part of the web service WSDL URL (must be a concrete WSDL URL). Either the |
|
The base URL part of endpoint URL. |
|
The endpoint URL for the web service. Either the |
|
The operation name. |
|
The port name. |
|
The service name. |
|
The target name space. |
|
Specifies whether multiple pending requests for the same job definition is allowed. This property has no meaning for a job set step. True or false. |
|
Specifies the logical name of the J2EE application used for request processing. This property is automatically set by Oracle Enterprise Scheduler during request submission. |
|
Specifies the process exit code for a process job request that denotes an execution business error. If this property is not specified, the system treats a process exit code of 4 as an execution business error. This property is optional for a process job type. It is not used for other job types. For more information about business errors, see Searching for a Job Request Using the Advanced Search Feature |
|
Specifies the Java executable for a Java job request. This should be the name of a Java class that implements the |
|
Specifies the command line used to invoke an external program for a process job request. This property is required for a Process job type. It is not used for other job types. |
|
Specifies the logical name of the J2EE application that is the effective application used to process the request. A job definition, job type, or a job set step can be associated with a different application by defining the |
|
Specifies the environment variables to be set for the spawned process of a process job request. The property value should be a comma separated list of name value pairs (name=value) representing the environment variables to be set. This property is optional for a Process job type. It is not used for other job types. |
|
Specifies whether instances of a repeating request with an execution time in the past should be generated. Instances are never generated before the requested start time or after the requested end time. To cause past instances to be generated, you must set this property to TRUE and specify the requested start time as the initial time from which instances should be generated. Note that a null requested start time defaults to the current time. Values for this property are:
If this property is not specified, the system defaults to |
|
For internal use only. |
|
Specifies an identifier for an external portion of an asynchronous Java job. For example, an asynchronous Java job usually invokes some remote process and then returns control to Oracle Enterprise Scheduler. This property can be used to identify the remote process. This property should be set by the job implementation of asynchronous Java jobs when the identifier is known. It is never set by Oracle Enterprise Scheduler. |
|
Optional. The supported values are “ADFBC", “OSB" or “SOA". Any other value is invalid. |
|
Specifies the name of the Oracle Enterprise Scheduler isolation group to which this request is bound. This property is automatically set by Oracle Enterprise Scheduler during request submission. |
|
Specifies input to a job request. The input to a serial job set is forwarded as input to the first step only. The input to a parallel job set is forwarded as input to all the parallel steps. Oracle Enterprise Scheduler imposes no format on the value of this property. |
|
Specifies the working directory used during job request processing for input files. Oracle Enterprise Scheduler sets the value of this property during job request processing. |
|
Specifies the event listener class associated with the request. This should be the name of a Java class that implements the |
|
Specifies a language code to apply to the job. |
|
Oracle Enterprise Scheduler provides the means by which EJB and web service jobs can define an abstract job location. The job location is specified by the Oracle Enterprise Scheduler In the Job Definitions > Job Definition Details page, set the Note that the terms "logical cluster" and "job location" can be used interchangeably. |
|
Specifies the logging working directory. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. |
|
Specifies output from a request. The output of a serial job set is the |
|
Specifies the working directory used during job request processing for output files. Oracle Enterprise Scheduler sets the value of this property during job request processing. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. |
|
Specifies the post-process callout handler class. This should be the name of a Java class that implements the |
|
Specifies the pre-process callout handler class. This should be the name of a Java class that implements the |
|
Specifies the request processing priority. The priority interval is [0...9] with 0 as the lowest priority and 9 as the highest. Default: If this property is not specified, the system default value used is 4. |
|
Specifies the name of the PL/SQL stored procedure to be called for a SQL job request. The stored procedure should be specified using schema.name format. The property is required for a SQL job type. It is not used for other job types. |
|
Specifies the product within the application that submitted the request. |
|
Specifies the file where standard output and error streams are redirected for a process job request. This represents the full path of the log file where the standard output and error streams are redirected for the process when the request is executed. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. |
|
Specifies the callout handler processing delay time. This represents the time, in minutes, to delay request processing when a delay is requested by a callback handler. Default: If this property is not specified, the system default used is 5. Integer type. |
|
Specifies the effective encoding associated with a process job request.
The effective encoding is computed before the process is spawned and is stored in this property. This is later used to determine the encoding for the request log and output. |
|
Specifies that job request can time out. |
|
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 requirements. |
|
Specifies the request processor node on which the request should be processed. This allows processor affinity to be specified for a job request. If this property is not specified, the request can run on any available request processor node. In general, this property should not be specified. If this property is specified for a request, the request processor's work assignments |
|
Specifies the expiration time for a request. This represents the time, in minutes, that a request expires after its scheduled execution time. An expiration value of zero (0) means that the request never expires. If this property is not specified, the system default value used is 0. Request expiration only applies to requests that are waiting to run. If a request waits longer than the specified expiration period, it does not run. After a request starts running the request expiration no longer applies. |
|
Specifies the retry limit for a failed request. If request execution fails, the request retries up to the number of times specified by this property until the request succeeds. If retry limit is zero (0), a failed request is not retried. If this property is not specified, the system default used is 0. |
|
This property enables elevating access privileges for completing a scheduled job. Normally, a request runs as the submitting user. However, if this property is set in the metadata of the job associated with the request, then the request executes under the user identified by this property. This property can only be specified using metadata and cannot be specified as a submission parameter. |
|
Specifies whether the result state of a job set step affects the eventual state of its parent job set. In order for the state of a job set step to be considered when determining the state of the job set, the |
|
Specifies an Oracle Enterprise Scheduler job class to be assigned to the Oracle Enterprise Scheduler job used to execute a SQL job request. This property need not be specified unless the job used for a job request is associated with a particular Oracle Database resource consumer group or has affinity to a database service. If this property is not specified, a default Oracle Enterprise Scheduler job class is used for the job that executes the SQL request. That job class is associated with the default resource consumer group. It belongs to the default service, such that it has no service affinity and, in an Oracle RAC environment, any one of the database instances within the cluster might run the job. No additional privilege or grant is required for an Oracle Enterprise Scheduler SQL job request to use that default job class. This property is optional for a SQL job type. It is not used for other job types. |
|
Specifies the logical name of the J2EE application for the submitted (absolute parent) request. This property is automatically set by Oracle Enterprise Scheduler during request submission. |
|
This property has been deprecated. |
|
Specifies the process exit code for a process job request that denotes an execution success. If this property is not specified the system treats a process exit code of 0 as execution success. This property is optional for a process job type. It is not used for other job types. |
|
Specifies a base directory in the file system where files, such as input and output files, may be stored for use by the request executable. Oracle Enterprise Scheduler supports a configuration parameter that specifies a file directory where requests may store files. At request submission, a This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. Note that if this property is deleted, its value defaults to a system-defined value of <server log path>/ess_request/ and the value of the SYS_EXT_userFileDirShared property is assumed to be false. |
|
Specifies the name of the user used to execute the request. Normally, this is the submitting user unless the |
|
Specifies the process exit code for a process job request that denotes an execution warning. If this property is not specified, the system treats a process exit code of 3 as execution warning. This property is optional for a process job type. It is not used for other job types. |
|
Specifies the working directory for the process of a process job request. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. |
You can delete a job definition.
To delete a job definition:
You can view, create, edit, delete and search for job sets, which are collections of job requests that can be grouped together to run as a single unit. You can nest a job set so that it may contain a collection of job requests or one or more child job sets. Each job request or job set included within a job set is called a job set step.
Note:
To avoid creating a cyclical dependency, do not add a job set to a job set that contains it. For example, if JobSet2
contains JobSet1
, be sure not to add JobSet2
to JobSet1
.
You manage job sets with the Job Sets page in Fusion Middleware Control.
This section contains the following topics:
You can view the job sets created for a given application.
To display job sets:
Figure 5-1 shows the Results table in the Job Sets page. The Results table displays job sets and their attributes, including name, package, execution mode and description.
Figure 5-1 The Job Sets Page and Results Table
You define a job set as either serial or parallel. At runtime, Oracle Enterprise Scheduler runs parallel job set steps together, in parallel. When a serial job set runs, on the other hand, Oracle Enterprise Scheduler runs the steps one after another in a specified sequence. With a serial job set, Oracle Enterprise Scheduler supports conditional branching between steps based on the execution status of a previous step.
For each step in a job set, you can configure an action to be taken on completion of the step, depending on the state of the step. You can also configure parameters and system properties for the job set, such as elevating access privileges to complete a particular job request or specifying the number of times a job can be retried in the event of failure.
To create or edit a job set:
From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Job Metadata and then select Job Sets.
The Job Sets page displays.
From the Applications dropdown list, select the name of the application for which you want to create or edit job sets.
Click Create to define a new job set, or Edit to modify an existing job set.
In the Name field, enter the name of the job set. Fill in the Display Name field with a name that is shown to users. Optionally, add a description in the Description text field, and the name of the relevant job set Java package in the Package text field.
In the Job Set Steps section, select Serial or Parallel to create a serial or parallel job set.
Add steps as required by clicking the Add button. Define each step as required.
In the Step tab, in the Step ID field, enter a meaningful ID for the step. The step ID must be unique for all steps in this job set.
In the Job field, click the search button. In the window that displays, select the job or job set that you want to use for this step, then click OK.
Select Insert into main diagram or Add to list of available steps. If you choose to add the step to the list of available steps, use the dropdown lists that display to select actions for the possible job outcomes, namely On Success, On Error and On Warning.
In the Application Defined Properties tab, click the Add button to define any required parameters and enter their initial value in the field provided. For more information about defining parameters, see Configuring Application Defined Properties.
In the System Properties tab, click the Add button to select system properties and enter their initial value in the field provided. For more information about selecting system properties, see Configuring System Properties.
Click OK.
If you configured the step as a serial step, it displays in the job set flow diagram. Configure the action to be taken upon reaching error and warning states, respectively. From the dropdown list for the error and warning icons, select Stop or the name of the job definition to run upon reaching an error or warning state.
Continue to define steps as required for the job set.
If your job set requires them, define application defined properties and system properties in sections toward the bottom of the job set window.
Configure access control for the job set. For more on defining access control, see Configuring Access Control.
On the Create Job Set page, click OK to save the job set.
You can delete a job set.
To delete a job set:
An Oracle Enterprise Scheduler incompatibility specifies which job definitions should not run simultaneously with one another.
An incompatibility defines either a global incompatibility or a domain-specific, property-based incompatibility.
This section contains the following topics:
The Incompatibilities page displays an incompatibility's name, the Java package associated it, and a description for the incompatibility.
To view job incompatibilities:
An incompatibility consists of one or more job definitions configured as incompatible, and optionally the resource over which they must be incompatible. A resource is not specified for a global incompatibility.
In a domain incompatibility, the resource is represented by the property name that forms the Incompatibility. The property name might be different across job definitions. For example, if two job definitions, JobA and JobB, are made incompatible, then the property identified for incompatibility might have different names in JobA and JobB.
The following gives more information about the difference between domain and global incompatibilities:
Domain-specific: In a domain incompatibility, Oracle Enterprise Scheduler ensures that requests for the incompatible jobs or job sets, with a property that has the same property value, do not run at the same time.
You add two or more job definitions as incompatible within the scope of a resource, where the resource is identified by a system property name or a parameter name. Each entity can use the same property name or a different property name. For a property-based incompatibility, you must specify a job definition or a job set and a property name for each entity.
Global: In a global incompatibility, Oracle Enterprise Scheduler ensures that requests for the incompatible jobs or job sets do not run at the same time.
Two or more job definitions cannot run together at any time. A global incompatibility is used when the incompatible entities are not to be run at the same time regardless of any property. For global incompatibility, only the job definition or job set is specified for each entity.
Usually an incompatibility is defined using two or more job or job set entities. An incompatibility can be defined for one entity as long as that entity is marked as self-incompatible. A self-incompatibility implies that multiple job requests associated with that job or job set cannot run together.
Defining an incompatibility involves the following:
Package and scope: Select a relevant Java package to use for the incompatibility and set the scope for the incompatibility (global or domain only).
Jobs: Select the jobs that are incompatible.
Parameters and properties: Define parameters and properties as required.
Access control: Define access control as required.
To create or edit an incompatibility:
Deleting an incompatibility results in the incompatible job requests or job sets becoming compatible again.
To delete an incompatibility:
Typically, customization of existing Oracle Enterprise Scheduler jobs involves editing job properties using Oracle Enterprise Manager Fusion Middleware Control or Oracle JDeveloper. This approach is limited and repetitive for customers interested in bulk updates of job properties. The System MBean Browser and the bulk customization APIs enable you to customize the property of a piece of metadata in bulk for a number of jobs without changing the base metadata.
Table 5-2 lists the properties that can be updated and customized in bulk.
Table 5-2 Properties That Can be Updated and Customized in Bulk
Properties |
---|
|
|
|
|
|
|
|
The bulk customization API can be conveniently invoked from the Oracle Enterprise Manager Fusion Middleware Control System MBean Browser. The process has two steps:
The following example shows how to use the System MBean Browser to export and customize job definition properties.
Start the Oracle Enterprise Manager Fusion Middleware Control System MBean Browser by choosing it from the Weblogic Domain menu as shown in Figure 5-2.
Figure 5-2 Start the Oracle Enterprise Manager Fusion Middleware Control System MBean Browser
In the System MBean Browser, navigate to your application's MetadataService entry. Figure 5-3 shows an example. Note that your server and application names may be different.
Figure 5-3 Navigation Path to MetadataService
Click on the Operations tab as shown in Figure 5-4.
Figure 5-4 Choose the exportESSJobMetadataBulk Item
Click on the exportESSJobMetadataBulk item (Figure 5-4) to invoke the Operation:exportESSJobMetadatBulk page.
On the Operation:exportESSJobMetadatBulk page, fill in the fields in the Value column using the parameters listed in Table 5-3 and then click Invoke. Figure 5-5 shows an example.
Figure 5-5 Operation: exportESSJobMetadataBulk Page
The following tables show additional examples of parameters and values that might be used in the Operation: exportESSJobMetadataBulk page.
|
|
|
Click Return to return to the MetadataService page and then click on the customizeJobDefinitionBulk item to invoke the Operation:customizeJobDefinitionBulk page.
Figure 5-6 Choose the customizeJobDefinitionBulk Item
Fill in the fields in the Value column as shown in Figure 5-7. The xmlInputFile entry is the name of the file to which you previously exported the parameters. Click the Invoke button to complete the customization.
Figure 5-7 The Operation: customizeJobDefinition Page
The bulk customization API is comprised of two methods, exportESSJobMetadataBulk
and customizeJobDefinitionBulk
.
This method exports the list of job definition properties that can be customized. This method queries the job definitions that match the specified filter criteria in the Oracle Enterprise Scheduler hosting application MDS repository.
The generated XML output file can be edited by an administrator. This file serves as the input to the customizeJobDefinitionBulk
method described in customizeJobDefinitionBulk Method.
void exportESSJobMetadataBulk (java.lang.String xmlOutputFile, java.lang.String filterQueryField, java.lang.String filterComparator, java.lang.String filterValue, java.lang.String application) throws java.io.IOException, javax.management.RuntimeOperationsException
Table 5-3 exportESSJobMetadataBulk Parameters
Parameter | Description |
---|---|
|
The absolute path of the output XML file to which the list of the job definitions' customizable properties is exported. |
|
The name of the query field by which to filter. The following are the supported query fields:
These query fields are defined in the package |
|
The name of the filter comparison operator. The following are the supported comparators:
These comparators are defined in the package |
|
The value with which to compare the filter query field. |
|
The name of the Oracle Enterprise Scheduler hosting application whose metadata repository is to be used. |
Table 5-4 exportESSJobMetadataBulk Exceptions
Exception | Description |
---|---|
j |
Thrown if a protocol error occurs. |
|
Thrown if the metadata sub-system encounters failures. |
This method customizes the job definition property metadata definitions defined in the input XML file generated by the exportESSJobMetadataBulk
method without changing the base metadata. The MDS metadata customization functionality is used, and an exception is thrown if the properties are not members of the one of the MetadataService.CustomizableProperty
enumerations.
This method modifies the base metadata for job definition properties that belong to the custom name space /oracle/apps/ess/custom
.
Note:
In order for this feature to work correctly, the application must define a customization class in its adf-config.xml
file. Refer to the MDS documentation for more information.
void customizeJobDefinitionBulk (java.lang.String xmlInputFile, java.lang.String application) throws java.io.IOException, javax.management.InstanceNotFoundException, javax.management.OperationsException, javax.management.InvalidAttributeValueException, javax.management.RuntimeOperationsException
Table 5-5 customizeJobDefinitionBulk Parameters
Parameter | Description |
---|---|
|
The path to the input XML file that contains the exported list of job definitions. The format of the file is dictated by the output of the |
|
The name of the application whose metadata repository is to be used. |
Table 5-6 customizeJobDefinitionBulk Exceptions
Exception | Description |
---|---|
|
Thrown if a protocol error occurs. |
|
Thrown if the validation of the definition fails. |
|
Thrown if the metadata sub-system encounters failures. |
|
Thrown if the specified MBean does not exist in the repository. |
|
Represents exceptions thrown in the MBean server when performing operations on MBeans. |