Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Identity Manager
11g Release 2 (11.1.2)

Part Number E27150-04
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

8 Using the Adapter Factory

Adapters are Java programs that enable you to integrate Oracle Identity Manager with other software solutions. This chapter describes how to create adapters using the Adapter Factory form. It contains these sections:

8.1 Introduction to Adapters

To be effective, it must be possible to integrate an access rights management application, such as Oracle Identity Manager, with other software solutions. This is necessary not only because there are many resources, but also because there is no single integration standard for connecting to these resources.

The traditional way to tackle this challenge is by using the common functionality that is supported by all the integrations. To do this, you need developers who can write this code. In addition, every time an existing software resource is modified, or a new one is added, you must write more code.

The Adapter Factory is a code-generation tool provided by Oracle Identity Manager. It helps you create Java classes, known as adapters, that simplify the integration challenge.

Note:

Oracle Identity Manager can connect to external systems such as databases and directory servers by using Java APIs for JDBC and LDAP. In addition, for all other APIs, such as C, C++, VB, and COM/DCOM, you can create a Java wrapper so that Oracle Identity Manager can communicate with the API directly.

A resource has an associated provisioning process, which in turn has various tasks associated with it. Each task in turn has an adapter associated to it, which in turn can connect to the target resource to carry out the required operations.

An adapter provides the following benefits:

Adapters can be developed for a range of tasks:

8.2 Types of Adapters

This section provides additional details about the five adapter types.

Rule Generator Adapters

Certain business rules must be applied to perform field validations and enter default values into the forms which either come packaged with Oracle Identity Manager or are created by Oracle Identity Manager users. For example, for the Users form, you might want Oracle Identity Manager to generate the User ID automatically by concatenating the user's first name and last name.

To do this, you must create a specific type of adapter, which is designed to modify the field value in a form. This type of adapter, which can generate, modify, or verify the value of a form field automatically, is called a rule generator. Oracle Identity Manager triggers a rule generator on preinsert and preupdate.

After you create this adapter and attach it to a form, Oracle Identity Manager automatically updates the field value for all records of that form, and saves this information to the Oracle Identity Manager database.

If you create a rule generator that contains adapter variables, you must map these adapter variables to their proper locations. Otherwise, the adapter will not be functional.

You can also attach this type of adapter to a provisioning process. Once the process is provisioned to a target user or organization, Oracle Identity Manager will trigger the associated rule generator.

On occasion, a rule generator which has been assigned to a provisioning process might no longer be needed to complete the process. If this happens, you can remove the rule generator from the provisioning process. Similarly, after you attach one rule generator to a form field, you can connect a different rule generator to that form field. When this occurs, you must first remove the rule generator currently attached to the form field.

Entity Adapters

Similar to rule generator adapters, entity adapters are also responsible for generating, modifying, or verifying the value of a form field automatically, and saving this information to the Oracle Identity Manager database.

Note:

In Oracle Identity Manager 11g Release 2 (11.1.2), creating new entity adapters and modifying existing entity adapters are not supported. However, if you have upgraded from Oracle Identity Manager Release 9.x, then the existing entity adapters continue to work, and you can view the existing variable mappings of the adapters.

Some differences between rule generators and entity adapters are:

Task Assignment Adapters

For a process task that must be completed manually, you can configure Oracle Identity Manager to automate the assignment of the task to either a specific user or a user who belongs to a particular role. This is achieved through the use of a task assignment adapter. Task assignment adapters are used only for assigning a task to a particular user or role.

When a task that is associated with specific provisioning process is created using the Tasks tab in the Process Definition form of the Design Console, you can choose the rule that decides if adapter will be picked up for execution. Note that this rule is defined in the Rule Definition form of the Design Console. An example of a rule is "Target User's Org name is XYZ. If this rule is satisfied, then the corresponding task assignment is picked up. However, you can have multiple rules defined and used while deciding task assignment. For multiple rules, Oracle Identity Manager associates priority with the task assignment functionality to decide the order in which the rule determination must occur. When the rule is determined, corresponding task assignment is run.

Note:

In other words, the task assignment rule allows Oracle Identity Manager to decide whether to assign a process task to a user or role. The task assignment adapter enables Oracle Identity Manager to determine which user or role will be the recipient of the process task.

For this example, Oracle Identity Manager will trigger the Associate Adapter with User rule first (because it has the highest priority). If the condition of this rule is TRUE, it is successful. As a result, Oracle Identity Manager will associate the related task assignment adapter (the Assign Task to User adapter) with the process task.

On the other hand, when the condition of a rule is FALSE, the rule has failed. Oracle Identity Manager triggers the rule with the next highest priority. If this rule is successful, then Oracle Identity Manager assigns the designated adapter to the target process task.

So, in this example, if the Associate Adapter with User rule fails, then Oracle Identity Manager triggers the Associate Adapter with Role rule. If this rule is successful, then Oracle Identity Manager associates the related task assignment adapter (the Assign Task to Role adapter) to the process task.

After assigning a rule to a task assignment adapter, if this type of adapter contains adapter variables, you must map these variables to their proper locations. Otherwise, the adapter will not be functional.

Finally, when a task assignment adapter becomes invalid, or is no longer necessary for Oracle Identity Manager to allocate the process task to a user or group, you must remove the adapter from the task.

Prepopulate Adapters

Sometimes a user-created form contains both fields that can be populated by Oracle Identity Manager and fields into which an Oracle Identity Manager user must enter data. When the information that the user types into a field is contingent upon the data that appears in a system-generated field, Oracle Identity Manager must first populate this field. When the form is displayed, the user can view the system-generated data to enter information into the appropriate fields.

This is achieved by creating a type of rule generator known as a prepopulate adapter. By attaching it to a field designated to be system-generated, you enable Oracle Identity Manager to automatically populate this field with the appropriate information, without saving this information to the Oracle Identity Manager database.

The data generated by a prepopulate adapter can appear automatically or it can be manually entered. Oracle Identity Manager displays this information automatically when the Auto-prepopulate check box is selected for a provisioning process. When this check box is cleared, an Oracle Identity Manager user must manually generate the displaying of the data that is generated by the prepopulate adapter. To do this, click the prepopulate button on the form section of the Direct Provisioning wizard in the Web client, while provisioning the form to a user.

You can use the same prepopulate adapter for different form fields. In addition, you can designate multiple prepopulate adapters to be associated with a particular field. As a result, Oracle Identity Manager must know which prepopulate adapter it must select for the form field. This requires the use of prepopulate rules. These rules enable Oracle Identity Manager to select one prepopulate adapter, which is associated with a form field, when this prepopulate adapter is assigned to the field.

Each prepopulate adapter has a prepopulate rule associated with it. In addition every rule has a priority number which indicates the order in which Oracle Identity Manager triggers it.

For example, Oracle Identity Manager can trigger the Rule for Uppercase User ID rule first because it has the highest priority. If the condition of this rule is TRUE, it is successful. As a result, Oracle Identity Manager will attach the related prepopulate adapter (the Display Uppercase Letters for User ID adapter) to the User ID field.

On the other hand, when the condition of a rule is FALSE, the rule has failed. Oracle Identity Manager will trigger the rule with the next highest priority. If this rule is successful, Oracle Identity Manager will attach the associated adapter to the designated field.

So, in this example, if the Rule for Uppercase User ID rule fails, Oracle Identity Manager will trigger the Rule for Lowercase User ID rule. If this rule is successful, Oracle Identity Manager will attach the related prepopulate adapter (the Display Lowercase Letters for User ID adapter) to the User ID field.

After assigning a rule to a prepopulate adapter, if this type of adapter contains adapter variables, you must map these adapter variables to their proper locations. Otherwise, the adapter will not be functional.

Finally, when a prepopulate adapter associated with a field is no longer valid, you must remove the adapter from the field.

Process Task Adapters

A process task adapter enables Oracle Identity Manager to automatically execute process tasks in provisioning processes.

Each process and process task has a status, which indicates the stage of its completion. The statuses for a process or process task are listed in the following table in order of importance.

Task Status Description

C

Completed: This process/process task has been completed successfully.

MC

Manually Completed: This process task has been completed successfully by an Oracle Identity Manager user (that is, manually).

P

Pending: This process/process task is in the process of being completed. All preceding tasks and processes, respectively, have been completed.

PX

Pending Cancellation: This process task will be canceled, but this task has to be completed first before it can be canceled.

R

Rejected: This process/process task has not been completed successfully or has not been approved. The status of rejected process tasks can only be changed to Canceled or Unsuccessfully Completed.

S

Suspended: This process/process task has been put on hold temporarily.

UC

Unsuccessfully Completed: This process task has been set to Completed. However, it had been rejected before.

W

Waiting: This process/process task cannot be completed until all preceding process tasks or processes are completed.

X

This process/process task has been stopped. Its status cannot change anymore


The status level of a process represents the most important status level of its process tasks, which must be completed for the process to be completed. Suppose a process has three process tasks, each process task has a different status level (Completed, Waiting, and Rejected), and all three process tasks must be completed for the process to complete. Because the highest task status level is Rejected, the status level of the process is also Rejected.

A process task can be managed in these ways:

8.3 Adapter Environment and Tools

This section contains these topics:

8.3.1 Configuring the Adapter Environment

To construct adapter tasks, ensure that Oracle Identity Manager has access to the target API JAR files and third-party applications to which you want to connect.

When your adapter uses Java tasks, you must configure Oracle Identity Manager to find the appropriate Java APIs. To do this, you must place the .jar files that contain these APIs into the Meta Data Store (MDS).

See Also:

Chapter 35, "Understanding Customization Types" for information about utilities to modify Oracle Identity Manager metadata

Then, you can access the Java classes associated with these Java APIs and use them in the Java task you are creating.

To configure Oracle Identity Manager to reference JAR and class files:

  1. Open the JavaTasks subdirectory, which can be found within the OIM_HOME/ directory path. For example, C:\oracle\Xellerate\JavaTasks.

  2. Place the JAR file or files into this subdirectory. You can use these files to create Java tasks within an adapter without restarting the server.

8.3.2 Remote Manager

Sometimes, instead of directly communicating with the third-party system, Oracle Identity Manager must use an Oracle Identity Manager component that acts like a proxy. This component is known as Remote Manager.

The Remote Manager is used for:

  • Invoking nonremotable APIs through Oracle Identity Manager

  • Invoking APIs that do not support Secure Sockets Layer (SSL) over secure connections

To configure the Remote Manager, follow the instructions described in Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management.

The Connector Server also has the ability to run Action Scripts. See "Understanding the Identity Connector Framework" for information about the Identity Connector Server.

8.3.3 The Adapter Factory

As stated earlier, an adapter is a Java class created by an Oracle Identity Manager user through the Adapter Factory, which is accessed through the Design Console.

Adapters extend the internal logic and functionality of Oracle Identity Manager. In addition, they interact with any IT resource by connecting to that resource's API.

The Adapter Factory is a code-generation tool provided by Oracle Identity Manager that enables a user to create Java classes, known as adapters. Figure 8-1 shows the Adapter Factory Form in the Design Console.

Figure 8-1 Adapter Factory Form

Surrounding text describes Figure 8-1 .

8.3.4 Compiling Adapters

Oracle Identity Manager provides various options for compilation, including:

  • compile individual adapters one at a time

  • compile a set of adapters at once

  • compile all adapters that exist in the Oracle Identity Manager database with a single click

8.3.4.1 Automatic Compilation of Adapters

Adapters are compiled automatically when you import connector files by using the Deployment Manager. The compiled adapter class files are stored in the Oracle Identity Manager database, as opposed to the file system, from where they are loaded at run time. The following two APIs are available to compile adapters programmatically:

  • public void compileAdapter (String adapterName): This API compiles a single adapter and stores the compiled classfile in the database. It takes the name of the adapter as a parameter. If the adapter is not found or if there are any errors, the API throws an appropriate exception.

  • public void compileAll: This API compiles all adapters in a system. If it encounters any errors during compilation, it throws an exception of the type tcBulkException. This exception comprises all the individual errors that the API encounters during compilation.

You can modify the adapters manually if you make any changes.

Note:

You must set the path of the JDK directory in the XL.CompilerPath system property. Otherwise, an error is encountered during the adapter compilation stage when you import an XML file using the Deployment Manager.

Refer to the "System Properties in Oracle Identity Manager" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for information about setting values of system properties.

8.3.4.2 Compiling Adapters Manually

The Adapter Manager form is located in the Development Tools folder. You use it to compile multiple adapters simultaneously.

To manually compile multiple adapters, perform these steps:

  1. Open the Adapter Manager form.

    The Adapter Manager form is in the Development Tools folder. It is used to compile multiple adapters simultaneously, as shown in Figure 8-2.

    Figure 8-2 Adapter Manager Form

    Adapter Manager form
  2. To compile every adapter that resides within the Oracle Identity Manager database, select the Compile All option.

    To compile multiple adapters, select the adapters you want to compile. Then, select the Compile Selected option.

    To compile all adapters that do not have an OK status, select the Compile Previously Failed option.

  3. Click the Start button.

    Oracle Identity Manager will compile the adapters that match the criteria you specified in Step 2.

Tip:

Oracle Identity Manager lets you review the record of any adapter that appears within the Adapter Manager form to see detailed information about the adapter.

To view an adapter's record, select the desired adapter and either double-click its row header, or right-click the adapter, and select the Launch Adapter command from the menu that appears.

8.4 Defining Adapters

