16 Developing Scheduled Tasks
Oracle Identity Manager contains a set of predefined tasks that can be scheduled as job runs. An example is a password warning task that sends email to users for password expiration. Oracle Identity Manager also provides the capability of creating your own scheduled tasks. You can create scheduled tasks according to your requirements if none of the predefined scheduled tasks fit your needs. For example, you can configure a reconciliation run using a scheduled task that checks for new information on target systems periodically and replicates the data in Oracle Identity Manager.
The following sections describe how to create and implement your custom scheduled tasks:
16.1 Overview of Task Creation
Review Oracle Identity Manager's predefined scheduled tasks to determine whether a custom task is necessary.
This section outlines the essential steps in creating scheduled tasks, and presents an example to illustrate the process. It contains the following topics:
16.1.1 Steps in Task Creation
Creating a scheduled task involves updating the scheduled task XML file with task metadata, developing the scheduled task Java class, packaging the scheduled task as a plug-in, and packaging the task files.
The basic steps for configuring new scheduled tasks are as follows:
16.1.2 Example of Scheduled Task
To illustrate the steps in developing a scheduled task, use an example scheduled task that retrieves employee records belonging to the given department from a given IT resource.
In addition, the scheduled task should allow the user to specify the number of records to be retrieved and whether to include disabled records in the retrieval.
16.2 Defining the Metadata for the Scheduled Task
Metadata for a scheduled task includes mandatory information about the task and optional parameters that the task accepts.
Each scheduled task contains the following metadata information:
-
Name of the scheduled task
-
Name of the Java class that implements the scheduled task
-
Description
-
Retry Interval
-
(Optional) Parameters that the scheduled task accepts. Each parameter contains the following additional information:
-
Parameter Name
-
Parameter Data Type
-
Required/ Optional Parameter
-
Help Text
-
16.3 Configuring the Scheduled Task XML File
Configuring the scheduled task XML file involves updating the XML file that contains the definitions of custom scheduled tasks.
This section describes how to update the task XML file with the details of the new custom scheduled task.
You can modify the task.xml file located in the /db namespace of Oracle Identity Manager MDS schema, or you can create a custom scheduled task file. If you create a custom file, then the file name must be the same as the scheduled task name, with the .xml extension. You must import the custom scheduled task file to the /db namespace of Oracle Identity Manager MDS schema.
See Also:
Developing Plug-ins for examples of plug-ins.
Note:
The scheduled task XML file can be imported into MDS using the Oracle Enterprise Manager. In a clustered environment, having the file in MDS avoids the need to copy the file on each node of the cluster.
For details about importing files into MDS, see Migrating User Modifiable Metadata Files.
The elements in the XML file reflect the task parameters that you described in Defining the Metadata for the Scheduled Task.
The following example shows a sample XML code for the scheduled task described in the preceding paragraph. Note that all the parameters are declared to be required parameters in this example.
<scheduledTasks xmlns="http://xmlns.oracle.com/oim/scheduler"> <task> <name>Test_scheduled_task</name> <class>oracle.iam.scheduler.TestScheduler</class> <description>Retrieve Employee Records For Given Department</description> <retry>5</retry> <parameters> <string-param required="true" encrypted="false" helpText="Name of the department">Department Name</string-param> <number-param required="true" helpText="Number of Records to Be Retrieved">Number of Records</number-param> <boolean-param required="false" helpText="Retrieve disabled employee records?">Get Disabled Employees</boolean-param> </parameters> </task> </scheduledTasks>
See Also:
Scheduled Task Configuration File for details about the elements in the scheduled task configuration file.
This is basically exporting the task.xml from MDS and then adding the required tags to it and importing it back into MDS.
Note:
For a task defined in a plugin, the metadata XML is not required to be seeded to MDS. This can be included in the META-INF folder in the plugin ZIP file. For details, see Creating the Directory Structure for the Scheduled Task.
You must export the task.xml file from MDS, add the required tags to the file, and then import it back to MDS. See Migrating User Modifiable Metadata Files for information about exporting and importing MDS files.
16.4 Developing the Scheduled Task Class
The Java class that implements a scheduled task is known as a scheduled task class.
The next step is to create a Java class to execute the task whose metadata was defined in the XML file. The Java class that implements a scheduled task is known as a scheduled task class.
To develop a Java class for the scheduled task:
16.5 Configuring the Plug-in XML File
You must configure the plugin.xml file in order to declare the scheduled task as a plug-in.
See Developing Plug-ins for more information about plug-ins.
Note:
Oracle recommends creating one plugin.xml file for one scheduled task. This is because when the plugin is unregistered, the corresponding package is deleted.
To configure the plugin.xml file:
16.6 Creating the Directory Structure for the Scheduled Task
The plugin.zip file that you create must contain a specific directory structure.
The final step in configuring the scheduled task is to create a plugin.zip file with the directory structure, as shown:
plugin/ lib/ PLUGIN.JAR plugin.xml META-INF (optional) METADATA.xml
In this example, a single plug-in is being added, but there can be multiple plugins in the plugin.zip file. Scheduler requires that files be zipped in a particular structure and named according to a particular naming convention. This ensures that Oracle Identity Manager identifies the custom scheduled tasks and makes it available in Oracle Identity System Administration while creating jobs.
Note that:
-
The XML file for the plug-in must be named plugin.xml.
-
The lib/ directory must contain only .JAR files. The lib/ directory consists of JAR files that contains the classes implementing the plug-in logic and the dependent library JAR files. In most instances, this directory consists of a single JAR file with the implementation of all the plug-ins that are specified in plugin.xml. See Developing Plug-ins for information about the directory structure.
-
The directory for the scheduled task must contain the following files:
-
XML for the plug-in
-
JAR files
-
-
There is one plugin.zip file for all the plug-ins that you create.
-
The META-INF folder is an optional folder, in which metadata (task definition) file can be stored. If this file is placed in the META-INF folder, then it is not required to be seeded in MDS.
Note:
If the task definition XML file is stored in the META-INF directory rather than seeded to MDS, then there is a limitation of exporting the scheduled task by using the Deployment Manager. -
If META-INF folder does not exist or if the metadata file is not placed in the META-INF folder, then seed the file to MDS.
In the preceding example, CLASS_NAME.JAR is the JAR file that you create in Developing the Scheduled Task Class.
After you create the plugin.zip file, if deploying in a clustered environment, register the plug-in to the database by using appropriate APIs. See Registering and Unregistering Plug-ins By Using APIs for details about registering plug-ins to Oracle Identity Manager by using APIs.
Note:
The XML for the plug-in must be named plugin.xml. Ensure that the lib directory contains only JAR files.
16.7 Scheduled Task Configuration File
Scheduled task definitions is contained in a XML file, which is called the scheduled task configuration file.
This section describes the structure and details of the XML file containing scheduler task definitions. It contains the following topics:
16.7.1 Structure of the Scheduler XML File
Some of the elements in the scheduled task configuration XML file are <name>, <class>, <description>, <retry>, and <parameters>.
The following is a list of elements in the configuration XML file:
<scheduledTasks xmlns="http://xmlns.oracle.com/oim/scheduler"> <task> <name> <class> <description> <retry> <parameters> <string-param> ..... </string-param> <number-param> ....... </number-param> <boolean-param> ....... </boolean-param> </parameters> </task> </scheduledTasks>
16.7.2 The scheduledTasks Element
The scheduledTasks element is the root element in XML used to define scheduled tasks.
Table 16-1 summarizes the properties of the scheduledTasks element.
Table 16-1 Properties of the scheduledTasks Element
Property | Value |
---|---|
Parent Element |
NA |
Attributes |
The XML namespace is specified as an attribute of the scheduledTasks element as follows: <scheduledTasks xmlns="http://xmlns.oracle.com/oim/scheduler"> Note: The xmlns parameter is mandatory. |
Child Elements |
task |
Number of Occurrences |
One for each scheduled task XML file to be created. |
Element Value |
NA |
Mandatory or Optional? |
Mandatory |
16.7.3 The task Element
The task element is the child element of the scheduledTasks element.
You use the task element to define a scheduled task. The task element contains information about the scheduled task, for example, the name, class, description, and retry count of the scheduled task.
Table 16-2 summarizes the properties of the task element.
Table 16-2 Properties of the task Element
Property | Value |
---|---|
Parent Element |
scheduledTasks |
Attributes |
None |
Child Elements |
name, class, description, retry, and parameters |
Number of Occurrences |
One for each task to be created. NOTE: If you want to define more than one task in a single scheduled task XML file, you must use one task element for every scheduled task being defined. |
Element Value |
NA |
Mandatory or Optional? |
Mandatory |
16.7.4 The name Element
The name element is the child element of the task element. The name element is used to specify the name of the scheduled task being created.
Table 16-3 summarizes the properties of the name element.
Table 16-3 Properties of the name Element
Property | Value |
---|---|
Parent Element |
task |
Attributes |
None |
Child Elements |
None |
Number of Occurrences |
One |
Element Value |
Name of the scheduled task being created. Note: The name of the scheduled task must be unique. |
Mandatory or Optional? |
Mandatory |
16.7.5 The class Element
The class element is a mandatory element and is the child element of the task element. You use the class element to specify the name of the Java class that runs the scheduled task.
Table 16-4 summarizes the properties of the class element.
Table 16-4 Properties of the class Element
Property | Value |
---|---|
Parent Element |
task |
Attributes |
None |
Child Elements |
None |
Number of Occurrences |
One |
Element Value |
Name of the Java class that runs the scheduled task. See Developing the Scheduled Task Class for information on developing a class for the scheduled task. |
Mandatory or Optional? |
Mandatory |
16.7.6 The description Element
The description element is a mandatory element and is the child element of the task element. You can use the description element to provide a description of the task being created.
Table 16-5 summarizes the properties of the description element.
Table 16-5 Properties of the description Element
Property | Value |
---|---|
Parent Element |
task |
Attributes |
None |
Child Elements |
None |
Number of Occurrences |
One |
Element Value |
Description of the task being created |
Mandatory or Optional? |
Mandatory |
16.7.7 The retry Element
You can use the retry element to provide the number of seconds the scheduler must wait before it tries to schedule the task again.
Table 16-6 summarizes the properties of the retry element.
Table 16-6 Properties of the retry Element
Property | Value |
---|---|
Parent Element |
task |
Attributes |
None |
Child Elements |
None |
Number of Occurrences |
One |
Element Value |
Number of seconds the scheduler must wait before it tries to schedule the task again |
Mandatory or Optional? |
Mandatory |
16.7.8 The parameters Element
If you want to specify parameters at run time that the scheduled task requires for a successful job run, you must use the parameters element. For example, you might create a scheduled task that requires the user to specify the number of records to be retrieved at run time.
The parameters specified within this element are displayed under the Parameters section on the Create Job page.
Table 16-7 summarizes the properties of the parameters element.
Table 16-7 Properties of the parameters Element
Property | Value |
---|---|
Parent Element |
task |
Attributes |
None |
Child Elements |
string-param, number-param, boolean-param |
Number of Occurrences |
One |
Element Value |
NA |
Mandatory or Optional? |
Optional |
16.7.9 The string-param Element
You can use the string-param element to specify the name of the field that can take a value of the string data type. In other words, the string-param element specifies a label for the field that can hold a value of the string data type.
Table 16-8 summarizes the properties of the string-param element.
Table 16-8 Properties of the string-param Element
Property | Value |
---|---|
Parent Element |
parameters |
Attributes |
required, helpText, encrypted |
Child Elements |
None |
Number of Occurrences |
One for every parameter of the string data type |
Element Value |
Name of the string parameter |
Mandatory or Optional? |
Optional |
As listed in Table 16-8, the string-param element contains the following attributes:
-
required
This is a mandatory attribute and it can take a value of either
true
orfalse
.If the value of the required attribute is
true
, it is mandatory to enter a value for the parameter at run time.If the value of the required attribute is
false
, it is not mandatory to enter a value for the parameter at run time. -
helpText
Use this attribute to specify the text that must appear at run time to help users know what to enter in the field. The text that is specified is usually the description of the field that is being created by the parameter.
-
encrypted
By default, it has a value of
false
and this can take a value of eithertrue
orfalse
.If the value of the encrypted attribute is
true
, then the entered value for the parameter at run time is stored in encrypted form.If the value of the required attribute is
false
, then the entered value for the parameter at run time is stored in plain text.
16.7.10 The number-param Element
You can use the number-param element to specify the name of the field that can take a value of the long data type.
Table 16-9 summarizes the properties of the number-param element.
Table 16-9 Properties of the number-param Element
Property | Value |
---|---|
Parent Element |
parameters |
Attributes |
required, helpText |
Child Elements |
None |
Number of Occurrences |
One for every parameter of the long data type |
Element Value |
Name of field that can hold a long data type |
Mandatory or Optional? |
Optional |
The behavior and description of the require and helpText attributes for the number-param and string-param elements is the same. See The string-param Element for information about the require and helpText attributes.
16.7.11 The boolean-param Element
You can use the boolean-param element to specify the name of the field that can take a value of the boolean data type.
Table 16-10 summarizes the properties of the boolean-param element.
Table 16-10 Properties of the boolean-param Element
Property | Value |
---|---|
Parent Element |
parameters |
Attributes |
required, helpText |
Child Elements |
None |
Number of Occurrences |
One for every parameter of the boolean data type |
Element Value |
Name of field that can hold a boolean data type |
Mandatory or Optional? |
Optional |
The behavior and description of the require and helpText attributes for the boolean-param element and the string-param element is the same. See The string-param Element for information about the require and helpText attributes.
16.8 Best Practices for Creating Custom Scheduled Tasks
Variables and/or constants are used for creating custom scheduled tasks.
Table 16-11 provides the guidelines for using variables/constants for creating custom scheduled tasks:
Table 16-11 Variables and Constants for Creating Custom Scheduled Tasks
Type | Example | Stor/Retrieve Value From |
---|---|---|
Target system connection details |
Hostname, port number, SSL |
IT Resource/application instance |
Target system configurations |
Attribute mappings, Unique Attribute, User Object Class |
Lookup |
Scheduled job-specific variables/constants |
Application Instance Name, IT Resource Name, File Path, Search Filter, Batch Size, Retries |
Scheduled job |
Scheduled job advanced configuration variables/constants |
Attribute Mappings, Target system Date Format, Constants, Attribute Transformation Classes |
Lookup |
Oracle Identity Manager-specific system wide highly static configuration properties/constants/variables |
Default Date Format, Default policy for username generation |
System properties |
Email notifications |
Subject, Body, To, From |
Email templates |
16.9 Using the isStop() Method
The isStopped() method is called to add a check for getting the jobs status.
When a job is stopped from the Scheduler section in Oracle Identity System Administration, the job does not stop and keeps running. To stop the scheduled task, you can perform the following:
If you have developed a custom scheduled task, then you can call the isStop() or isStopped() method at various stages inside the execute method. If this method returns true, then return from the execute method. If you have loops inside the execute method, then make sure that the isStop() or isStopped() method is called for each loop iteration.
In the execute method, add a check for getting the job status. This can be obtained by calling the isStopped() method of the com.thortech.xl.scheduler.tasks.SchedulerBaseTask class. If the isStopped() method returns TRUE, then return from the execute method without performing any execution for the scheduled task. The following is the code snippet for this:
if(isStopped()) return;
If you develop a custom scheduled task by extending the TaskSupport class, then call the isStop() method in the execute method.
If the custom scheduled task code is extending legacy com.thortech.xl.scheduler.tasks.SchedulerBaseTask class of Oracle Identity Manager Release 9.x, then call the isStopped() method in the execute method.
16.10 Monitoring Scheduled Jobs Performance using DMS
Dynamic Monitoring Service (DMS) can be used to view performance metrics.
The OIM_ScheduledJob
DMS metrics is present for monitoring the performance of scheduled jobs. It provides details, such as number of scheduled jobs run and average time taken by scheduled job. Details of the successful jobs come under the execute
column while failed job details come under the Failed_execute
column.