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.
This chapter explains how to create and implement your custom scheduled tasks. It contains these topics:
Overview of Task Creation
Defining the Metadata for the Scheduled Task
Configuring the Scheduled Task XML File
Developing the Scheduled Task Class
Configuring the Plug-in XML File
Creating the Directory Structure for the Scheduled Task
Scheduled Task Configuration File
This section outlines the essential steps in creating scheduled tasks, and presents an example to illustrate the process. Subsequent sections provide details on each step.
Example of Scheduled Task
The basic steps for configuring new scheduled tasks are as follows:
Review Oracle Identity Manager's predefined scheduled tasks to determine whether a custom task is necessary.
For details about the predefined tasks, see "Managing Scheduled Tasks" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager.
Determine key features of the scheduled task, such as the task name and the parameters that control the actions performed by the task.
For details, see Section 26.2, "Defining the Metadata for the Scheduled Task".
Add the task metadata to the scheduled task XML file.
For details, see Section 26.3, "Configuring the Scheduled Task XML File".
Develop the scheduled task Java class.
For details, see Section 26.4, "Developing the Scheduled Task Class".
Declare the new scheduled task as a plug-in.
For details, see Section 26.5, "Configuring the Plug-in XML File".
Package the task files so that Oracle Identity Manager can locate the files and make the task available for jobs.
For details, see Section 26.6, "Creating the Directory Structure for the Scheduled Task".
To illustrate the steps in developing a scheduled task, we use an example scheduled task that retrieves employee records belonging to the given department from a given IT resource.
In addition, our scheduled task should allow the user to specify the number of records to be retrieved and whether to include disabled records in the retrieval.
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
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:Chapter 27, "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 Section 26.2, "Defining the Metadata for the Scheduled Task".
Example 26-1 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.
Example 26-1 Sample XML for a Scheduled Task
<scheduledTasks xmlns=""> <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-paramDepartment Name</string-param> <string-paramDepartment Name</string-param> <number-paramNumber of Records</number-param> <boolean-paramGet 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.
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:
Create a Java class file that extends the
oracle.iam.scheduler.vo.TaskSupport class and overrides the
execute() method with processing logic based on your requirements.
Create a JAR file for the Java class that you created. 27, .
Specify the plug-in point for the scheduled task by changing the value of the
pluginpoint attribute of the plugins element to
oracle.iam.scheduler.vo.TaskSupport.
The following XML code block from the plugin.xml file shows the value entered within the plugins element:
<plugins pluginpoint="oracle.iam.scheduler.vo.TaskSupport">
Note:For scheduled tasks, the <plugins> element remains the same for all scheduled tasks.
Add a <plugin> element for each scheduled task that you are adding.
To specify the class that implements the plug-in (in this case, the scheduled task), change the value of the
pluginclass attribute of the plugin element to the name of the Java class that implements the scheduled task. The following XML code block from the plugin.xml file shows sample values entered within the plugin element:
<plugin pluginclass= "oracle.iam.scheduler.TestScheduler" version="1.0.1" name="scheduler element"/>
After modification, the plugin.xml file looks similar to the following:
<?xml version="1.0" encoding="UTF-8"?> <oimplugins xmlns: <plugins pluginpoint="oracle.iam.scheduler.vo.TaskSupport"> <plugin pluginclass= "oracle.iam.scheduler.TestScheduler" version="1.0.1" name="scheduler element"> </plugin> </plugins> </oimplugins>
Save and close the plugin.xml file.
The final step in configuring the scheduled task is to create a plugin.zip file with the directory structure specified in Example 26-2. 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.
Example 26-2 Directory Structure for the Scheduled Task
plugin/ lib/ PLUGIN.JAR plugin.xml META-INF (optional) METADATA.xml
Note that:
The XML file for the plug-in must be named plugin.xml.
The lib/ directory must contain only .JAR files. The 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.
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 Section 26.4, "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.
This appendix describes the structure and details of the XML file containing scheduler task definitions.
Structure of the Scheduler XML File
The scheduledTasks Element
The boolean-param Element
The following is a list of elements in the configuration XML file:
<scheduledTasks xmlns=""> <task> <name> <class> <description> <retry> <parameters> <string-param> ..... </string-param> <number-param> ....... </number-param> <boolean-param> ....... </boolean-param> </parameters> </task> </scheduledTasks>
The scheduledTasks element is the root element in XML used to define scheduled tasks.
Table 26-1 summarizes the properties of the scheduledTasks 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 26-2 summarizes the properties of the task 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 26-3 summarizes the properties of the name 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 26-4 summarizes the properties of the class 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 26-5 summarizes the properties of the description element.
Table 26-6 summarizes the properties of the retry 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 26-7 summarizes the properties of the parameters 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 26-8 summarizes the properties of the string-param element.
As listed in Table 26-8, the string-param element contains the following attributes:
required
This is a mandatory attribute and it can take a value of either
true or
false.
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 either
true or
false.
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.
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 26-9 summarizes the properties of the number-param element.
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.
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 26-10 summarizes the properties of the boolean-param element.
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.