To define an adapter:

  1. Log in to Oracle Identity Manager Design Console.

  2. Open the Adapter Factory form. This form is in the Development Tools folder in the Design Console.

  3. In the Adapter Name field, enter the name of the adapter, for example, Create Solaris User.

    Note:

    Although the adapter name can contain special characters, Oracle recommends that you do not use them because there might be run-time errors.

  4. Double-click the Adapter Type lookup field.

    The Lookup window is displayed, displaying the five types of Oracle Identity Manager adapters. These are:

    • Process Task

    • Rule Generator

    • Pre-populate Rule Generator

    • Entity

    • Task Assignment

  5. To enable the adapter to automate a process task, select Process Task (T).

    To incorporate business rules into an Oracle Identity Manager or user-defined form field, select Rule Generator (R). For example, for the User ID field of a form, you can configure Oracle Identity Manager to concatenate the initial letter of the user's first name with the user's last name.

    You can attach a type of rule generator adapter to a user-created form field, so that it can:

    • Display the data, which is generated by the adapter, automatically or manually.

    • Use criteria that enable Oracle Identity Manager to determine which adapter is applied to the designated form field.

    To attach the adapter to an Oracle Identity Manager or user-defined form field, and have Oracle Identity Manager trigger the adapter on preinsert, preupdate, predelete, postinsert, postupdate, or postdelete, select Entity (E).

    To allow the adapter to automate the allocation of a process task to a user or group, select Task Assignment (A).

    Tip:

    If you create an entity adapter, then an error might be generated while compiling the adapter on computers with less file limits. To avoid this problem, change the file limits in the /etc/security/limits.conf file to the following:

    soft nofile 4096

    hard nofile 4096

    Then, restart Oracle Identity Manager.

  6. Select the type of adapter you want, for example, Process Task (T). Then, click OK.

    See Also:

    "Developing Process Forms" for more information about the Form Designer form

  7. In the Description field, type a description for the adapter, for example, This adapter is used to create a new user for the Solaris environment.

  8. From the toolbar, click Save.

    The adapter is now stored in the Oracle Identity Manager database.

8.5 Tabs of the Adapter Factory Form

The Adapter Factory form in the Design Console contains the following tabs:

8.5.1 Adapter Tasks

In the Adapter Tasks tab, you can create and manage the atomic function calls of an adapter. These function calls are known as adapter tasks.

The sequence of calls is vital because these calls in turn gets converted into Java statements. In other words, if you put an Else call before an If call, then the adapter is not compiled. In addition, you must understand the logical flow of java program while creating adapter. Analogically, this is like writing an algorithm instead of a program with Java syntax.

8.5.2 Execution Schedule

The Execution Schedule tab lets you specify when you want Oracle Identity Manager to trigger a rule generator or an entity adapter. You can schedule Oracle Identity Manager to run a rule generator (Adapter Type R) on preinsert and/or preupdate. You can also configure Oracle Identity Manager to execute an entity adapter (Adapter Type E) on preinsert, preupdate, predelete, postinsert, postupdate, or postdelete.

Caution:

Process task adapters and task assignment adapters, which are attached to process tasks, are triggered once the process task's status becomes Pending. Therefore, you do not specify when Oracle Identity Manager will trigger these types of adapters, Oracle Identity Manager disables the Execution Schedule tab for them.

Also, because Oracle Identity Manager always triggers pre-populate adapters on preinsert, Oracle Identity Manager disables the check boxes of this tab for pre-populate adapters.

8.5.3 Resources

From the Resources tab, you can:

  • Click the Java APIs subtab to see the Java APIs that are being used by the adapter.

  • Click the Other subtab to document a non-Java API file to the adapter, if necessary.

Note:

This Resources tab does not represent resource objects.

8.5.4 Variable List

For prepopulation adapters, the data is passed to adapter input variables and are processed by using adapter logic. The adapter returns output variable, which is then assigned to process form field.

From the Variable List tab, you can:

  • Create, modify, and delete adapter variables.

  • Set the data type and provide a description for each variable.

  • Map an adapter variable to a literal or an adapter reference. You can also postpone the mapping until it is attached to a process task or a form field.

You also can resolve the value of the adapter variable at run time, when it is attached to a process task and the process task is run. As a result, process-specific data is available to map to this variable.

8.5.5 Usage Lookup

For a process task or task assignment adapter, the Usage Lookup tab displays the process task to which the adapter is attached, as well as the process of which this process task is a member.

For a rule generator or entity adapter, this tab shows the Oracle Identity Manager form and associated data object to which the adapter is attached. In addition, it displays the execution schedule of the adapter, along with a sequence number that represents the order in which Oracle Identity Manager will trigger the adapter.

For a pre-populate adapter, this tab displays the user-defined form and form field to which the adapter is attached. Also, it shows the pre-populate rule that is associated with the adapter.

8.5.6 Responses

The Responses tab is used for defining meaningful responses to the process task. These responses depend on the execution result of the adapter. The various error messages returned by the external system can be mapped to these responses in a way that they make sense in the context of the process task. On attaching the adapter to a process task, the status bucket, which consists of Pending, Completed, and Rejected, of the process task (and subsequently the Object status) can be set, based on the adapter response code.

Tip:

Oracle Identity Manager enables the Responses tab only for process task adapters. If an adapter is a task assignment, rule generator, pre-populate, or entity adapter, Oracle Identity Manager disables this tab.

8.6 Disabling and Re-enabling Adapters

To disable an adapter so that it cannot be used with a process task or form field, select the Disable Adapter option, and save the adapter.

To re-enable it, clear the Disable Adapter option, and save the adapter.

8.7 About Adapter Variables

For a newly-created adapter to work, you can map data to the parameters of the adapter tasks. For this reason, you create placeholders, also known as adapter variables, to map the data at run time.

Note:

An adapter variable can be reused for all adapter tasks.

Once an adapter variable is not needed for the adapter to run, you can remove it from the adapter. After you have deleted the adapter variable, ensure to recompile the adapter.

8.7.1 Creating an Adapter Variable

To create an adapter variable:

  1. Select the adapter to which you wish to add an adapter variable, for example, the Create Solaris User adapter.

  2. Select the Variable List tab.

  3. Click Add.

    The Add a Variable window is displayed.

  4. When you do not want Oracle Identity Manager to be able to change the adapter variable value after it is activated, select Final.

  5. In the Variable Name field, enter the name of the adapter variable, for example, SolarisUserID.

    Caution:

    The adapter variable name cannot contain spaces.

  6. From the Type menu, select the classification type of the adapter variable, such as String. The available items are:

    • Object

    • IT Resource

    • String

    • Boolean

    • Character

    • Byte

    • Date

    • Integer

    • Float

    • Long

    • Short

    • Double

  7. Within the Description text area, you can enter explanatory information about the adapter variable.

  8. From the Map To menu, you can map your adapter variable to one of the items listed in Table 8-1.

    Table 8-1 Items on the Map To Menu

    Name Description

    Literal

    This adapter variable is mapped to a constant (or literal).

    Resolve at Run time

    This adapter variable's mapping occurs later, at run time. Selecting this option increases the reusability of the adapter.

    Adapter References

    This adapter variable gives access to an Oracle Identity Manager database reference or an Oracle Identity Manager data object reference.

    System Date

    When this adapter variable is triggered by Oracle Identity Manager, it is mapped to the current date and time of the Server.

    Note: This option appears only when you select the Date type.


    Note:

    When you select the object type, a Qualifier menu is displayed within the Add a Variable window. From this menu, you can select either of the following:

    • Database Reference. If you select this item, the adapter variable is mapped to the reference of the database that the Oracle Identity Manager is currently running against.

    • Data Object Reference. If you select this item, the adapter variable is mapped to an Oracle Identity Manager data object.

    Note:

    If you select the IT Resource type, a Resource Type menu is displayed within the Add a Variable window. From this menu, you can select one of the IT resource types that have been created by using the IT Resource Type Definition form. By doing so, you can map the adapter variable to a parameter of this IT resource type.

  9. On the toolbar in the Add a Variable window, click Save. The information for your adapter variable is stored in the Oracle Identity Manager database.

    Close the Add a Variable window to activate the main screen. The name, classification type, mapping selection, and description of the adapter variable you created appear in the child table of the Variable List tab.

This adapter variable now belongs to the adapter in the Adapter Factory form. It is saved to the Oracle Identity Manager database, and the adapter variable is ready to use.

8.7.2 Modifying an Adapter Variable

To modify an adapter variable:

  1. Select the adapter that contains the adapter variable you want to edit, for example, the Create Solaris User adapter.

  2. Click the Variable List tab and double-click the row header of the adapter variable you want to modify. The Edit a Variable window is displayed, showing information about the adapter variable.

  3. Make the necessary edits, for example, changing the adapter variable's data type from String to Character.

  4. On the Edit a Variable toolbar, click Save. The modified information about the adapter variable is stored in the Oracle Identity Manager database.

  5. Close the Edit a Variable window to activate the main screen. The adapter variable you modified appears within the child table of the Adapter Factory form.

    Note:

    Ensure that you check your data mappings and recompile the adapter, especially if you change the adapter variable's data type.

8.7.3 Deleting an Adapter Variable

When an adapter variable is no longer necessary for the adapter to run, you can remove it from the adapter. To do this:

  1. Select the adapter that contains an adapter variable you want to remove, for example, the Create Solaris User adapter.

  2. Select the Variable List tab.

  3. From the list of this tab, select the adapter variable you want to delete.

  4. Click Delete.

  5. Recompile the adapter after deleting any variable.

The adapter variable disappears from the child table. The adapter variable has been deleted.

8.8 Creating Adapter Tasks

After you construct the adapter and create its variables, you can create the atomic function calls of an adapter. These function calls are known as adapter tasks.

This section explains adapter tasks and how to create tasks:

8.8.1 Types of Adapter Tasks

Oracle Identity Manager allows you to create the following adapter tasks:

  • A Java task, which allows an adapter to communicate with an external source by invoking Java API.

  • A remote task, which enables an adapter to call a method on an API. This API resides on a computer that is external to Oracle Identity Manager.

    This type of task is used mostly with integrations of third-party APIs that are not network-enabled. A remote manager executes the remote API method, which is located on a remote computer. In addition, if the third-party API does not use SSL, you can use the remote manager to invoke third-party APIs over SSL-protected communication. Remote tasks can also be used with integrations of third-party APIs, which are network-enabled, but are not located on the Oracle Identity Manager server for scalability purposes. The remote API method is still executed by a remote manager. However, because the third-party API is network-enabled, the remote manager does not have to reside on the target system.

  • A stored procedure task, which allows Oracle Identity Manager to map to and execute SQL programs located within a particular database schema. These programs are known as stored procedures. They contain information, such as SQL statements, which are pre-compiled for greater efficiency.

    By incorporating a stored procedure task into an adapter, and attaching this adapter to a process task, Oracle Identity Manager can incorporate stored procedures on any Oracle Database or Microsoft SQL Server database that is accessible on its network. This includes retrieving primitive values from stored procedures.

  • A utility task, which enables you to populate an adapter with methods and APIs that come packaged with Oracle Identity Manager. In addition, this type of task provides you with access to the Java Standard Library APIs.

  • An Oracle Identity Manager API task, which enables access to Oracle Identity Manager published APIs from adapter tasks. This allows for enhanced portability of adapter code.

  • A set variable task, which allows you to set a variable within an adapter.

  • An error handler task, which lets you display any errors associated with an adapter that occur at run time. In addition, you can see the reasons for the errors, along with possible solutions.

  • A logic task, which lets you build a conditional statement within an adapter.

You can create the following types of logic tasks:

  • FOR loops

  • WHILE loops

  • IF statements

  • ELSE statements

  • ELSE IF statements

  • BREAK statements

  • RETURN statements

  • CONTINUE statements

  • SET VARIABLE statements

  • Handle Error statements

See Also:

Section 8.8.9, "Creating a Logic Task" for more information about the types of logic tasks you can build

For classification purposes, Oracle Identity Manager represents each type of adapter task by an icon. The icon, which precedes the task name, is a visual indicator of the type of task it is. For example, "J" represents a Java task, and "LT" represents a logic task.

To see a list of these icons, select the Adapter Tasks tab, and click Legend. The Legend window appears, displaying the following list of icons:

  • Functional Task

    • Java

    • Remote

    • Stored Procedure

  • Utility Task

    • Utility

    • Oracle Identity Manager API

  • Logical Task

8.8.2 Creating a Java Task

Oracle Identity Manager can handshake with an external source through a Java API. To make this happen, you must add a task to an adapter which, when triggered by Oracle Identity Manager, initiates communications with the external source. This type of task is called a Java task.

To create a Java task:

  1. Select the adapter to which you want to add a Java task, for example, the Update Solaris Password adapter.

  2. Select the Adapter Tasks tab.

  3. Click Add.

    After the Adapter Task Selection window is displayed, select the Functional Task option.

  4. From the display area to the right of this option, select the Java item, and click Continue.

    The Object Instance Selection window is displayed.

    Table 8-2 explains the options in the Object Instance Selection window.

    Table 8-2 Options in the Object Instance Selection Window

    Option Description

    New Object Instance

    When you click this option, you are creating a new Java object instance.

    Persistent Instance

    You can call the method on a persistent object by clicking this option, clicking the adjacent combo box, and selecting an object instance from the drop-down menu.

    Task Return Value Instance

    You can call this method on an object returned by an adapter task defined earlier by clicking this option, clicking the combo box, and selecting an adapter task from the drop down list.


    Note:

    When the Persistent Instance option is grayed out, it indicates that you have not defined any persistent objects for your adapter. Similarly, if the Task Return Value Instance option is grayed out, none of the tasks have Java Object return values associated with them.

  5. Click an option—for example, New Object Instance—and click Continue. The Add an Adapter Factory Task window is displayed.

    Table 8-3 lists and describes the various regions of the Add an Adapter Factory Task window:

    Table 8-3 Regions of the Add an Adapter Factory Task Window

    Name Description

    Task Name

    This field displays the name of the Java task.

    Persistent Instance

    If this Java object is to be used again, the check box is selected, and the name of the task instance is entered in the adjacent field.

    API Source

    This combo box contains a list of all JAR and class files to which you have access.

    Application API

    This combo box contains a list of all class files to which you have access, and which belong to the JAR file that has been selected from the API Source list.

    Constructors

    This text area displays all the constructors, which are available for the Java object.

    Methods

    This text area shows a list of all the methods, which are available for the Java object.

    Application Method Parameters

    This area contains the parameters of the selected constructor and method. These parameters are mapped to the adapter variables and Oracle Identity Manager components.


  6. In the Task Name field, enter the name of the task you are creating, for example, Update Password.

  7. (Optional.) To make your Java object reusable, select Persistent Instance, type the name of the instance of this task in the text field located to the right of the check box.

    Caution:

    Ensure that name of the instance contains no spaces.

    Note:

    To reference a session with the target resource multiple times during the life of the adapter, and not just once, select Persistent Instance.

    Tip:

    By setting the Java object to be persistent, the next time you create a Java object, it appears in the Persistent Instance list of the Object Instance Selection window. In addition, you do not have to map the constructor to all adapter tasks of the same Java object.

  8. Select the API Source. The JAR files appear, which Oracle Identity Manager references from the JavaTasks subdirectory of the OIM_HOME/ directory path—for example, C:\oracle\Xellerate\JavaTasks.

    See Also:

    Section 8.3.1, "Configuring the Adapter Environment" for instructions on how to enable Oracle Identity Manager to use third-party JAR files with a Java task

  9. Select the Application API. The class files, which belong to the JAR file you selected in the API Source, appear.

  10. From the Constructors area, select the method to be used to initialize the Java class you selected.

  11. From the Methods area, select the method that will be used with your Java task.

  12. From the toolbar, click Save.

    The information pertaining to the Java task is stored in the Oracle Identity Manager database. You can now access the parameters of your Java task's constructors and methods. These parameters appear in the Application Method Parameters region of the Add an Adapter Factory Task window.

  13. To display the Java class constructors and methods for which you must set mappings, click the plus icons displayed to the left of the Constructor and Method icons.

  14. Select the parameter of the constructor or method for which you must set a mapping.

  15. In the Description text area, you can enter a description for this mapping.

  16. Click the Map to combo box, and select an item that you can map to the parameter of the constructor or method, for example, Adapter Variables.

  17. Set the appropriate mappings.

    See Also:

    "Adapter Mapping Information" for more information about which mappings to set

  18. Click Set.

    The parameter of the selected constructor or method now appears in blue. This signifies that it has been mapped.

    Tip:

    To remove a parameter mapping, right-click the appropriate parameter, and select Un-Map Parameter from the popup menu that appears.

  19. Repeat steps 15 through 18 for all parameters of the constructors and methods that appear in the Application Method Parameters region.

  20. On the Add an Adapter Factory Task window toolbar, click Save. The information pertaining to the Java task is stored in the Oracle Identity Manager database.

  21. On the toolbar, click Close. The Add an Adapter Factory Task window disappears, and the main screen is active once again. The Java task that you created—for example, Update Password—appears within the Adapter Factory form.

  22. (Optional.) To create additional Java tasks for the adapter, repeat steps 3-21.

    Tip:

    You can create different types of adapter tasks, and add them to the adapter.

    If the adapter is logically complete, and all variables on the adapter tasks are mapped, you can compile it to use with a process task or form field.

  23. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and found no errors. You can now attach the adapter to a process task or form field.

  24. (Optional.) To see the code that Oracle Identity Manager generates, from the toolbar, click Notes.

    The Notes window is displayed, containing the code that Oracle Identity Manager generated.

    Note:

    If, after clicking Build, CODE GEN ERROR appears in the Compile Status field, it means that Oracle Identity Manager encountered one of two types of errors while validating and compiling the adapter:

    • Validation Error

      While Oracle Identity Manager is checking the adapter to verify that it is valid, an error is found. This error can result from a parameter of an adapter task not being mapped, a parameter being mapped improperly, or an adapter task being placed out of order.

      Because Oracle Identity Manager generates code for an adapter only after it is validated, if Oracle Identity Manager encounters a validation error, it does not create any code.

    • Java Compilation Error

      Oracle Identity Manager has verified that the adapter is valid. However, while Oracle Identity Manager is compiling the adapter, an error is found. This error can result from assigning an incorrect data type to an adapter task parameter.

      Because Oracle Identity Manager has validated the adapter, it generates code. However, Oracle Identity Manager stops building code at the point of the compilation where it encounters the error.

    Tip:

    Once you create a Java task, and add it to an adapter, you can see the following information by accessing the Resources tab of the Adapter Factory form:

    • The JAR and class files used to create the Java task.

    • The name, which represents the directory path that contains these JAR and class files.

8.8.3 Creating a Remote Task

A remote task enables an adapter to invoke an API method by using the Remote Manager. This API resides on a computer that is external to Oracle Identity Manager. This section explains how to create a remote task.

Note:

Before creating a remote task, ensure that you define an adapter variable with a classification type of IT Resource, as well as select one of the IT resources that have been created by using the IT Resource Type Definition form.

  1. Select the adapter to which you wish to add a remote task.

  2. Click the Adapter Tasks tab.

  3. Click Add.

    The Adapter Task Selection window is displayed.

  4. Select the Functional Task option.

  5. From the display area to the right of the button, select the Remote item to create a remote task. Then, click Continue.

    The Object Instance Selection window is displayed.

    Note:

    To learn more about the choices of this window, refer to Section 8.8.2, "Creating a Java Task".

  6. Click Continue.

    The Add an Adapter Factory Task window is displayed.

  7. In the Task Name field, enter the name of the remote task you are creating.

  8. (Optional.) If you want your remote task to be reusable, select the Persistent Instance option. Then, type the name of the instance of this task in the text field, located to the right of the check box.

    Caution:

    Ensure that the name of the instance contains no spaces.

    See Also:


    Section 8.8.2, "Creating a Java Task" for more information about the regions of the Add an Adapter Factory Task window

    Section 8.3.1, "Configuring the Adapter Environment" for information about how to enable Oracle Identity Manager to use third-party JAR files with a Java task
  9. From the Add an Adapter Factory Task window, select a JAR file, class file, constructor, and method. Then, set the mappings for the parameters of the constructor and method.

    Note:

    One of the input parameters will have a classification type of IT Resource. You must associate this parameter with an adapter variable of type IT Resource.

    See Also:

    "Adapter Mapping Information" for more information about which mappings to select

  10. From the Add an Adapter Factory Task window toolbar, click Save.

    The information pertaining to the remote task is stored in the Oracle Identity Manager database.

  11. From this window toolbar, click Close.

    The Add an Adapter Factory Task window disappears, and the main screen is active once again. The remote task that you created appears within the Adapter Factory form.

  12. (Optional.) To create additional remote tasks for the adapter, repeat Steps 3 through 11.

    You are now ready to compile the adapter, so it can be used with a process task or form field.

  13. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field, so Oracle Identity Manager can communicate with the external API.

8.8.4 Creating a Stored Procedure Task

Through Oracle Identity Manager, you can map to and execute SQL programs that are located within a particular database schema. These SQL programs are known as stored procedures. Stored procedures contain information, such as SQL statements, which are precompiled for greater efficiency.

For this to occur, you must add a stored procedure task to an adapter. When triggered by Oracle Identity Manager, this task incorporates stored procedures on any Oracle Database or Microsoft SQL Server database that is accessible on its network. This includes retrieving primitive values from stored procedures.

Take these steps to create a stored procedure task:

Note:

The parameter values and server type for the database schema are set within the IT Resources form.

The server type of the schema must be set to Database. Otherwise, Oracle Identity Manager cannot reference the database schema during the creation of a stored procedure task, the execution of a stored procedure task, or both.

In addition, Oracle Identity Manager uses values, which are represented by parameters—for example, Database Name or URL—to connect to the schema. As a result, the stored procedures contained within the schema, can be executed.

  1. For Oracle Identity Manager Installations that use Oracle Database, copy the ojdbc14.jar file from the OIM_HOME/ext/ directory to the OIM_DC_HOME/xlclient/ext directory.

    For Oracle Identity Manager Installations that use Microsoft SQL Server, you must obtain the following files from Microsoft and copy them to the OIM_DC_HOME/xlclient/ext directory:

    • msbase.jar

    • mssqlserver.jar

    • msutil.jar

  2. Select the adapter to which you wish to add a stored procedure task, for example, the Update User ID adapter.

  3. Click the Adapter Tasks tab.

  4. Click Add.

    The Adapter Task Selection window is displayed.

  5. Select the Functional Task option.

  6. From the display area to the right of the option, select Stored Procedure, and click Continue. The Add an Adapter Factory Task window is displayed.

    The following table lists and describes the regions of the Add an Adapter Factory Task window.

    Table 8-4 Regions of the Add an Adapter Factory Task Window

    Name Description

    Task Name

    Displays the name of the stored procedure task.

    Description

    Displays explanatory information about the stored procedure task.

    Database

    Lists the databases defined in the IT Resources form.

    Important: Only those IT resources with a server type of Database appear in the Database list.

    Schema

    Lists the schemas, which are associated with the database that appears in the Database list.

    Procedure

    Lists the stored procedures, which reside within the database schema that is displayed in the Schema list.

    Connection Status

    Displays the status of the connection between Oracle Identity Manager and the database that contains the target stored procedure.

    When Oracle Identity Manager can connect to the database, Connection Established is displayed in the Connection Status region.

    Note: If Oracle Identity Manager cannot connect, Connection Failed appears in the display area. In addition, the Notes button of the Add an Adapter Factory Task window is enabled. Clicking this button shows you why a connection could not be established, for example:

    Exception Type:

    java.lang.ClassNotFoundExceptionMessage:

    java.lang.ClassNotFoundException:

    oracle.jdbc.driver.OracleDriver

    In this example, Oracle Identity Manager could not connect to the designated database because it could not find a particular Java class.

    Parameters

    Contains parameters that can be mapped to the stored procedure. These parameters appear after you select a database, schema, and stored procedure and save this information to the Oracle Identity Manager database.


  7. In the Task Name field, enter the name of the stored procedure task you are creating (for example, Update ID).

  8. In the Description text area, you can enter a description for this stored procedure task.

  9. Click the Database list. The databases, which are defined in the IT Resources form, appear.

    Note:

    If Oracle Identity Manager cannot connect to the database you selected, Connection Failed appears in the display area. In addition, the Notes button of the Add an Adapter Factory Task window is enabled. Clicking this button shows you why a connection could not be established.

    Tip:

    Schemas and stored procedures appear only after you select a database to which Oracle Identity Manager can connect. Based on this selection, related schemas and stored procedures appear in the corresponding combo boxes.

  10. Click the Schema list. The schemas appear, which are associated with the database you selected.

  11. Click the Procedure list. The stored procedures, which reside within the database schema that you selected from the Schema combo box, appear.

  12. From the Add an Adapter Factory Task window's toolbar, click Save. The information pertaining to the stored procedure task is saved into the Oracle Identity Manager database.

    You can now set the mappings for the parameter(s) of the stored procedure. These parameters appear in the Parameters region of the Add an Adapter Factory Task window.

    Note:

    Oracle Identity Manager automatically maps the database and schema of the selected stored procedure. However, Oracle Identity Manager enables you to override these mappings.

    See Also:

    "Adapter Mapping Information" for more information about which mappings to select

  13. From the Add an Adapter Factory Task window's toolbar, click Save. The mappings that you have set for the parameter(s) of the stored procedure task are stored in the Oracle Identity Manager database.

  14. From this window's toolbar, click Close.

    The Add an Adapter Factory Task window disappears, and the main screen is active once again. The stored procedure task you created (for example, Update ID) appears within the Adapter Factory form.

  15. (Optional.) Repeat steps 3 through 13 to create additional stored procedure tasks for the adapter.

  16. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field, so Oracle Identity Manager can map to and execute the stored procedure you selected.

8.8.5 Creating a Utility Task

The Adapter Factory is shipped with a library of utility classes and methods, which increase the efficiency of developing adapters.

These utility classes and methods are contained within the xlUtils.jar, xlIntegration.jar, and rt.jar files. A Java task you create by using a class or method from one of these JAR files is called a utility task.

See Also:

Oracle Fusion Middleware Java API Reference for Oracle Identity Manager for more information about the class files that contains the xlUtils.jar, xlAPI.jar, xlIntegration.jar, and rt.jar files

  1. Select the adapter to which you wish to add a utility task, for example, the Update Solaris User Group adapter.

  2. Click the Adapter Tasks tab.

  3. Click Add.

    The Adapter Task Selection window is displayed.

  4. Select the Utility Task option.

  5. From the display area to the right of the option, select Utility, and click Continue. The Object Instance Selection window is displayed.

    See Also:

    "Creating a Java Task" to learn more about the choices of this window

  6. Click Continue. The Add an Adapter Factory Task window is displayed

  7. In the Task Name field, enter the name of the utility task you are creating, for example, Update User Group.

  8. (Optional.) If you want your utility task to be reusable, select Persistent Instance, type the name of the instance of this task in the text field to the right of the check box.

    Caution:

    Ensure that name of the instance does not contain any spaces.

    See Also:


    "Creating a Java Task" for more information about the regions of the Add an Adapter Factory Task window

    "Configuring the Adapter Environment"
  9. Click the Application API list. The class files appear, which belong to the xlUtils.jar, xlIntegration.jar, and rt.jar files.

    Note:

    The xlUtils.jar, xlIntegration.jar, and rt.jar files contain all of the class files that you can use for a utility task. Therefore, you do not have to access the API Source list.

  10. From the Add an Adapter Factory Task window, select a constructor and method. Then, set the mappings for the parameters of the constructor and method.

  11. From the Add an Adapter Factory Task window's toolbar, click Save. The information pertaining to the utility task is stored in the Oracle Identity Manager database.

  12. From this window's toolbar, click Close.

    The Add an Adapter Factory Task window disappears, and the main screen is active once again. The utility task that you created (for example, Update User Group) appears within the Adapter Factory form.

  13. (Optional.) Repeat steps 3 through 12 to create additional utility tasks for the adapter.

    You are now ready to compile the adapter, so it can be used with a process task or form field.

  14. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field.

8.8.6 To Create an Oracle Identity Manager API Task

For greater portability of the adapter code, an Oracle Identity Manager API task enables Adapter tasks to call APIs published by Oracle Identity Manager. This is better than accessing Oracle Identity Manager data directly through hardcoded SQL statements.

The Adapter Factory is shipped with a library of utility classes and methods, which increase the efficiency of developing adapters that contain Oracle Identity Manager API tasks. These utility classes and methods are contained within the xlAPI.jar file.

See Also:

Oracle Fusion Middleware Java API Reference for Oracle Identity Manager for more information about the class files that contain the xlUtils.jar, xlAPI.jar, xlIntegration.jar, and rt.jar files

To create this type of adapter task:

  1. Select the adapter to which you wish to add an Oracle Identity Manager API task, for example, the Get User's Password adapter.

  2. Click the Adapter Tasks tab.

  3. Click Add.

    The Adapter Task Selection window is displayed.

  4. Select the Utility Task option.

  5. From the display area to the right of the option, select Xellerate API, and click Continue. The Object Instance Selection window is displayed.

    See Also:

    "Creating a Java Task" to learn more about this window

  6. Click Continue. The Add an Adapter Factory Task window is displayed.

  7. In the Task Name field, enter the name of the Oracle Identity Manager API task you are creating, for example, Retrieve Password).

  8. (Optional.) If you want your Oracle Identity Manager API task to be reusable, select Persistent Instance. Then, type the name of the instance of this task in the text field to the right of the check box.

    Tip:

    Ensure that name of the instance contains no spaces.

    See Also:


    "Creating a Java Task" for more information about the regions of the Add an Adapter Factory Task window

    "Configuring the Adapter Environment" to learn how to enable Oracle Identity Manager to use third-party JAR files with a Java task
  9. Click the Application API list. The class files appear, which belong to the xlAPI.jar file.

    Note:

    The xlAPI.jar file contains all of the class files that you can use for an Oracle Identity Manager API task. Therefore, you do not have to access the API Source list.

  10. From the Add an Adapter Factory Task window, select a class file, constructor, and method. Then, set the mappings for the parameters of the constructor and method.

    See Also:

    "Adapter Mapping Information" for more information about which mappings to select

  11. From the Add an Adapter Factory Task window's toolbar, click Save. The information pertaining to the Oracle Identity Manager API task is stored in the Oracle Identity Manager database.

  12. Close the Add an Adapter Factory window to activate the main screen. The Oracle Identity Manager API task that you created—for example, Retrieve Password—appears within the Adapter Factory form.

  13. (Optional.) To create additional Oracle Identity Manager API tasks for the adapter, repeat steps 3 through 12.

    You are now ready to compile the adapter, so it can be used with a process task or form field.

  14. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field, so Oracle Identity Manager can communicate with a third-party application.

8.8.7 Reassigning the Value of an Adapter Variable

Sometimes, for an adapter to accomplish its required objective, you must reassign the value of one adapter variable to another adapter variable, a different type of adapter task, or a constant (or literal). The task that enables you to reallocate an adapter variable value is known as a set variable task.

See Also:

"About Adapter Variables" for information about adapter variables

For example, you can create a set variable task to set the adapter variable return value to equal the output of an adapter task (UserName) if the User ID length is fewer than 11 characters.

To create a set variable task:

  1. Select the adapter to which you wish to add a set variable task (for example, the Check the Solaris User ID adapter).

  2. Click the Adapter Tasks tab.

  3. Click Add. The Adapter Task Selection window is displayed.

  4. Select the Logic Task option.

  5. From the display area, select SET VARIABLE, and click Continue. The Add Set Variable Task Parameters window is displayed.

  6. From the Variable Name list, select the adapter variable that has a value you want to reassign—for example, Adapter return value.

  7. From the Operand Type list, select the type of operand that will provide the value for the variable.

    Tip:

    You can reassign an adapter variable's value to another adapter variable, a different type of adapter task, or a literal.

    Use Table 8-5 to understand the various types of operands.

    Table 8-5 Types of Operands

    Operand Name Description

    Variable

    If you select this operand type, adapter variables appear in the Operand Qualifier list. From this list, select the specific adapter variable that will provide the reassigned value.

    Note: The only adapter variables that will appear in the Operand Qualifier combo box will be those variables that have the same data type as the adapter variable that is displayed within the Variable Name combo box.

    Adapter Task

    By selecting this operand type, adapter tasks are displayed in the Operand Qualifier combo box. From this combo box, select the particular adapter task that will provide the reallocated value.

    Note: The only adapter tasks that will appear in the Operand Qualifier combo box will be those tasks that have the same data type as the adapter variable that is displayed within the Variable Name combo box.

    Literal

    When you select this operand type, types of literals appear in the Operand Qualifier combo box. From this combo box, select the type of literal that will provide the reallocated value. Then, type the specific literal into the field that appears underneath the combo box.


The following task sets the adapter variable's return value to be equal to the UserName adapter variable.

  1. On the toolbar in the Add Set Variable Task Parameters window, click Save. The set variable task you created is stored in the Oracle Identity Manager database.

  2. On the Add Set Variable Task Parameters window toolbar, click Close. The Add Set Variable Task Parameters window disappears, and the main screen is active once again. The set variable task that you created, for example, Set Adapter return value = UserName, appears in the Adapter Factory form.

  3. (Optional.) Repeat Steps 3-9 to create additional set variable tasks for the adapter.

    You are now ready to compile the adapter, so it can be used with a process task or form field.

  4. To compile the adapter, click Build. The text in the Compile Status field changes from Recompile to OK. Oracle Identity Manager compiled the adapter and found no errors. You can attach the adapter to a process task or form field.

8.8.8 Adding an Error Handler Task

To add an error handler task:

  1. An adapter task can return errors. When this occurs, the process task or form field to which the adapter is attached gets rejected.

    You can attach your own customizable error messages, which will be displayed to the user. These messages are known as error handler tasks.

    For example, you can attach an error handler task to an adapter that will display an error message when the length of a User ID is greater than 10 characters.

  2. Select the adapter to which you wish to add an error handler task (for example, the Check the Solaris User ID adapter).

  3. Click the Adapter Tasks tab.

  4. Click Add.

    The Adapter Task Selection window is displayed.

  5. Select the Logic Task option.

  6. From the display area, select Handle Error, and click Continue. The Add an Adapter Factory Task window is displayed.

  7. Double-click this window's lookup field. The Lookup window is displayed, displaying the error handler tasks you can add to the adapter.

    Note:

    The only error handler tasks that appear in this Lookup window are the ones that begin with ADAPTER—such as ADAPTER.USERIDLENERR).

    If you do not see the error handler task that you want to incorporate into the adapter, you can create one by accessing the Error Message Definition form. Refer to "Defining Error Messages".

  8. Select the error handler task you want, for example, ADAPTER.USERIDLENERR.

  9. Click OK. The Lookup window disappears, and the Add an Adapter Factory Task window is active. In addition, the error handler task you selected appears in the field of this window.

  10. From the Add an Adapter Factory Task window toolbar, click Save. The error handler task you incorporated into the adapter is stored in the Oracle Identity Manager database.

  11. From this window's toolbar, click Close.

    The Add an Adapter Factory Task window disappears, and the main screen is active once again. The error handler task you added, for example, Handle Error.ADAPTER.USERIDLENERR, appears within the child table of the Adapter Factory form.

  12. (Optional.) Repeat Steps 3-10 to create additional error handler tasks for the adapter.

    If the adapter is logically complete and all variables on the adapter tasks are mapped, you can compile it to use with a process task or form field.

  13. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field.

See Also:

"Defining Error Messages" for information about creating error messages by using the Error Message Definition form

8.8.9 Creating a Logic Task

While defining the adapter, you can add conditional statements to the adapter to control its logic flow. These conditional statements are known as logic tasks. For example, you can create a logic task that will trigger an action if the length of a User ID is greater than 10 characters.

To create a logic task:

  1. Select the adapter to which you wish to add a logic task (for example, the Check the Solaris User ID adapter).

  2. Click the Adapter Tasks tab.

  3. Click Add. The Adapter Task Selection window is displayed.

  4. Select the Logic Task option.

  5. From the display area, select the type of logic task you want to create. Then, click Continue.

    Note:

    If you select a conditional expression, and click Continue, one of the following actions occurs:

    Oracle Identity Manager adds the conditional statement to the adapter directly; or

    A secondary window is displayed, containing fields about the conditional expression that you can configure.

    To see what happens when you select a particular conditional statement, refer to Table 8-6.

    Table 8-6 Actions Resulting from Particular Conditional Statements

    Conditional Statement Statement Is Added to the Adapter Directly Secondary Window Appears

    FOR

     

    X

    WHILE

     

    X

    IF

     

    X

    ELSE

    X

     

    ELSE IF

     

    X

    BREAK

    X

     

    RETURN

    X

     

    CONTINUE

    X

     

    Table 8-7 explains the various regions of the Add Adapter Factory Logic Task Parameters window:

    Table 8-7 Regions of the Add Adapter Factory Logic Task Window

    Name Description

    Operand Type

    These combo boxes contain types of operands, such as adapter tasks and adapter variables.

    Comparator Combo Box

    From this combo box, you can set the relationship between two operands (for example, <, =, >).

    Operand Qualifier

    These combo boxes contain the qualifiers for the operands.

    Literal Text Box

    When you select the Literal operand type, enter the specific literal into this field.


    Note:

    By selecting the FOR conditional statement, an Add Adapter Factory Logic Task Parameters window is displayed. However, it contains different text and combo boxes.

    For the FOR conditional expression, use Table 8-8 to understand the various regions of this Add Adapter Factory Logic Task Parameters window.

    Table 8-8 Add Adapter Factory Logic Task Parameters for FOR Conditional Statement

    Name Description

    Operand Type

    These combo boxes contain types of operands, such as adapter tasks and adapter variables.

    Comparator Combo Box

    From this combo box, you can set the relationship between two operands (for example, <, =, >).

    Operand Qualifier

    These combo boxes contain the qualifiers for the operands.

    Increment Combo Box

    Within this area, you can set whether the initial value will increase or decrease, and by how much.


    Note:

    If you select the ELSE, BREAK, RETURN, or CONTINUE conditional expressions, proceed to Step 8.

  6. Set the parameters for your conditional expression.

    This logic task will check to see if the length of the User ID is greater than 10 characters.

  7. From the Add Adapter Factory Logic Task Parameters window toolbar, click Save.

    The logic task you created is stored in the Oracle Identity Manager database.

  8. From this window toolbar, click Close. The Add Adapter Factory Logic Task Parameters window disappears, and the main screen is active once again. The logic task that you created—for example, If (Check ID Length > 10)—appears within the Adapter Factory form.

  9. (Optional.) Repeat Steps 3-8 to create additional logic tasks for the adapter.

    Caution:

    All adapter tasks that can be executed for a condition of a logic task should be nested properly under that logic task.

    See Also:

    Section 8.10, "Changing the Order and Nesting of Tasks" for more information about nesting tasks

    You are now ready to compile the adapter, so it can be used with a process task or form field.

  10. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field.

8.9 Modifying Adapter Tasks

The following procedure will show you how to edit an adapter task, in case you must make changes to it. To modify an adapter task

  1. Select the adapter that contains the adapter task you wish to edit (for example, the Update Solaris User Group adapter).

  2. Click the Adapter Tasks tab.

  3. Double-click the adapter task that you want to modify.

    The Edit Adapter Factory Task Parameters window is displayed, displaying information that relates to the adapter task you selected. Within this window, make the necessary modifications.

  4. On the Edit Adapter Factory Task Parameters window toolbar, click Save.

    The information you modified is stored in the Oracle Identity Manager database.

  5. On the toolbar, click Close.

    The Edit Adapter Factory Task Parameters window disappears. The main screen is active again. The modified task appears within the child table of the Adapter Factory form. You must re-compile the adapter, so it can be used with a process task or form field.

  6. To recompile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field.

Caution:

You cannot modify the API call inside a Java, Xellerate API, or Utility task. The adapter task has to be deleted and re-created. In addition, if CODE GEN ERROR appears in the Compile Status field, Oracle Identity Manager encountered errors while compiling the adapter. Rectify the errors, if necessary re-do the adapter task modifications, and compile the adapter again.

8.10 Changing the Order and Nesting of Tasks

If you add multiple tasks to an adapter, you can either change the order in which the tasks are executed, or place one task inside of another task for the adapter to work.

The following procedure will show you how to change the order and nesting of tasks.

Caution:

You should not change the order and nesting of adapter tasks unless you understand the mapping dependencies of the adapter tasks.

To change the order and nesting of tasks:

  1. Select the adapter that contains tasks of which you want to change the order and/or nest (for example, the Check the Solaris User ID adapter).

  2. Click the Adapter Tasks tab.

    The tasks appear, which belong to the current adapter.

    In this example, the following changes must occur:

    • The error handler task must be nested inside of the IF (Check ID Length > 10) logic task.

    • The set variable task has to be nested inside of the ELSE logic task.

    • The IF logic task precedes the ELSE logic task.

    Therefore, you must first reorganize the logic tasks. Then, you must nest the error handler task and set variable task inside of the IF and ELSE logic tasks, respectively. To reorganize tasks:

  3. Select the task that must run before another task, and click the Up arrow button. The selected task will switch places with the task that precedes it.

    or

    Select the task that must be executed after another task, and click the Down arrow button. The highlighted task is displayed below the task that previously followed it.

    To nest tasks/remove task nestings:

  4. Select the task that must be placed inside of another task, and click the Right arrow button. The selected task will be nested inside of the task that appears above it.

    or

    Select the task that no longer be nested inside of another task, and click the Left arrow button. The highlighted task will not be nested inside of the task that is displayed above it.

  5. On the toolbar, click Save.

    The order and nesting of the adapter's tasks is stored in the Oracle Identity Manager database. If the adapter is logically complete and all variables on the adapter tasks are mapped, you can compile it to use with a process task or form field.

  6. To compile the adapter, click Build.

    The text in the Compile Status field changes from Recompile to OK. This indicates that Oracle Identity Manager compiled the adapter and did not find any errors. You can now attach the adapter to a process task or form field.

    Caution:

    If you see CODE GEN ERROR in the Compile Status field, Oracle Identity Manager found errors while compiling the adapter. Rectify the errors, if necessary re-do the adapter task modifications, and compile the adapter again.

8.11 Deleting Adapter Tasks

When an adapter task is no longer necessary for the adapter to run, you must remove it from the adapter. To delete an adapter task:

  1. Select the adapter that contains the task you wish to remove (for example, the Update Solaris User Group adapter).

  2. Click the Adapter Tasks tab.

  3. Select the task that you want to remove (for example, the CONTINUE logic task).

  4. Click Delete.

    The selected task is deleted and disappears from the child table.

  5. On the toolbar, click Save.

  6. Recompile the adapter.

Caution:

While deleting adapter tasks, ensure that the logic of the adapter is consistent and maintained.

8.12 Working with Responses

Adapters can have different outcomes, called responses. Based on these responses, adapters can trigger other process tasks.

For example, if the adapter returns a True response, the process task's status can be set automatically to Completed. However, if the adapter returns a False response, the process task's status can be set automatically to Rejected, and another process task can be triggered.

These responses can be added, modified, or removed on the Responses tab of the Adapter Factory form.

The following procedures will show you how to create, modify, and delete responses.

Note:

Responses are used only with process task adapters, because these adapters are attached to process tasks. Rule generators, pre-populate adapters, and entity adapters are not connected to processes. In addition, task assignment adapters are not associated with responses. Therefore, if the active adapter is a task assignment adapter, rule generator, pre-populate adapter, or entity adapter, Oracle Identity Manager disables the Responses tab.

8.12.1 To Create a Response

  1. Select the adapter to which you want to add responses (for example, the Create Solaris User adapter).

  2. Click the Responses tab.

  3. Click Add.

    An empty row is inserted into the Responses tab.

  4. Click the field that appears within the Code Name column.

  5. Enter a code, which represents a response type that can be generated (for example, True).

  6. Click the field that appears within the Description column.

  7. Enter a description for this response (for example, The user was created successfully.).

  8. Double-click the field that appears within the Status column.

    The Lookup popup window is displayed, containing the different status levels that you can associate with the response.

    Note:

    For more information about Oracle Identity Manager's status levels, refer to Chapter 4, "About Process Task Adapters" on page 4-1.

  9. Click the desired status level (for example, Completed (C)). Then, click OK.

    The Lookup window disappears, and the Responses tab is active once again.

  10. Create another response, by clicking the Add button, and entering False and The user was not created successfully. into the Code Name and Description fields, respectively. Then, access the Lookup window, and assign the Rejected (R) status level to this response.

  11. On the toolbar, click Save.

    The responses that you created for this adapter have been stored in the Oracle Identity Manager database. After you attach this adapter to a process task, these responses will appear in the Responses tab of the Editing Task window of the Process Definition form.

8.12.2 To Modify a Response

The following procedure demonstrates how to edit a response.

  1. Select the adapter that contains the response you want to edit (for example, the Create Solaris User adapter).

  2. Click the Responses tab.

  3. Double-click the field of the response, which contains information that you want to modify.

    1. If the field is a text field, Oracle Identity Manager enables it. You can now edit the contents within this field.

    2. When the field is a lookup field, the Lookup popup window is displayed, containing the different status levels that you can associate with the response. Click the desired status level, click OK.

    For example, double-click the Status column of the False response, select the Suspended (S) status level, and click OK.

  4. On the toolbar, click Save.

    The information that you modified for the response is stored in the Oracle Identity Manager database.

8.12.3 To Delete a Response

When a response is no longer necessary, you can delete it from the adapter.

  1. Select the adapter, which contains a response that you want to remove.

  2. Click the Responses tab.

  3. Select the response that you want to delete.

  4. Click Delete.

The response disappears. This indicates that Oracle Identity Manager has deleted the response.

8.13 Scheduling Rule Generators and Entity Adapters

Oracle Identity Manager triggers a process task adapter or a task assignment adapter automatically if it is attached to a process task, and the process task's status is Pending. In addition, Oracle Identity Manager always triggers pre-populate adapters on pre-insert. Therefore, you do not schedule when process task adapters, task assignment adapters, or pre-populate adapters will be executed.

On the other hand, a rule generator and an entity adapter are attached to a form field. The only way that Oracle Identity Manager will be able to execute the rule generator or entity adapter is for you to specify when it will be triggered. You do this through the Execution Schedule tab.

Note:

If an entity adapter is attached to a process form or an object form for validation of field values, these adapters will trigger if we edit data in these forms after completing direct or request provisioning.

Using this tab, you can determine that Oracle Identity Manager will trigger the rule generator or entity adapter on preinsert or preupdate. In addition, you can also schedule an entity adapter to be executed on predelete, postinsert, postupdate, and postdelete.

This procedure demonstrates how to configure Oracle Identity Manager to trigger a rule generator or entity adapter.

8.13.1 Scheduling Rule Generators and Entity Adapters

To schedule rule generator and entity adapters:

  1. Select the rule generator or entity adapter that you want Oracle Identity Manager to trigger (for example, Solaris User ID Generator).

    Note:

    When you work with process task adapters or pre-populate adapters, you do not use the Execution Schedule tab. As a result, this tab, as well as its contents, are grayed out.

  2. Click the Execution Schedule tab.

    The contents of the Execution Schedule tab appear.

    The following table will help you understand the various check boxes of the Execution Schedule tab:

    Name Description

    Pre-Insert

    By clicking this check box, Oracle Identity Manager can trigger the rule generator or entity adapter before the record is inserted into the database.

    Pre-Update

    When you click this check box, Oracle Identity Manager can trigger the rule generator or entity adapter before the record is updated in the database.

    Pre-Delete

    By clicking this check box, Oracle Identity Manager can trigger the entity adapter before the record is deleted from the database.

    Post-Insert

    When you click this check box, Oracle Identity Manager can trigger the entity adapter after the record is inserted into the database.

    Post-Update

    By clicking this check box, Oracle Identity Manager can trigger the entity adapter after the record is updated in the database.

    Post-Delete

    When you click this check box, Oracle Identity Manager can trigger the entity adapter after the record is deleted from the database.


    Note:

    By clicking the check boxes of the Execution Schedule tab, you are defining the times when Oracle Identity Manager can trigger the rule generator or entity adapter. The Data Object Manager form allows you to specify when Oracle Identity Manager will trigger the rule generator or entity adapter.

    For more information about the Data Object Manager form, refer to "Mapping Rule Generator Adapter Variables".

  3. Enable the desired check boxes. Then, from the toolbar, click Save.

    The criteria you set for Oracle Identity Manager to execute the rule generator or entity adapter is stored in the Oracle Identity Manager database.

8.14 Working with Rule Generator Adapters

This section explains how to work with rule generator adapters, and contains these topics:

8.14.1 Mapping Rule Generator Adapter Variables

After creating a rule generator, you must map the adapter variables of the rule generator to their proper locations to ensure that the adapter will function as intended.

To map these adapter variables, access the Data Object Manager form from the Development Tools/Business Rule Definition folder of the Design Console.

To map the adapter variables of a rule generator to their proper locations:

  1. Open the Data Object Manager form. In the Design Console workshops, the Data Object Manager form is displayed.

    The following table lists and describes the various regions of the Data Object Manager form:

    Name Description

    Form Description Field

    From this lookup field, select the form that contains the field to which you are attaching the rule generator.

    Data Object Field

    This field displays the name of the data object, which is represented by the selected form.

    Attach Handlers Tab

    This tab displays:

    • The rule generators that are attached to the selected form.

    • The execution schedule of the rule generators associated with this form.

    • The order in which Oracle Identity Manager will run the rule generators.

    • Insert, update, and delete permissions for roles.

    Map Adapters Tab

    This tab displays:

    • The names of the rule generators that are associated with the form;

    • The status of these adapters.

    • The names, descriptions, and mapping statuses of the rule generators' adapter variables.

    Note: The Map Adapters tab is grayed out until an adapter is assigned to the current data object.


  2. Double-click the Form Description field. A Lookup dialog box appears with the forms to which you can attach rule generators.

  3. Select the form you want (for example, Solaris). Then, click OK.

  4. On the toolbar, click Save.

    The selected form, the form's data object, and the rule generator adapters associated with the form appear. In addition, Oracle Identity Manager enables the Map Adapters tab.

    For this example, the Solaris form has been selected. Its data object Thor.CarrierBase.tcUD_SOLARIS appears, along with the four rule generator adapters associated with it (adpCONVERTTOLOWERCASE, adpSOLARISHMDSTRINGGEN, adpSETSOLARISASSET, and adpSETPASSWORDFROMMAIN). Oracle Identity Manager will trigger these four rule generators on preinsert.

    Based on the sequence numbers of these adapters, Oracle Identity Manager will trigger the adpCONVERTTOLOWERCASE adapter first, followed by the adpSOLARISHMDSTRINGGEN, adpSETSOLARISASSET, and adpSETPASSWORDFROMMAIN adapters respectively.

    Tip:

    To change the sequence of triggering a rule generator:

    1. Click Assign. The Event Handlers dialog box is displayed.

    2. Select the rule generator from.

    3. Click the up arrow and down arrow buttons to modify the order of the rule generator.

    For these rule generators to work properly, you must map the adapter variables to their proper locations.

  5. Click the Map Adapters tab.

  6. From the Name combo box, select the rule generator, which has adapter variables that can be mapped (for example, the adpCONVERTTOLOWERCASE rule generator).

    The Map Adapters tab now displays the following:

    • The name of the rule generator that is to be attached to the form.

    • The status of the rule generator.

    • The names, descriptions, and mapping statuses of the rule generator's adapter variables.

    See Also:

    "Attaching Process Task Adapters to Process Tasks" for information about various mapping statuses for an adapter

  7. Set the mappings for each variable that appears in the Adapter Variables region of the Map Adapters tab. To do so, double-click the row header of the variable you want to map (for example, Data). The Data Mapping for Variable dialog box is displayed.

    Table 8-9 describes the various fields of the Data Mapping for Variable dialog box.

    Table 8-9 Fields of the Data Mapping for Variable Dialog Box

    Field Name Description

    Variable Name

    This field displays the name of the adapter variable for which you are setting a mapping (for example, Data).

    Data Type

    This field shows the data type of the adapter variable (for example, String is the data type for the Data adapter variable).

    Map To

    This field contains the source and target locations of the mappings you can set for the adapter variable (for example, User Definition).

    When you map the adapter variable to a location or a contact, Oracle Identity Manager enables the adjacent combo box. From this combo box, select the specific type of location or contact to which you are mapping the adapter variable.

    If you are not mapping the adapter variable to a location or contact, this combo box is grayed out.

    Qualifier

    This field contains the qualifiers for the mapping you selected in the Map To combo box (for example, User Login).

    IT Asset Type

    This field enables you to select a specific IT Resource (for example, Solaris) when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.

    IT Asset Property

    This field enables you to select a specific field that will receive the results of the mapping (for example, User Name), when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.

    Important: The IT Asset Type and IT Asset Property fields are included within this window for backward compatibility. The preferred way is to create an adapter variable with a data type of IT Resource, in which case these fields will not appear.

    Literal Value

    When you map the adapter variable to a literal, type the name of the specific literal in this field (for example, IBM).

    If you are not mapping the adapter variable to a literal, this field does not appear.


    Complete the Map To, Qualifier, IT Asset Type, IT Asset Property, and Literal Value fields.

    See Also:

    "Adapter Mapping Information" for more information about the mappings to select

  8. Click Save. Then, click Close

    The Data Mapping for Variable window disappears. The Map Adapters tab is active again.

  9. On the main screen toolbar, click Save.

Repeat Steps 7 and 8 for all adapter variables that can be mapped.

The contents in the Status field change from Mapping Incomplete to Ready. In addition, the mapping statuses for the adapter variables change from No (N) to Yes (Y).

This signifies that all the adapter variables for the rule generator adapter have been mapped correctly. You are now ready to attach this rule generator to a provisioning process, so it can be triggered after the process is provisioned to a target user or organization.

Tip:

When you map all the adapter variables for a rule generator that is associated with a form, a quick way to see the form to which it is attached as well as the execution schedule of the rule generator, is by accessing the Usage Lookup tab of the Adapter Factory form.

After the rule generator is assigned to a process, and the process is provisioned, the rule generator will be executed by Oracle Identity Manager.

8.14.2 Associating Rule Generators with Processes

After you map the adapter variables of a rule generator to their proper locations, you must attach it to a provisioning process. Then, once the process is provisioned to a target user or organization, Oracle Identity Manager will trigger the associated rule generator.

Similarly, when a rule generator, which has been assigned to a provisioning process, is no longer needed for the process to be completed, you must remove the rule generator from the provisioning process.

To assign a rule generator to a provisioning process or remove a rule generator from a provisioning process, access the Event Handlers/Adapters tab in the Process Definition form. This form can be found in the Process Management folder.

8.14.3 Removing Rule Generators from Form Fields

Sometimes, after you attach a rule generator to a form field, you can connect a different rule generator to that form field. When this occurs, you must first remove the rule generator that is currently attached to the form field.

Caution:

If you remove a rule generator from a form and if the class name of the form's data object matches the table name of a provisioning process, you will not be able to assign the rule generator to that provisioning process.

For example, suppose the adpCONVERTTOLOWERCASE rule generator is removed from the Solaris form. If the class name of the form's associated data object is UD_SOLARIS, the rule generator cannot be assigned to any provisioning process with a table name of UD_SOLARIS.

To remove a rule generator from a form field, perform the following steps:

  1. Open the Data Object Manager form.

  2. Select the form that contains a rule generator you want to remove.

  3. The selected form, along with its rule generators, appear in the Data Object Manager form.

  4. Click the rule generator that you want to remove from the form field.

  5. Click Delete.

The selected rule generator no longer appears in the Data Object Manager form. This indicates that you have removed the rule generator from the form field.

Caution:

If you attempt to remove a rule generator from a form field, and if an error box appears, the adapter has already been associated with a provisioning process. First, detach the rule generator from the process. Then, you can remove it from the form field.

8.15 Working with Entity Adapters

For information about working with entity adapters, see:

Note:

In Oracle Identity Manager 11g Release 2 (11.1.2), creating new entity adapters and modifying existing entity adapters are not supported. However, if you have upgraded from Oracle Identity Manager Release 9.x, then the existing entity adapters continue to work, and you can view the existing variable mappings of the adapters.

8.16 Working with Task Assignment Adapters

This section contains these topics:

8.16.1 Attaching Task Assignment Adapters to Process Tasks

After creating a task assignment adapter, you must attach it to a process task so that Oracle Identity Manager can automate the assignment of the task to a user or role.

To connect a task assignment adapter to a process task, access the Assignment tab (from the Process Definition form). From this tab, you can also map any adapter variables to their proper locations.

The following procedure shows you how to attach a task assignment adapter to a process task.

  1. Open the Process Definition form, which is located in the Process Management folder.

    Within the Oracle Identity Manager workspace, the Process Definition form appears.

  2. Select the process, which contains a task to which you want to attach an adapter.

    The selected process, along with its tasks, appears in the Process Definition form.

  3. Double-click the row header of the task to which you want to attach a task assignment adapter.

    The Editing Task window appears, containing information about the task (for example, the Get Solaris UUID process task).

  4. Click the Assignment tab. The Assignment dialog box is displayed.

  5. From this tab, click Add.

    A blank row appears within the Assignment tab.

    The following table lists the relevant fields of the Assignment tab:

    Field Name Description

    Priority

    From this field, set the priority number for the associated task assignment rule.

    Rule

    From this lookup field, select the rule that will determine if the associated adapter will be used to automate the assignment of the process task to a user or role.

    Target Type

    From this lookup field, specify whether the task is to be assigned to an Oracle Identity Manager user or role.

    Adapter

    From this lookup field, select the adapter that is to be associated with the designated task assignment rule.

    Adapter Status

    This field displays the mapping status of the adapter's variables.

    See "Attaching Process Task Adapters to Process Tasks" for information about the various mapping statuses for an adapter.


  6. Double-click the Priority field. From this field, set the priority number for the associated task assignment rule.

  7. Double-click the Rule lookup field. From the Lookup dialog box that is displayed, select the rule that will determine if the associated adapter will be used to automate the assignment of the process task to a user or role.

  8. Double-click the Target Type lookup field. From the Lookup dialog box that is displayed, specify whether the task is to be assigned to an Oracle Identity Manager user or role.

  9. Double-click the Adapter lookup field. From the Lookup dialog box that is displayed, specify the task assignment adapter that is to be associated with the rule you selected in Step 7 of this procedure.

  10. On the toolbar that is displayed within the Assignment tab, click Save.

    The mapping status of the task assignment adapter variables is displayed within the Adapter Status field. Use the following table to decide which action to perform, based on the adapter's mapping status.

    Mapping Status Action

    Ready

    The adapter does not have any variables that can be mapped. In other words, none of the adapter variables are return variables or have been designated as Resolve at Run time. So, proceed to Step 14 of this procedure.

    Mapping Incomplete

    At least one of the adapter's variable must be mapped. So, proceed to Step 11 of this procedure.

    Adapter Unavailable

    After the adapter had been compiled successfully, it was modified. As a result, you must recompile the adapter.


    Note:

    To learn more about the various mapping statuses for an adapter, see "Attaching Process Task Adapters to Process Tasks".

  11. Click Map.

    The Adapter Variables window appears. It displays the following information:

    • The name of the task assignment adapter that is attached to the process task;

    • The status of the adapter; and

    • The mapping statuses, names, and descriptions of the adapter's variables.

  12. Set the mappings for each variable that appears in the Adapter Variables region of this window. To do so, double-click the row header of the variable you want to map (for example, UUID).

    The Edit Data Mapping for Variable dialog box is displayed.

    Table 8-10 lists the fields of the Edit Data Mapping for Variable dialog box is displayed.

    Table 8-10 Fields of the Edit Data Mapping for Variable Dialog Box

    Field Name Description

    Variable Name

    This field displays the name of the adapter variable for which you are setting a mapping (for example, UUID).

    Data Type

    This field shows the data type of the adapter variable (for example, String is the data type for the UUID variable).

    Map To

    This field contains the types of mappings that you can set for the adapter variable (for example, IT Resources).

    When you map the adapter variable to a location or a contact, Oracle Identity Manager enables the adjacent combo box. From this combo box, select the specific type of location or contact to which you are mapping the adapter variable.

    In addition, if you map the adapter variable to a custom process form, and this form contains child table(s), Oracle Identity Manager enables the adjacent combo box. From this combo box, select the child table to which you are mapping the adapter variable.If you are not mapping the adapter variable to a location, contact, or child table of a custom process form, this combo box is grayed out.

    Qualifier

    This field contains the qualifiers for the mapping you selected in the Map To combo box (for example, IT Asset).

    IT Asset Type

    This field enables you to select a specific IT Resource (for example, Solaris) when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.

    IT Asset Property

    This field enables you to select a specific field that will receive the results of the mapping (for example, Unique ID), when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or if the variable's data type is not String, this field does not appear.

    Important: The IT Asset Type and IT Asset Property fields are included within this window for backward compatibility. The preferred way is to create an adapter variable with a data type of IT Resource, in which case these fields will not appear.

    Literal Value

    When you map the adapter variable to a literal, use this field to specify the specific literal value.

    If you are not mapping the adapter variable to a literal, this field does not appear.

    Old Value

    By selecting this check box, you map the adapter variable to the value that was originally in the selected Qualifier field before modification.

    Process task adapters associated with process tasks are conditionally triggered when some field on the process form is changed. If you click the Old Value option, and the process task is marked Conditional, the value that is passed to the adapter is the previous value of the field. This is useful in cases of fields that accept passwords.

    For example, if you want to disallow setting the password to the same value, you can use the old value for comparison.

    If you are not mapping the adapter variable to a field that belongs to a child table of a custom process form, this check box is grayed out.


  13. Complete the Map To, Qualifier, IT Asset Type, IT Asset Property, Literal Value, and Old Value fields.

    See Also:

    "Adapter Mapping Information" for more information about the mappings to select

  14. On the toolbar, click Save. Then, click Close.

    The Edit Data Mapping for Variable window disappears. The Adapter Variables dialog box is active again.

    The contents in the Status field change from Mapping Incomplete to Ready. In addition, the mapping statuses for the adapter's variables change from No (N) to Yes (Y).

  15. Click Save. Then, click Close.

    The Adapter Variable dialog box disappears, and the Assignment tab is active once again.

    The adapter that you assigned to the process task (for example, Assign Solaris Task) now has a status of Ready.

  16. From the toolbar that appears within the Assignment tab, click Save and Close

    The Assignment tab disappears, and the main screen is active once again. This signifies that the task assignment adapter is attached to the process task.

    Note:

    Once you attach a task assignment adapter to a process task, a quick way to see the process and the task to which it is connected is by accessing the Usage Lookup tab of the Adapter Factory form.

8.16.2 Removing Task Assignment Adapters from Process Tasks

When a task assignment adapter either becomes invalid, or is no longer necessary for Oracle Identity Manager to allocate the process task to a user or role, you must remove the adapter from the task.

8.16.2.1 To Remove a Task Assignment Adapter from a Process Task

To detach a task assignment adapter from a process task, perform the following tasks:

  1. Open the Process Definition form.

    The Process Definition form appears in the Design Console workspace.

  2. Select the process, which contains a task from which you want to remove an adapter (for example, the Solaris 8 process).

    The selected process, along with its tasks, appears in the Process Definition form.

  3. Double-click the row header of the process task from which you want to remove the adapter (for example, the Get Solaris UUID task).

    The Editing Task dialog box is displayed, containing information about the process task.

  4. Click the Assignment tab.

    The Assignment tab appears, displaying information about the adapter that is attached to the process task.

  5. Highlight the row, containing the adapter that you want to remove from the process task.

  6. Click Delete. The adapter no longer appears within the Assignment tab.

  7. Click Save. Then, click Close.

    The Assignment tab disappears, and the Main Screen is active once again. This signifies that the task assignment adapter is removed from the process task.

8.17 Working with Prepopulate Adapters

This section contains these topics:

8.17.1 Attaching Prepopulate Adapters to Form Fields

To attach a prepopulate adapter to a form field, perform the following steps:

  1. Select the field to which a prepopulate adapter will be attached.

  2. Select the rule that will determine if the adapter will be used to populate the designated field with information.

  3. Select the adapter that will be associated with the designated field.

  4. Set the priority number of the selected rule.

  5. Map the adapter variables of the prepopulate adapter to their proper locations.

    Note:

    To attach a prepopulate adapter to a form field, you must ensure the following:

    • The form is not in an active state. Otherwise, create a new form version.

    • After attaching the adapter, you must activate the form to be able to use it.

  6. Open the Form Designer form.

  7. Query for the form to which you want to attach a prepopulate adapter (for example, Solaris).

  8. Click the prepopulate tab.

    The prepopulate adapters, which have already been attached to the form you queried, appear within this tab.

    Note:

    If no adapters have been attached to a form field, the prepopulate tab will be empty.

  9. Click Add.

    The prepopulate Adapters dialog box is displayed.

    Table 8-11 lists and describes the fields of the prepopulate Adapters dialog box.

    Table 8-11 Fields of the Prepopulate Adapter Dialog Box

    Name Description

    Field Name

    This combo box contains a list of all of the form fields to which a prepopulate adapter can be attached.

    Rule

    From this lookup field, select the rule that will determine if the associated adapter will be used to populate the designated form field with information.

    Adapter

    From this lookup field, select the adapter that will be associated with the designated field.

    Order

    From this field, set the priority number of the selected rule.

    Adapter Status

    This field displays the mapping status of the adapter variables.

    See "Attaching Process Task Adapters to Process Tasks" for information about the various mapping statuses for an adapter.

    Adapter Variables

    This area displays the following:

    • Mapped: The mapping statuses of the adapter's variables. "Y" indicates that an adapter variable has been mapped properly; "N" indicates that this variable has not been mapped correctly.

    • Name: The names of the adapter variables.

    • Mapped to: The form fields to which the variables are mapped If an adapter variable is not yet mapped, the corresponding cell in this column will be empty.


  10. From the Field Name combo box, select the form field, such as User ID, to which the prepopulate adapter will be attached.

  11. Double-click the Rule lookup field. From the Lookup dialog box that is displayed, select the rule that will determine if the associated adapter will be used to populate the designated form field with information (for example, Rule for Lowercase User ID).

  12. Double-click the Adapter lookup field. From the Lookup dialog box that is displayed, choose the adapter that will be associated with the field you selected in Step 10, for example, Display Lowercase Letters for User ID.

  13. In the Order field, enter the priority number of the rule you selected in Step 11, for example, 2.

  14. On the prepopulate Adapters window toolbar, click Save.

  15. Mapping Incomplete appears within the Adapter Status field. This signifies that the adapter you selected contains variables that have not been mapped correctly. These variables can be mapped to their proper locations. Otherwise, the adapter will not work.

  16. Set the mappings for each variable that appears in the Adapter Variables region of the prepopulate Adapters window. To do so, double-click the row header of the variable you want to map, for example, UserID.

    The Map Adapter Variables window is displayed.

    Table 8-12 describes the fields of the Map Adapter Variables window.

    Table 8-12 Fields of the Map Adapter Variables WIndow

    Field Name Description

    Variable Name

    This field displays the name of the adapter variable for which you are setting a mapping (for example, UserID).

    Data Type

    This field shows the data type of the adapter variable (for example, String is the data type for the UserID adapter variable).

    Map To

    This field contains the types of mappings that you can set for the adapter variable (for example, Process Data).

    When you map the adapter variable to a location or a contact, Oracle Identity Manager enables the adjacent combo box. From this combo box, select the specific type of location or contact to which you are mapping the adapter variable.

    If you are not mapping the adapter variable to a location or contact, this combo box is grayed out.

    Qualifier

    This field contains the qualifiers for the mapping you selected in the Map to combo box (for example, User ID).

    IT Asset Type

    This field enables you to select a specific IT Resource (for example, Solaris) when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.

    IT Asset Property

    This field enables you to select a specific field that will receive the results of the mapping (for example, User Name), when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.

    Important: The IT Asset Type and IT Asset Property fields are included within this window for backward compatibility. The preferred way is to create an adapter variable with a data type of IT Resource, in which case these fields will not appear.

    Literal Value

    When you map the adapter variable to a literal, use this field to specify the specific literal value.

    If you are not mapping the adapter variable to a literal, this field does not appear.


  17. Complete the Map To, Qualifier, IT Asset Type, IT Asset Property, and Literal Value fields.

    See Also:

    "Adapter Mapping Information" for more information about the mappings to select

  18. On the Map Adapter Variable window toolbar, click Save. Then, click Close.

    The Map Adapter Variables window disappears. The prepopulate Adapters window is active again.

    The text in the Adapter Status field changes from Mapping Incomplete to Ready. In addition, the mapping statuses for the adapter's variables change from No (N) to Yes (Y).

  19. On the prepopulate Adapters window toolbar, click Close.

The prepopulate Adapters window disappears, and the Form Designer form is active again. The prepopulate adapter, which you attached to the User ID form field (Display Lowercase Letters for User ID), appears in the prepopulate tab of the Results of 1Q Sales 2003 form.

After a process, which references this form, is provisioned to a target user or organization, the form will appear. Oracle Identity Manager will check to see if the prepopulate rule, which has the highest priority, is valid. If so, Oracle Identity Manager will assign the associated prepopulate adapter to the designated field (User ID), and execute it. At this point, one of the following actions occur:

  • If the Auto-prepopulate check box is selected for the provisioning process, Oracle Identity Manager will display the data that is generated by the prepopulate adapter automatically.

  • If the Auto-prepopulate check box is cleared, an Oracle Identity Manager user must manually trigger the displaying of the data that is generated by the prepopulate adapter. To do this, the administrator must click the prepopulate button on the form section of the direct provisioning wizard in the Web client, while provisioning the form to a user.

Tip:

Once you allocate a prepopulate adapter to a form field, and assign a prepopulate rule to the adapter, a quick way to see the association among the adapter, the form field, and the rule is by accessing the Usage Lookup tab of the Adapter Factory form.

8.17.2 Removing Prepopulate Adapters from Form Fields

If a prepopulate adapter, which has been associated with a form field, is no longer valid, you must remove the adapter from the field.

Note:

Before removing the prepopulate adapter from a form field, you must create a new version of the form.

To remove a prepopulate adapter from a form field:

  1. Select the prepopulate adapter that you want to remove.

  2. Click Delete. The prepopulate adapter is removed from the form field. It cannot be triggered when the form is launched.

  3. After removing the adapter, you must activate the form.

8.18 Working with Process Task Adapters

This section contains these topics:

8.18.1 Guidelines for Working with a Process Task Adapter

After you create a process task adapter, you attach it to the appropriate process task by using the Integration tab of the Process Definition form. From this tab, you can also map any variables of the adapter to their proper locations, which were designated as either Resolve at Run time or as an adapter return variable.For example, the adapter named adpSOLARISPASSWORDUPDATED is connected to the Password Updated task of the Solaris process.After you attach an adapter to a process task, for the adapter to be functional, it might need data from fields of other forms. For this example, the adpSOLARISPASSWORDUPDATED adapter cannot work unless it obtains the following information:

  • The user's Oracle Identity Manager ID and password.

  • The user's Solaris ID and password.

  • The IP address where Solaris is located.

Therefore, it must get this information from the UserID, Passwd, SolarisUserID, SolarisUserPasswd, and ServerAddress adapter variables respectively. These five variables are created by using the Adapter Factory form. The "Y" that precedes each adapter variable signifies that it has been mapped correctly.The form that enables you to create process-specific fields, which will be used by a process to obtain the information it needs, is called the Form Designer. When you create these fields, Oracle Identity Manager stores them into a table. Then, by associating this table with a process (through the Table Name lookup field of the Process Definition form), the adapter, which you attach to a task of this process, will use the table to retrieve the appropriate data.If you want to modify this table, you can do so through the Form Designer form.The UD_SOLARIS table contains two fields: UD_SOLARIS_USERID and UD_SOLARIS_PASSWD. By accessing this record of the Form Designer form, you can edit the fields of the table.

Once you attach the process task adapter to a dependent process task, and the status of this process task is Pending (the status of the previous process task is Completed), Oracle Identity Manager will trigger the adapter automatically. When the process task is an independent task, Oracle Identity Manager will execute the adapter as soon as the process is requested.The result of the adapter being executed represents the state of the process task. When the adapter is finished successfully, the process task to which this adapter is attached will have a status of Completed.On the other hand, if the adapter cannot perform its designated function, the process task to which this adapter is attached will have a status of Rejected. By discovering the cause of the error, you can modify the process task and/or adapter so it can run successfully.

Note:

To determine why a process task might have failed:

Find the process task. When the process task has not yet been provisioned to the target user or organization, it is located in the To Do List or Pending Approvals. To find the task:

  1. Log in as the user.

  2. Select the To Do List link or the Pending Approvals links in the left side of the window.

8.18.2 Attaching Process Task Adapters to Process Tasks

In the previous chapter, you learned how to create a process task adapter. You must attach it to a process task to execute that process task automatically.To connect an adapter to a process task, access the Integration tab (from the Process Definition form). From this tab, you can also map any adapter variables to their proper locations.The following procedure shows you how to attach a process task adapter to a process task:

  1. Open the Process Definition form, which is located in the Process Management folder.

    In the Oracle Identity Manager Workspace, the Process Definition form appears.

  2. Select the process, which contains a task to which you want to attach an adapter. The selected process, along with its tasks, appears in the Process Definition form. For this example, the Solaris process has been selected.

  3. Double-click the row header of the task to which you want to attach an adapter. The Editing Task window appears, containing information about the task (for example, the Password Updated process task).

  4. Click the Integration tab.

  5. Click Add.

    The Handler Selection window appears.

  6. To access Oracle Identity Manager adapters, click the Adapter option.

    The adapters appear, which you can attach to the process task.

  7. From this region, select the adapter that you want to attach to the process task, for example, the adpSOLARISPASSWORDUPDATED adapter.

    Tip:

    For classification purposes, the first three letters of each adapter's name are adp. For classification purposes, the first three letters of each adapter's name are adp.

  8. From the Handler Selection window's toolbar, click Save.

    A dialog box appears, stating that the adapter was successfully added to the process task.

  9. Click OK.

    The dialog box disappears, and the Integration tab is now active. This tab now displays the following:

    • The name of the adapter that is attached to the process task;

    • The status of the adapter; and

    • The names, descriptions, and mapping statuses of the adapter's variables.

    Note:

    An adapter can have one of three mapping statuses:

    Ready. This adapter has been successfully compiled, and all of its variables have been mapped correctly.

    Mapping Incomplete. This adapter has been successfully compiled, but at least one of its variables have not been mapped correctly.

    Adapter Unavailable. After this adapter had been compiled successfully, it was modified, and recompiled.

    Note:

    If an adapter does not have any mappable variables, the Adapter Variables region is empty. In addition, the Status field will display either Ready or Adapter Unavailable, depending on whether the adapter has to be recompiled.

    Note:

    A mappable adapter variable either has been designated as Resolve at Run time or it is an adapter return variable.

    Note:

    Once you attach the adapter to the process task, any responses that you defined for the adapter appear in the Responses tab of the Editing Task window.

  10. Set the mappings for each variable that appears in the Adapter Variables region of the Integration tab. To do so, double-click the row header of the variable you want to map (for example, SolarisUserID).

    The Data Mapping for Variable window is displayed.

    Table 8-13 describes the fields of the Data Mapping for Variable window.

    Table 8-13 Fields of the Data Mapping for Variable WIndow

    Field Name Description

    Variable Name

    This field displays the name of the adapter variable for which you are setting a mapping (for example, SolarisUserID).

    Data Type

    This field shows the data type of the adapter variable (for example, String is the data type for the SolarisUserID variable).

    Map To

    This field contains the types of mappings that you can set for the adapter variable (for example, IT Resources).When you map the adapter variable to a location or a contact, Oracle Identity Manager enables the adjacent combo box. From this combo box, select the specific type of location or contact to which you are mapping the adapter variable. In addition, if you map the adapter variable to a custom process form, and this form contains child table(s), Oracle Identity Manager enables the adjacent combo box. From this combo box, select the child table to which you are mapping the adapter variable. If you are not mapping the adapter variable to a location, contact, or child table of a custom process form, this combo box is grayed out.

    Qualifier

    This field contains the qualifiers for the mapping you selected in the Map to combo box (for example, IT Asset).

    IT Asset Type

    This field enables you to select a specific IT Resource (for example, Solaris) when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.

    IT Asset Property

    This field enables you to select a specific field that will receive the results of the mapping (for example, User Name), when you map an adapter variable to an IT Resource, and this variable's data type is String.

    If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.

    Important: The IT Asset Type and IT Asset Property fields are included within this window for backward compatibility. The preferred way is to create an adapter variable with a data type of IT Resource, in which case these fields will not appear.

    Literal Value

    When you map the adapter variable to a literal, use this field to specify the specific literal value.

    If you are not mapping the adapter variable to a literal, this field does not appear.

    Old Value

    By selecting this check box, you map the adapter variable to the value that was originally in the selected Qualifier field before modification.

    Process task adapters associated with process tasks are conditionally triggered when some field on the process form gets changed. If you click the Old Value option, and the process task is marked Conditional, the value that is passed to the adapter is the previous value of the field, before it got modified. This is useful in cases of fields that accept passwords. For example, if you want to disallow setting the password to the same value, you can use the old value for comparison.

    If you are not mapping the adapter variable to a field that belongs to a child table of a custom process form, this check box is grayed out.


  11. Complete the Map To, Qualifier, IT Asset Type, IT Asset Property, Literal Value, and Old Value fields.

    See Also:

    "Adapter Mapping Information" for more information about the mappings to select

  12. On the toolbar, click Save. Then, click Close.

    The Data Mapping for Variable window disappears. The Integration tab is active again.

  13. On the Editing Task window toolbar, click Save.

    The contents in the Status field change from Mapping Incomplete to Ready. In addition, the mapping statuses for the adapter's variables change from No (N) to Yes (Y).

  14. On the toolbar, click Close.

    The Editing Task window disappears, and the main screen is active once again. The adapter you added to the Password Updated task (adpSOLARISPASSWORDUPDATED) appears in the Process Definition form.This signifies that the adpSOLARISPASSWORDUPDATED process task adapter was attached to the Password Updated process task.

    Tip:

    Once you attach a process task adapter to a process task, a quick way to see the process and task to which it is connected is by accessing the Usage Lookup tab of the Adapter Factory form.

8.18.3 Removing Process Task Adapters from Process Tasks

If a process task adapter is no longer necessary for Oracle Identity Manager to complete the process task automatically, or when you wish to attach a different adapter to a process task, you must first remove the adapter that is attached to the process task.This procedure will show you how to remove a process task adapter from a process task.

8.18.3.1 To Remove a Process Task Adapter from a Process Task

  1. Open the Process Definition form.

    In the Design Console workspace, the Process Definition form appears.

  2. Select the process, which contains a task from which you want to remove an adapter (for example, the Solaris process).

    The selected process, along with its tasks, appears in the Process Definition form.

  3. Double-click the row header of the process task from which you want to remove the adapter (for example, the Password Updated task).

    The Editing Task window appears, containing information about the process task. Click the Integration tab.

  4. Click the Integration tab.

    The Integration tab displays information about the adapter that is attached to the process task.

  5. Click Remove.

    A dialog box appears, asking if you want to remove the adapter from the process task.

  6. Click OK.

    A dialog box appears, signifying that the adapter has been removed from the process task.

  7. Click OK.

    The contents of the adapter no longer appear in the Integration tab.

  8. On the toolbar, click Close.

    The Editing Task window disappears, and the main screen is active once again. The adapter that was once linked to the Password Updated task (adpSOLARISPASSWORDUPDATED) no longer appears in the child table of the Process Definition form.

    This signifies that you have removed the adapter from the process task.

8.19 Adapter Mapping Information

An adapter is a Java class, generated by the Adapter Factory, which enables Oracle Identity Manager to interact with an external JAR file, a target IT resource (for example, a resource asset), or a user-defined form. The Adapter Factory is a code-generation tool provided by Oracle Identity Manager, which enables a User Administrator to create Java classes.

An adapter extends the internal logic and functionality of Oracle Identity Manager. It automates process tasks, and defines the rules for the auto-generation and validation of data in fields within Oracle Identity Manager. There are five types of adapters: task assignment adapters, task adapters, rule generator adapters, pre-populate adapters, and entity adapters.

The following topics are discussed in this section:

8.19.1 Adapter Task Mapping Information

An adapter task is one of the several possible components within an adapter. And this is a logical step within an adapter, equivalent to calling a programming language method. The following types of adapter tasks are available: Functional Tasks (Java Task, Remote Task, and Stored Procedure Task), Utility Tasks (Utility Task and Oracle Identity Manager API Task), and Logic Tasks (Set Variable Task and Error Handler Task).

This section lists the mappings that you can set for the parameters of an adapter task, in the following topics:

8.19.1.1 Adapter Variables

The following table lists and describes the items of the Map To list box of the Data Mapping for Variable window and the Name list box to which you can map the parameters of an adapter variable for an adapter task.

Map To Combo Box Name Combo Box Description

Adapter Variables

A list of adapter variables are displayed

You can map the parameter to the adapter variables that you created for this adapter.

Note: When the adapter variable's classification type is Object, it cannot be used with process task adapters.

Note: If the adapter variable's classification type is IT Resource, then an Attribute combo box is displayed. From this combo box, select the attribute of the IT resource to which you wish to map the parameter.


8.19.1.2 Adapter Task

The following table lists and describes the items of the Map To, Name, and Output combo boxes of the Adapter Factory form to which you can map the parameters of an adapter task.

Map To Combo Box Name Combo Box Output combo Box Description

Adapter Task

A list of adapter tasks are displayed.

A list of output variables pertaining to the selected adapter task is displayed.

You can map the parameter to the adapter tasks that you created for this adapter.


8.19.1.3 Literal

The following table lists and describes the items of the Map To and Type combo boxes, as well as the Value field of the Adapter Factory form, to which you can map the parameters of a constant (or literal) for an adapter task.

Map To Combo Box Type Combo Box Value Field Description

Literal

String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, Double

Enter the value of the literal into this field.

You can map the parameter to a String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, or Double data type, respectively.


8.19.1.4 Adapter References

The following table lists and describes the items of the Map To and Type combo boxes of the Adapter Factory form to which you can map the parameters of an adapter reference for an adapter task.

Map To Combo Box Type Combo Box Description

Adapter References

Event Handler Name or Database Reference

You can map the parameter to the active adapter.


8.19.1.5 Organization Definition

The following table lists and describes the items of the Map To and Field combo boxes of the Adapter Factory form to which you can map the parameters of an organization definition for an adapter task.

Map To combo box Field Combo Box Description

Organization Definition

Organization Name

You can map the parameter to the Organization Name field of the Organizations form.

 

Organization Type

You can map the parameter to the Type field of the Organizations form.

 

Organization ID

You can map the parameter to the Organization # field of the Organizations form.

 

Organization Parent

You can map the parameter to the Parent Organization field of the Organizations form.

 

Organization Status

You can map the parameter to the Status field of the Organizations form.

 

Organization Parent ID

You can map the parameter to the parent_key field in the ACT database table.

 

Any fields that are displayed in the User Defined Fields tab of the Organizations form.

You can map the parameter to the selected user-defined field.


8.19.1.6 Process Definition

The following table lists and describes the items of the Map To and Field combo boxes of the Adapter Factory form to which you can map the parameters of a process definition for an adapter task.

Map To Combo Box Field Combo Box Description

Process Definition

Name

You can map the parameter to the Name field of the Process Definition form.

 

Type

You can map the parameter to the Type field of the Process Definition form.


8.19.1.7 User Definition

The following table lists and describes the items of the Map To and Field combo boxes of the Adapter Factory form to which you can map the parameters of a user definition for an adapter task.

Map To Combo Box Field Combo Box Description

User Definition

User Key

You can map the parameter to a key, representing a unique record of the Users form.

 

First Name

You can map the parameter to the First Name field of the Users form.

 

Middle Initial

You can map the parameter to the Middle Name field of the Users form.

 

Last Name

You can map the parameter to the Last Name field of the Users form.

 

User Login

You can map the parameter to the User ID field of the Users form.

 

Password

You can map the parameter to user password of the Users form.

 

Type

You can map the parameter to the Xellerate Type field of the Users form.

 

User Status

You can map the parameter to the Status field of the Users form.

 

Role

You can map the parameter to the Role field of the Users form.

 

Identity

You can map the parameter to the Identity field of the Users form.

 

Disabled

You can map the parameter to the Disable User check box of the Users form.

 

Organization

You can map the parameter to the Organization field of the Users form.

 

Manager

You can map the parameter to the Manager field of the Users form.

 

Start Date

You can map the parameter to the Start Date field of the Users form.

 

End Date

You can map the parameter to the End Date field of the Users form.

 

Email

You can map the parameter to the Email field of the Users form.

 

Provisioning Date

You can map the parameter to the Provisioning Date field of the Users form.

 

Provisioned Date

You can map the parameter to the Provisioned Date field of the Users form.

 

Deprovisioning Date

You can map the parameter to the Deprovisioning Date field of the Users form.

 

Deprovisioned Date

You can map the parameter to the Deprovisioned Date field of the Users form.

 

Any fields that are displayed in the User Defined Fields tab of the Users form.

You can map the parameter to the selected user-defined field.


8.19.2 Adapter Variable Mapping Information

For a newly created adapter to work, you can map data to the parameters of the adapter's tasks. For this reason, you create placeholders, also known as adapter variables, to map the data at run time. Once an adapter variable is not needed for the adapter to run, you can remove it from the adapter. After you have deleted the adapter variable, recompile the adapter.

When an adapter variable is not the adapter return variable, or it is not designated as Resolve at Run time, it should be mapped within the Variable List tab of the Adapter Factory form. On the other hand, if the adapter variable is classified as an adapter return variable, or the adapter variable is set to Resolve at Run time, it can be mapped at another location within Oracle Identity Manager. This location is contingent upon the adapter's type. For example, the variables of a process task adapter will be mapped at a different place than the variables of a pre-populate adapter. The following table lists the variables of a particular type of adapter that can be mapped.

Adapter Type Location

Process Task

The Integration tab of the Editing Task window

Task Assignment

The Assignment tab of the Editing Task window

Rule Generator

The Map Adapters tab of the Data Object Manager form

Pre-Populate

The Pre-Populate tab of the Form Designer form

Entity

The Map Adapters tab of the Data Object Manager form


The following topics are discussed in this section:

8.19.2.1 From the Variable List Tab

The following table lists the mappings that you can set from the Variable List tab.

Variable Type Map To Qualifier/Resource Type

Object

Adapter References

Database References

   

Data Object References

 

Set at run time (for Task Assignment adapters only)

Database References

   

Data Object References

IT Resource

Resolve at Run time

The IT Resource types that are displayed in the Table view of the IT Resources Type Definition form

String, Character, Byte, Integer, Float, Long, Short, Double

Literal

If you are mapping the adapter variable to a literal, a Literal Value field is displayed below the Resource Type combo box. Within this field, enter the value of this literal.

 

Resolve at Run time

NA

 

Adapter References

Event Handler Name

Note: If the data type of the adapter variable is not String, Adapter References cannot be selected from the Map To combo box.

Boolean

Literal

Boolean. If you select this resource type, two Literal Value options are displayed below the Resource Type combo box: True and False.

Select the option that corresponds to the value of the adapter variable.

 

Resolve at Run time

NA

Date

Literal

If you are mapping the adapter variable to a literal, a Literal Value lookup field is displayed below the Resource Type combo box.

Double-click this lookup field. From the Date & Time window that is displayed, select the date and time that will be the value of this literal.

 

Resolve at Run time

NA

 

System Date

NA

Note: This variable's value will reflect Oracle Identity Manager's date and time. Hence, you do not map it.


8.19.2.2 Process Task Adapter Variable Mappings

The following table lists the process task adapter variable mappings.

Variable Type Map To Qualifier/Description

Object (Adapter Return Variable)

Process Data

You can map the parameter to a field of either the associated custom process form, or a child table that belongs to this form.

 

Response Code

NA

 

Task Information

Note. You can map the parameter to the Note tab of the Task List form.

Reason. You can map the parameter to the Error Details window. To access this window, double-click a task that is displayed within the Task List form.

 

Process Definition

Name. You can map the parameter to the Name field of the Process Definition form.

Type. You can map the parameter to the Type lookup field of the Process Definition form.

Object (Adapter Return Variable)

Organization Definition

The fields of the Organizations form to which you can map the adapter variable.

Note: Because the data type of the adapter variable is Object, you cannot select Organization ID from the Qualifier combo box.

 

User Definition

The fields of the Users form to which you can map the adapter variable.

IT Resource

IT Resource

You can map the parameter to an IT resource. This IT resource is a member of the IT resource type that is displayed in parenthesis from within the Data Type field.

 

Process Data

You can map the parameter to a field of the associated process-specific form.

Note: The only field names that are displayed in this combo box are ones with a data type of IT Resource Lookup Field.

String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, Double

Process Data

You can map the parameter to a field of either the associated custom process form, or a child table that belongs to this form.

 

Task Information

Note. You can map the parameter to the Note tab of the Task List form.

   

Reason. You can map the parameter to the Error Details window. To access this window, double-click a task that is displayed within the Task List form.

 

Process Definition

Name. You can map the parameter to the Name field of the Process Definition form.

   

Type. You can map the parameter to the Type lookup field of the Process Definition form.

 

Organization Definition

The fields of the Organizations form to which you can map the adapter variable.

String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, Double

User Definition

The fields of the Users form to which you can map the adapter variable.

 

Literal

If you are mapping the adapter variable to a literal, and the variable's data type is String, Character, Byte, Integer, Float, Long, Short, or Double, a Literal Value field is displayed below the Qualifier combo box. Within the field, enter the value of this literal.

When you are mapping the adapter variable to a literal, and the variable's data type is Boolean, two Literal Value options are displayed below the Qualifier combo box: True and False. Select the option that corresponds to the value of the adapter variable.

If you are mapping the adapter variable to a literal, and the variable's data type is Date, a Literal Value lookup field is displayed below the Qualifier combo box. Double-click this lookup field. From the Date & Time window that is displayed, select the date and time that will be the value of this literal.

String

IT Resources

If you are mapping the adapter variable to an IT Resource, three combo boxes are displayed below the Map To combo box: Qualifier, IT Asset Type, and IT Asset Property. From these combo boxes, select the qualifier for the mapping, the specific name of the IT resource, and the field of the IT resource that will receive the results of the mapping.

Note: If the data type of the adapter variable is not String, IT Resources cannot be selected from the Map To combo box.


8.19.2.3 Task Assignment Adapter Variable Mappings

The following table lists the task assignment adapter variable mappings.

Variable Type Map To Qualifier/Description

IT Resource

Object Data

You can map the parameter to an IT resource's instance key. This IT resource is a member of the IT resource type that is displayed in parenthesis from within the Data Type field.

 

IT Resource

You can map the parameter to an IT resource.

Object (Adapter Return Value)

Object Data

You can map the parameter to a field of either the associated custom resource object form, or a child table that belongs to this form.

 

Response Code

NA

 

Task Information

The fields of the Task List form to which you can map the adapter variable.

 

Process Definition

The fields of the Process Definition form to which you can map the adapter variable.

 

Organization Definition

The fields of the Organizations form to which you can map the adapter variable.

 

User Definition

The fields of the Users form to which you can map the adapter variable.

String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, Double

Object Data

You can map the parameter to a resource object's instance key.

 

Task Information

The fields of the Task List form to which you can map the adapter variable.

 

Process Definition

The fields of the Process Definition form to which you can map the adapter variable.

 

Organization Definition

The fields of the Organizations form to which you can map the adapter variable.

String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, Double

User Definition

The fields of the Users form to which you can map the adapter variable.

 

Request Info

Request ID. You can map the parameter to the Request ID field of the Requests form.

   

Request Action. You can map the parameter to the Request Action field of the Requests form.

   

Request Priority. You can map the parameter to the Request Priority field of the Requests form.

 

Request Target User

The fields of the Users form to which you can map the adapter variable.

 

Request Target Organization

The fields of the Organizations form to which you can map the adapter variable.

 

Requester Info

The fields of the Users form to which you can map the adapter variable.

 

Literal

If you are mapping the adapter variable to a literal, a Literal Value field is displayed below the Qualifier combo box. Within the field, enter the value of this literal.

Note: If the data type of the adapter variable is Boolean, two options are displayed in place of the field: True and False. Select the option that reflects the value of the adapter variable.

Note: If the data type of the adapter variable is Object, Literal cannot be selected from the Map To combo box.

String

IT Resources

Resource Instance. You can map the parameter to an IT resource's instance key. This IT resource is a member of the IT resource type that is displayed in parenthesis from within the Data Type field.

   

IT Asset Type. You can map the parameter to an IT resource type.

String

IT Resources

IT Asset Property. You can map this parameter to one of the properties that comprise the selected IT resource type.


8.19.2.4 Rule Generator and Entity Adapter Variable Mappings

The following table lists the rule generator and entity adapter variable mappings.

Variable Type Map To Qualifier/Description

Object (Adapter Return Variable), IT Resource, String, Boolean, Character, Byte, Date, Integer, Float, Long, Short

Literal

If you are mapping the adapter variable to a literal, a Literal Value field is displayed below the Qualifier combo box. Within the field, enter the value of this literal.

Note: If the data type of the adapter variable is Object, Literal cannot be selected from the Map To combo box.

 

Entity Field

You can map the adapter variable to a field of the associated process form. The name of this form is displayed in the Form Description field of the Data Object Manager form.

 

Organization Definition

The fields of the Organizations form to which you can map the adapter variable.

Note: If the data type of the adapter variable is not Object, you cannot select Organization ID and Organization Parent ID from the Qualifier combo box.

 

User Definition

The fields of the Users form to which you can map the adapter variable.


8.19.2.5 Prepopulate Adapter Variable Mappings

The following table lists the prepopulate adapter variable mappings.

Variable Type Map To Qualifier/Description

IT Resource

IT Resource

You can map the parameter to an IT resource. This IT resource is a member of the IT resource type that is displayed in parenthesis from within the Data Type field.

 

Process Data

You can map the parameter to a field of the associated process-specific form.

Note: The only field names that are displayed in this combo box are ones with a data type of IT Resource Lookup Field.

Object, String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, Double

Process Data

You can map the parameter to a field of the associated process-specific form.

 

Organization Definition

The fields of the Organizations form to which you can map the adapter variable.

 

User Definition

The fields of the Users form to which you can map the adapter variable.

String, Boolean, Character, Byte, Date, Integer, Float, Long, Short, Double

Literal

If you are mapping the adapter variable to a literal, and the variable's data type is String, Character, Byte, Integer, Float, Long, Short, or Double, a Literal Value field is displayed below the Qualifier combo box. Within the field, enter the value of this literal.

When you are mapping the adapter variable to a literal, and the variable's data type is Boolean, two Literal Value options are displayed below the Qualifier combo box: True and False. Select the option that corresponds to the value of the adapter variable.

If you are mapping the adapter variable to a literal, and the variable's data type is Date, a Literal Value lookup field is displayed below the Qualifier combo box. Double-click this lookup field. From the Date & Time window that is displayed, select the date and time that will be the value of this literal.

String

IT Resources

If you are mapping the adapter variable to an IT Resource, three combo boxes are displayed below the Map To combo box: Qualifier, IT Asset Type, and IT Asset Property. From these combo boxes, select the qualifier for the mapping, the specific name of the IT resource, and the field of the IT resource that will receive the results of the mapping.

Note: If the data type of the adapter variable is not String, then IT Resources cannot be selected from the Map To combo box.


8.20 Defining Error Messages

The Error Message Definition form, as shown in Figure 8-3, is in the Development Tools folder of the Design Console. It is used to:

Note:

If an entity adapter is attached to a process form or an object form for validation of field values, these adapters will run if you edit data in these forms after completing direct or request provisioning.

Oracle Identity Manager 11g Release 2 (11.1.2) does not support creating new entity adapters.

Figure 8-3 Error Message Definition Form

Surrounding text describes Figure 8-3 .

Table 8-14 describes the data fields of the Error Message Definition form.

Table 8-14 Fields of the Error Message Definition Form

Field Name Description

Key

The error message definition's unique, system-generated identification number.

Code

The code that represents the error message definition.

Reset Count

When you click this button, Oracle Identity Manager resets the counter to zero. This counter is the number of times the error message is displayed.

Description

A description of the error message.

Remedy

A description of how to correct the condition that caused the error message to be displayed.

Help URL

The link to the URL that contains an online Help topic for this error message.

Action

A one-letter code, representing the seriousness of the condition that causes the error message to be displayed.

An error message has three levels of seriousness: Error (E), Rejection (R), and Fatal Rejection (F).

Severity

For classification purposes, you can categorize the seriousness of the condition that results in the error message being displayed, even further.

An error message has five sub-levels of severity: None (N), Low (L), Medium (M), High (H), and Crash (C).

Note

Explanatory information about the error message.


When you create an error message, Oracle Identity Manager populates the Key field with a unique identification number. When a condition occurs that causes the error message to be displayed, the text in the Description field is displayed in a dialog box.

Note:

After you create an error message definition, to reset the count of how many times the error message is displayed, click the Reset Count button. This resets the count to zero.

To create an error message:

  1. Open the Error Messaging Definition form.

  2. In the Code field, enter the code that represents the error message definition.

  3. In the Description field, enter a description for the error message.

  4. In the Remedy field, you can enter a description for how to correct the condition that causes the error message to be displayed.

  5. In the Help URL field, you can enter the link to the URL that contains an online Help topic for this error message.

  6. (Optional) Double-click the Action Lookup field.

    From the Lookup dialog box that is displayed, you can select a code that represents the seriousness of the condition that causes the error message to be displayed. These codes, listed by degree of seriousness (from lowest to highest), are:

    • Error (E). Oracle Identity Manager stores the error message, and stops any related operations from being triggered. Instead, the operation rolls back to the previous operation.

    • Reject (R). Oracle Identity Manager stores the rejection message, but it does not prevent subsequent operations from being executed.

    • Fatal Reject (F). Oracle Identity Manager stores the rejection message, and it stops any subsequent operations from being triggered. However, it stores all operations that were executed up to the fatal rejection.

  7. (Optional) Double-click the Severity Lookup field. From the Lookup dialog box that is displayed, you can select a code (None (N), Low (L), Medium (M), High (H), or Crash (C)). This code presents a detailed classification of the code that is displayed in the Action lookup field.

  8. In the Note field, enter explanatory information about the error message.

  9. Click Save.

    The error message is created.

    After creating error messages by using the Error Message Definition form, you must add new error codes and advice messages in the Oracle Identity Manager customResources.properties resource bundle. These localized error codes and advice messages will be displayed in Identity Self Service or Identity System Administration.