5 Extending the Functionality of the Connector

You can extend the functionality of the connector to address your specific business requirements.

This chapter discusses the following optional procedures:

Note:

From Oracle Identity Manager Release 11.1.2 onward, lookup queries are not supported. See Managing Lookups in Oracle Fusion Middleware Administering Oracle Identity Manager guide for information about managing lookups by using the Form Designer in the Oracle Identity Manager System Administration console.

Note:

In this guide, a target system that exposes webservice endpoint has been referred to as the target system. ACME Webservice is used as a sample target system to discuss the configurations and the connector objects.

5.1 Securing the Connector

This section describes the following procedures that enable you to secure the connector:

5.1.1 Handling Passwords

Learn about securing sensitive information.

This section discusses the following topics:

5.1.1.1 Custom Webservice Policy and Guidelines for Passcode

In this connector, the target webservice operations are invoked using SOAP messages, which by default are not encrypted and can be viewed by anyone from the Enterprise Manager or a testing utility. This poses a threat when you have to pass sensitive information like passwords. To secure sensitive information, the following custom webservice policy can be used:

Guidelines for Passcode

  • Sensitive fields are encrypted by Oracle Identity Manager and this encrypted value is sent to the SOA composite.

  • The passcode attribute in the IT Resource of the connector is used as a key for encrypting the value.

  • Passcode should contain alphabets, numbers, and special characters.

  • Passcode should contain both upper case and lower case characters.

  • Passcode should be minimum 8 characters long.

  • Passcode should be changed periodically.

  • Passcode should not resemble any known and obvious keywords.

  • Passcode provided in the SOA composite should match with the value of the passcode parameter in the connector IT Resource.

  • In the SOA composite, the custom outbound policy (oimcp_WS_CONNECTOR_OUTBOUND) that handles password decryption is attached to the target webservice partner link.

  • Passcode fields, password fields, and target namespaces are specified in the composite, which are used by the policy to decrypt the password fields.

  • In the runtime, the policy decrypts a password field using the passcode and replaces it in the target SOAP payload before invoking the target webservice operation.

  • Only the masked passwords are displayed in the Enterprise Manager and payloads.

5.1.1.2 Configuring the Custom Webservice Policy

To configure this custom webservice policy:

  1. Adding the connector outbound policy to the Policy store. To do so:

    1. In the Enterprise Manager console, select the WebLogic domain in the left pane. In the main page, navigate to WebLogic Domain, Web Services, Policies.

      Description of sec_1-1.gif follows
      Description of the illustration sec_1-1.gif

    2. In the Web Service Policies page, click Import From File and browse for the outbound policy.

      The oimcp_WS_CONNECTOR_OUTBOUND policy is available in the ConnectorDefaultDirectory/Webservices-11.1.1.5.0/soa/policy directory. Attach the sample outbound policy in Sample Outbound Policy.

      Description of sec_1-2.gif follows
      Description of the illustration sec_1-2.gif

    3. Click OK to import the policy.

      You can verify if the policy is imported by visiting http://soaserverhost:soaport/wsm-pm/validator and confirm if the imported policy is listed on this page.

      Description of sec_1-3.gif follows
      Description of the illustration sec_1-3.gif

  2. Deploy the custom policy JAR file, Webservices-oim-integration.jar. To do so:

    1. Stop the WebLogic (admin) server.

    2. Copy the ConnectorDefaultDirectory/Webservices-11.1.1.5.0/soa/policy/ Webservices-oim-integration.jar file to the $DOMAIN_HOME/lib directory.

    3. Restart WebLogic server.

    4. Stop the SOA server.

    5. Copy the ConnectorDefaultDirectory/Webservices-11.1.1.5.0/soa/policy/ Webservices-oim-integration.jar file to the $MW_HOME/Oracle_SOA/soa/modules/oracle.soa.ext_11.1.1/ directory.

    6. Set the ANT_HOME environment variable and run the ant command.

    7. Restart the SOA server.

  3. Configure the SOA composite in the composite.xml file. To do so, add the following entries within the <binding.ws> tags of the webservice that requires password decryption.

    <wsp:PolicyReference URI="oimcp/WS_CONNECTOR_OUTBOUND" orawsp:category="security" orawsp:status="enabled"/>
  <property name="passcode" type="xs:string">abcd1234</property>
  <property name="password.field.xpath.locations" type="xs:string">/ns6:ListOfUser/ns6:User/ns6:Password</property>
  <property name="target.payload.namespaces" type="xs:string">ns6=urn:/acme/xml/password</property>

    In these entries:

    • passcode is the passcode field of the connector IT Resource

      See "Guidelines for Passcode" listed earlier.

    • password.field.xpath.locations is the comma separated list of XPath locations that contain the encrypted password fields

    • target.payload.namespaces is the comma separated list of target namespaces corresponding to the values of password.field.xpath.locations

    Note:

    • The property tags follow the PolicyReference tags in the composite.xml file. Ensure this structure when you configure other security policies for the same webservice.

    • Ensure that the namespace in the target.payload.namespace property does not include quotation marks.

  4. Deploy the SOA composite in JDeveloper and test the password reset operation from Oracle Identity Manager. See Deploying and Testing the Webservice SOA Composite for more information.

5.1.2 Configuring Webservice Security Policy

You can configure webservice security policy in the SOA composite in JDeveloper. To do so:

Note:

See Sample WSDL for Security Policy for SecurityPolicy.wsdl.

  1. Right-click the target webservice and click Configure WS Policies.
  2. In the Configure SOA WS Policies window, click the plus sign next to the Security field.
  3. In the Select Client Security Policies window, select the webservice security policy you want to add for authentication and click OK.
  4. Click OK.
  5. In the Component Palette, click the plus sign below the Binding Properties to specify the binding properties as required.
  6. After the SOA composite is ready, you can build and deploy it in JDeveloper. See Deploying and Testing the Webservice SOA Composite for more information.

5.1.3 Passing Credentials Using CSF

You can pass target system credentials from the SOA composite using the Credential Store Factory (CSF) mechanism. The procedure is as follows:

  1. Create a key for the target system credentials in CSF. To do so:

    1. In the Enterprise Manager console, select the WebLogic domain in the left pane. In the main page, navigate to WebLogic Domain, Security, Credentials.

      Description of sec_3-1.gif follows
      Description of the illustration sec_3-1.gif

    2. Click Create Key and add the credential details.

      Description of sec_3-2.gif follows
      Description of the illustration sec_3-2.gif

    3. Click OK and save the key.

  2. Configure the SOA composite in the composite.xml file. To do so:

    1. Right-click the target webservice and click Configure WS Policies.

    2. In the Configure SOA WS Policies window, select the security policy under Security and click the pencil sign to edit.

      Description of sec_3-3.gif follows
      Description of the illustration sec_3-3.gif

    3. In the Override Value column, enter the name of the CSF key that was created in the previous step and click OK.

      Description of sec_3-4.gif follows
      Description of the illustration sec_3-4.gif

    Alternatively, you can add the binding properties in the composite.xml file directly in text mode:

    <binding.ws port="urn:acme/ws/user/#wsdl.endpoint(User/Default)" location="userWrapper.wsdl" soapVersion="1.1">
<wsp:PolicyReference URI="oracle/wss_username_token_client_policy" orawsp:category="security" orawsp:status="enabled"/>
<property name="csf-key" type="xs:string" many="false">acme-csf-key</property>
</binding.ws>

5.1.4 Passing Credentials Using Custom Headers

Apart from the webservice security policy authentication mechanisms, the webservices may be authenticated using custom SOAP headers. This mechanism would be useful for the target webservices whose format do not comply with webservice security policy.

To pass the credentials using custom headers:

  1. Define the schema of the elements used in the custom headers in an XSD file. Copy the file to the xsd folder in the SOA composite project in JDeveloper.
  2. Create variables for the headers. In the BPEL process, click the variable icon (x) and add a variable.
  3. Select the variable type from the custom header's XSD in the Type Chooser window.
  4. Assign values to the headers in the Assign activity.
  5. Edit the Invoke operation.
  6. Click the Header tab and select the variables that you created. This will add the selected variables in the SOAP header when the operation is invoked.
  7. Click Apply and OK.
  8. After the SOA composite is ready, you can build and deploy it. See Deploying and Testing the Webservice SOA Composite for more information.

    The configured variables will be a part of the SOAP headers when the target webservice operation is invoked.

5.1.5 Importing SSL Certificate for HTTPS-based Target Webservice

You can perform this procedure only if the target system exposes the webservice over SSL. To import the SSL certificate:

  1. Download the SSL certificate from the target system's website that is exposing the webservice.
  2. Log in to the Oracle WebLogic Server administration console.
  3. Under Domain Structure, expand Environment (by clicking the + next to it). Then click Servers.
  4. Click the SOA managed Server name. For example, soa_server1.
  5. Switch to the Keystores tab.

    This page lists the various keystores that are associated with the server.

  6. Import the SSL certificate into all the keystores that are listed on this page using keytool, the key and certificate management utility.

    For example, to import the certificate into the Demo Trust Keystore, run the following command from the computer hosting the server:

    keytool -keystore <MW_HOME>/server/server/lib/DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase -import -file acme-cert.cer

    Similarly, import the certificate to the other keystores that are listed.

  7. Restart Oracle WebLogic Server and SOA server.

5.2 Adding Custom Attributes for Provisioning

Note:

In this section, the term "attribute" refers to the identity data fields that store user data.

To add a custom attribute, you must ensure that the corresponding attribute exists on the target system. If it does not exist, then you must first add the custom attribute on the target system. Contact an administrator for information about adding a custom attribute on the target system.

You can add custom attributes for provisioning by configuring in Oracle Identity Manager and in the SOA Composite. These procedures are described in the following sections:

5.2.1 Adding Custom Attributes for Provisioning in Oracle Identity Manager

By default, the attributes listed in Connector Objects Used During Provisioning are mapped for provisioning b etween Oracle Identity Manager and the target system. If required, you can also configure the connector for provisioning after adding custom attributes or other user attributes that are not available out of the box (OOTB) with the connector.For example, if CountryName is a custom attribute added to the user profile on the target system, then you can configure the connector to provision this attribute by performing the following steps:

  1. For the custom attribute, CountryName, determine the corresponding attribute name in ACME WSDL.

  2. Log in to the Oracle Identity Manager Design Console.

    If you are using Oracle Identity Manager release 11.1.2.x, then log in to Oracle Identity System Administration and perform the steps described in http://docs.oracle.com/cd/E27559_01/admin.1112/e27149/form.htm#CACGHJIF.

  3. Create a new version of the process form as follows:

    1. Expand Development Tools.

    2. Double-click Form Designer.

    3. Search for and open the UD_ACME_USR process form.

    4. Click Create New Version.

      On the Create a new version dialog box, enter a new version in the Label field, and then click Save.

  4. Add the new field on the process form as follows:

    1. Click Add.

      A field is added to the list. Enter the details of the field.

      For example, if you are adding the CountryName field, enter UD_ACME_USR_COUNTRYNAME in the Name field, CountryName in the Label Name field, and the remaining details of this field.

      If the field is a LookupField type, create a new lookup definition, for example, Lookup.ACME.CountryName. Then, add appropriate entries to the lookup definition.

      Open the UD_ACME_USR process form and click Properties. Select the newly added property and click Add Property. Select Property Name as Lookup Code, and then enter the newly created lookup, Lookup.ACME.CountryName as the property value.

    2. Click Save.

    3. To activate the newly created form, click Make Version Active.

  5. Create an entry for the field in the lookup definition for provisioning as follows:

    1. Expand Administration.

    2. Double-click Lookup Definition.

    3. Search for and open the Lookup.ACME.UM.ProvAttrMap lookup definition.

    4. Click Add and enter the Code Key and Decode values for the field.

      The Code Key value must be the form field label name. The Decode value can be same as the Code Key value, as the mapping is done in the SOA composite.

      For example, enter CountryName in the Code Key and the Decode fields. After this attribute is added in the Provisioning Attribute Map and in the process form, the attribute will appear in the Oracle Identity Manager App Instance form and the input values can be provided from Oracle Identity Manager.

    5. Click Save.

  6. If you are using Oracle Identity Manager release 11.1.2.x or later, create a new UI form and attach it to the application instance to make this new attribute visible. See Creating a New UI Form and Updating an Existing Application Instance with a New Form for the procedures.

5.2.2 Adding Custom Attributes for Provisioning in SOA Composite

You can add custom attributes in the SOA composite for an operation such as Create. The custom attribute will be passed in the <otherAttributes> tag in the payload. The custom attribute can be the Decode value CountryName from the Lookup.ACME.UM.ProvAttrMap lookup definition. To do so:

  1. In the Assign activity, expand otherAttributes under userAccount and map the value to the target attribute.
  2. Edit the From XPath field and add [name = 'CountryName'] before /value.
  3. Save the assignment.

    The blue assignment line shifts to userAccount in the From region.

  4. Save the project.

    You can compile and deploy the project. Test the operation from the Enterprise Manager. See Deploying and Testing the Webservice SOA Composite for more information.

5.2.3 Adding Custom Attribute for Update Operation

To add a custom attribute for update operation. To do so:

Note:

Ensure that the field has been added to the Oracle Identity Manager process form and the entry has been added in Lookup.ACME.UM.ProvAttrMap so that create operation is working.

  1. In the Design Console, add the FIELD_NAME Updated process task.

    For example, if the custom field is Location, add the Location Updated task.

  2. Add the adpACMEUPDATEATTRIBUTEVALUE adapter and complete the integration similar to an existing task such as FirstName Updated.
  3. In the SOA composite, map the name under udpatedAttribute to the if construct and the value to the target variable.
  4. Switch to source. The following is a sample source: 
    <xsl:if test="/types:update/updatedAttribute/name">
  <firstName>
    <xsl:value-of select="/types:update/updatedAttribute/value"/>
  </firstName>
</xsl:if>
  5. Verify the Decode value for the connector field in the Lookup.ACME.UM.ProvAttrMap lookup definition.

    For the example attribute name first name, the Decode value is FirstName.

  6. Modify the source as follows: 
    <xsl:if test='/types:update/updatedAttribute/name = "FirstName"'>
  <firstName>
    <xsl:value-of select="/types:update/updatedAttribute/updatedAttribute[name = 'FirstName']/value"/>
  </firstName>
</xsl:if>
  7. Save the project.

    You can compile and deploy the project. Test the operation from the Enterprise Manager. See Deploying and Testing the Webservice SOA Composite for more information.

5.3 Adding Custom Attributes for Reconciliation

You can add custom attributes for reconciliation by configuring in Oracle Identity Manager and in the SOA Composite. These procedures are described in the following sections:

5.3.1 Adding Custom Attributes for Reconciliation in Oracle Identity Manager

To add a custom attribute such as Country Name in Oracle Identity Manager:

Note:

If you have already added an attribute for provisioning, then you need not repeat steps performed as part of that procedure.

  1. In the Design Console, search for and open the Lookup.ACME.UM.ReconAttrMap lookup definition.
  2. Add a new entry for the custom attribute.
  3. Add the custom field to the list of reconciliation fields in the resource object. Then, click Create Reconciliation Profile.
  4. Add the custom field on the process form.
  5. Create a reconciliation field mapping for the custom field in the provisioning process.

5.3.2 Adding Custom Attributes for Reconciliation in SOA Composite

You can add custom attributes in the SOA composite for an operation such as Search. The custom attribute will be passed in the <otherAttributes> tag in the payload, as shown in SearchOutputTransform.xsl.

Description of cust5.gif follows
Description of the illustration cust5.gif

To perform this procedure:

  1. Map the custom attribute to the value field under otherAttributes.
  2. The name field under otherAttributes has to be set with the Decode value of the attribute in Lookup.ACME.UM.ReconAttrMap lookup.

    Right-click name and click Set Text, then Enter Text.

    Description of cust7.gif follows
    Description of the illustration cust7.gif
  3. Enter the decode value of the custom attribute as defined in the lookup definition.
  4. Switch to the Source tab to view the XSL transform code for the otherAttributes.

    You can add as many otherAttribute tags as needed. By adding more tags, the Design view may throw errors that can be ignored. As long as the XSLT syntax is correct, the project can be deployed and tested.

    Description of cust9.gif follows
    Description of the illustration cust9.gif

5.3.3 Adding Custom Attributes for Reconciling _UID_ Field

Note:

Perform the procedure described in this section only when the name and Uid fields in your target system do not store the same values.

Customizing the Uid field includes configuring the otherAttributes attribute in the composite and then assigning it to the Unique Id field in the Lookup.ACME.UM.ReconAttrMap lookup definition.

To do so, perform the following steps in the Transform after UserInvokeSearch:

  1. Open the search branch transform and map the Uid field to the otherAttributes attribute as follows:

    1. Search for and expand the otherAttributes attribute and right-click the Name attribute.

    2. In the context menu that is displayed, select Set Text, and then select Enter Text.

      Description of map_otherattr.gif follows
      Description of the illustration map_otherattr.gif

    3. In the Set Text dialog box, select Text, enter uid in the text field, and click OK.

      Description of uid_ok.gif follows
      Description of the illustration uid_ok.gif

    4. In the UserSearchTransform tab, map the target Uid field to the attribute value in otherAttributes.

      Description of trget_uid_field.gif follows
      Description of the illustration trget_uid_field.gif

  2. Save, compile, and deploy the composite to the SOA server.

  3. Test the Search operation from Enterprise Manager and observe the response payload.

    Login is populated in the login field and Uid is set as uid in the otherAttributes attribute.

    Description of em_payload.gif follows
    Description of the illustration em_payload.gif

  4. Update the Lookup.ACME.UM.ReconAttrMap lookup definition as follows:

    1. Log in to the Design Console.

    2. Expand Administration and then double-click Lookup Definition.

    3. Search for and open the Lookup.ACME.UM.ReconAttrMap lookup definition.

    4. Search for and update the decode value of Unique Id code key to uid.

      Description of unique_id_reconmappi.gif follows
      Description of the illustration unique_id_reconmappi.gif

    5. Click Save.

  5. Run the Target User Reconciliation scheduled job. See Scheduled Tasks for Reconciliation for more information about this scheduled job.

    After the reconciliation run is successful, the unique ID value is mapped to the custom attribute. You can view this mapping in the Event Management region by opening the latest event ID.

    Description of recon_event.gif follows
    Description of the illustration recon_event.gif

5.4 Adding Custom Child Forms

You can add custom child forms by configuring in Oracle Identity Manager and in the SOA Composite. These procedures are described in the following sections:

5.4.1 Adding Custom Child Forms in Oracle Identity Manager

To add a custom child form for a field such as Mailing List in Oracle Identity Manager:

  1. In the Form Designer, create the child form for the Mailing List field.
  2. Create a new version of the parent form and add the new child form to it. Then, make the new version of the parent form active.
  3. Add process tasks for Mailing List Insert, Mailing List Update, and Mailing List Delete. These process tasks will be similar to the child form Insert, Update, and Delete tasks.
  4. Add an entry in the Lookup.ACME.UM.ProvAttrMap lookup definition.

    Code Key: CHILD_TABLE~FIELD_LABEL

    Decode: RELEVANT_STRING_VALUE

    For example, Code Key value is UD_ACME_CH2~Mailing List and Decode value is MailingList.

    Note:

    For complex child tables, the decode value is AttributeName~ObjectClass~TargetFieldName

    You must provide values for the AttributeName and ObjectClass attributes as mentioned under ComplexMultiAttributes in the SOA composite.

    Description of ch_form3.gif follows
    Description of the illustration ch_form3.gif

5.4.2 Adding Custom Child Forms in SOA Composite

In the ACME webservice, there are different operations for different multivalued attributes (child form attributes), such as AddRole and AddMailingList operations.

To add a custom child form for a field such as Mailing List in the SOA composite:

  1. Drop a Switch activity to UpdateAddAttributeValues OnMessage. Uncomment it in the source view if it was previously commented.
  2. Double-click the condition box to open the Edit Switch Case window. Provide the name as Role and click the XPath Expression Builder icon above the Expression region.
  3. Select contains from String functions and click Insert Into Expression.
  4. Set the first argument as attributeName under UpdateAddAttributeValuesOp_InputVariable.
  5. Set second argument as Role and set the label as Role.

    The second argument value is the same as the Decode value of the first child table entry in the Lookup.ACME.UM.ProvAttrMap lookup.

    Description of child_form7.gif follows
    Description of the illustration child_form7.gif
  6. Drop an Invoke activity for calling the AddRole operation in the Role branch. Then, drop another Invoke activity for calling the AddMailingList operation in the otherwise branch.

    Specify the input and output variables.

    Description of child_form8.gif follows
    Description of the illustration child_form8.gif
  7. Add Assignment activities before the Invoke activities and map the attributes to the target operation attributes. Then, map the UID to the output variable of the Reply activity.
    Description of child_form9.gif follows
    Description of the illustration child_form9.gif

    The following is a sample screenshot of the configured SOA composite:

    Description of child_form10.gif follows
    Description of the illustration child_form10.gif

5.5 Adding Child Form Data

The UpdateAddAttributeValues and UdpateRemoveAttributeValues operations are used for adding and removing child form data such as Roles (multivalued data or entitlements) respectively.

The mappings for UpdateAddAttributeValues are as follows. The mappings for UdpateRemoveAttributeValues are similar.

  1. Depending on the target webservice, you may have to create a new partner link if the target exposes Role operations in a separate webservice.
  2. Drop an Invoke activity to the target operation such as AddRole. Then, specify the input and output variables.
  3. Drop an Assign activity before the InvokeRoleAd activity.
  4. In the Assign activity, map the variables in the UpdateAddAttributeValueOp_InputVariable to the input variable of the Invoke activity for Role.

    In the case of ACME web service, the first argument is the UID and the second argument is the attribute name, Role (for multiple child tables, this value would change). The third argument is the attribute value, which is the actual role name such as Administrator.

    Description of child_data3.gif follows
    Description of the illustration child_data3.gif
  5. Drop an Assign activity between the Invoke and the AddAttrValReply activities. Then, map the output of the Invoke activity (which is the UID) to the Response variable.
    Description of child_data4.gif follows
    Description of the illustration child_data4.gif

    If the target web service does not return the UID on role addition, then this assignment can be done between the UID passed in the input call to the UdpateAddAttributeValues operation and the response variable.

    You can follow similar steps to configure the RemoveRole operation using the UdpateRemoveAttributeValues operation.

5.6 Mapping Timestamp Attribute

The timestamp attribute in the connector is of long type. The attribute on some target webservices may be of a different type or format. For example, in Oracle CRM On Demand, if you want to use the modified date as the incremental reconciliation attribute, then you need to convert the attribute type to long.

See Also:

Table 4-2 for the usage of the timestamps in the scheduled task attributes

Initially, timestamp is a string in MM/dd/yyyy format. You can write a Java code to convert the string into java.sql.Timestamp format and then, use the getTime() method to derive the value of long type.

This Java code can be used to define a custom XPath function that can be used directly in the SOA composite, which takes the modified date as input and produces the long value as output. Then, this output can be mapped to the timestamp attribute.

Perform the procedure described in Creating User-Defined XPath Extension Functions in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite to create a custom (user-defined) XPath extension function.

The following is a sample Java code to define a custom XPath function to convert DateString to Long type:

package org.webservices.conversion;
 
import java.text.SimpleDateFormat;
 
import java.util.Date;
import java.util.List;
 
import oracle.fabric.common.xml.xpath.IXPathContext;
import oracle.fabric.common.xml.xpath.IXPathFunction;
 
public class ConvertDateStringToLong implements IXPathFunction {
  public ConvertDateStringToLong() {
    super();
  }
 
  public static Long convertDateStringToLong(String dateString) {
 
    Date date = null;
 
    SimpleDateFormat dateFormat = new SimpleDateFormat("MM/dd/yyyy HH:mm:ss");
 
    try {
 
      date = dateFormat.parse(dateString);
 
    } catch (Exception e) {
      e.printStackTrace();
    }
 
    long timeInLong = date.getTime();
 
    return timeInLong;
  }
 
  public Object call(IXPathContext ixPathContext, List<?> list) {
    return convertDateStringToLong((String)list.get(0));
  }
}

5.7 Configuring the Connector for Multiple Instances and Multiple Versions of the Target System

Note:

Perform this procedure only if you want to configure the connector for multiple installations of the target system.

You may want to configure the connector for multiple installations of the target system. The following example illustrates this requirement:

The Tokyo, London, and New York offices of Example Multinational Inc. have their own installations of the target system. The company has recently installed Oracle Identity Manager, and they want to configure Oracle Identity Manager to link all the installations of the target system.

To meet the requirement posed by such a scenario, you must configure the connector for multiple installations of the target system.

To configure the connector for multiple installations of the target system:

See Also:

Cloning Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager for Oracle Identity Manager for detailed instructions on performing each step of this procedure

  1. Create and configure one IT resource for each target system installation.

    The IT Resources form is in the Resource Management folder. An IT resource is created when you import the connector XML file. You can use this IT resource as the template for creating the remaining IT resources, of the same resource type.

  2. Configure reconciliation for each target system installation. See Scheduled Tasks for instructions. Note that you only need to modify the attributes that are used to specify the IT resource and to specify whether or not the target system installation is to be set up as a trusted source.
  3. If required, modify the fields to be reconciled for the ACME Webservice User resource object.

When you use the Administrative and User Console to perform provisioning, you can specify the IT resource corresponding to the target system installation to which you want to provision the user.

5.8 Configuring Validation of Data During Reconciliation and Provisioning

The Lookup.ACME.UM.ProvValidations and Lookup.ACME.UM.ReconValidations lookup definitions hold single-valued data to be validated during provisioning and reconciliation operations, respectively.

For example, you can validate data fetched from the First Name attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the First Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations.

Note:

The Lookup.ACME.UM.ProvValidations and Lookup.ACME.UM.ReconValidations lookup definitions are optional and do not exist by default.

You must add these lookups as decode values to the Lookup.ACME.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations.

To configure validation of data:

  1. Write code that implements the required validation logic in a Java class with a fully qualified domain name (FQDN), such as org.identityconnectors.acme.extension.ACMEValidator.

    This validation class must implement the validate method. The following sample validation class checks if the value in the First Name attribute contains the number sign (#):

    package com.validationexample;

import java.util.HashMap;
 
public class MyValidator {
    public boolean validate(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) throws ConnectorException {
 
        /* You must write code to validate attributes. Parent
                 * data values can be fetched by using hmUserDetails.get(field)
                 * For child data values, loop through the
                 * ArrayList/Vector fetched by hmEntitlementDetails.get("Child Table")
                 * Depending on the outcome of the validation operation,
                 * the code must return true or false.
                 */
        /*
        * In this sample code, the value "false" is returned if the field
        * contains the number sign (#). Otherwise, the value "true" is
        * returned.
        */
        boolean valid = true;
        String sFirstName = (String) hmUserDetails.get(sField);
        for (int i = 0; i < sFirstName.length(); i++) {
            if (sFirstName.charAt(i) == '#') {
                valid = false;
                break;
            }
        }
        return valid;
 
    }
}
  2. Log in to the Design Console.
  3. Create one of the following new lookup definitions:

    • To configure validation of data for reconciliation:

      Lookup.ACME.UM.ReconValidations

    • To configure validation of data for provisioning:

      Lookup.ACME.UM.ProvValidations

  4. In the Code Key column, enter the resource object field name that you want to validate. For example, Alias.
  5. In the Decode column, enter the class name. For example, org.identityconnectors.acme.extension.ACMEValidator.
  6. Save the changes to the lookup definition.
  7. Search for and open the Lookup.ACME.UM.Configuration lookup definition.
  8. In the Code Key column, enter one of the following entries:

    • To configure validation of data for reconciliation:

      Recon Validation Lookup

    • To configure validation of data for provisioning:

      Provisioning Validation Lookup

  9. In the Decode column, enter one of the following entries:

    • To configure validation of data for reconciliation:

      Lookup.ACME.UM.ReconValidations

    • To configure validation of data for provisioning:

      Lookup.ACME.UM.ProvValidations

  10. Save the changes to the lookup definition.
  11. Create a JAR with the class and upload it to the Oracle Identity Manager database as follows:

    Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Select 1 as the value of the JAR type.

  12. Run the PurgeCache utility to clear content related to request datasets from the server cache.
  13. Perform reconciliation or provisioning to verify validation for the field, for example, Alias.

5.9 Configuring Transformation of Data During User Reconciliation

The Lookup.ACME.UM.ReconTransformations lookup definition holds single-valued user data to be transformed during reconciliation operations. For example, you can use First Name and Last Name values to create a value for the Full Name field in Oracle Identity Manager.

Note:

The Lookup.ACME.UM.ReconTransformations lookup definition is optional and does not exist by default.

You must add this lookup as decode value to the Lookup.ACME.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations.

To configure transformation of single-valued user data fetched during reconciliation:

  1. Write code that implements the required transformation logic in a Java class with a fully qualified domain name (FQDN), such as org.identityconnectors.acme.extension.ACMETransformation.

    This transformation class must implement the transform method. The following sample transformation class creates a value for the Full Name attribute by using values fetched from the First Name and Last Name attributes of the target system:

    package com.transformationexample;

import java.util.HashMap;
 
 
public class MyTransformer {
    public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) throws ConnectorException {
        /*
        * You must write code to transform the attributes.
        * Parent data attribute values can be fetched by
        * using hmUserDetails.get("Field Name").
        * To fetch child data values, loop through the
        * ArrayList/Vector fetched by hmEntitlementDetails.get("Child          Table")
        * Return the transformed attribute.
        */
        String sFirstName = (String) hmUserDetails.get("First Name");
        String sLastName = (String) hmUserDetails.get("Last Name");
        return sFirstName + "." + sLastName;
 
    }
}
  2. Log in to the Design Console.
  3. Create a new lookup definition, Lookup.ACME.UM.ReconTransformations.
  4. In the Code Key column, enter the resource object field name you want to transform. For example, Alias.
  5. In the Decode column, enter the class name. For example, org.identityconnectors.acme.extension.ACMETransformation.
  6. Save the changes to the lookup definition.
  7. Search for and open the Lookup.ACME.UM.Configuration lookup definition.
  8. In the Code Key column, enter Recon Transformation Lookup.
  9. In the Decode column, enter Lookup.ACME.UM.ReconTransformations.
  10. Save the changes to the lookup definition.
  11. Create a JAR with the class and upload it to the Oracle Identity Manager database as follows:

    Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Select 1 as the value of the JAR type.

  12. Run the PurgeCache utility to clear content related to request datasets from the server cache.
  13. Perform reconciliation to verify transformation of the field, for example, Alias.

5.10 Configuring Resource Exclusion Lists

The Lookup.ACME.UM.ProvExclusionList and Lookup.ACME.UM.ReconExclusionList lookup definitions hold user IDs of target system accounts for which you do not want to perform provisioning and reconciliation operations, respectively.

Note:

The Lookup.ACME.UM.ProvExclusionList and Lookup.ACME.UM.ReconExclusionList lookup definitions are optional and do not exist by default.

You must add these lookups as decode values to the Lookup.ACME.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations.

The following is the format of the values stored in these lookups:

Code Key Decode Sample Values

User Login Id resource object field name

User ID of a user

Code Key: User Login Id

Decode: User001

User Login Id resource object field name with the [PATTERN] suffix

A regular expression supported by the representation in the java.util.regex.Pattern class

Code Key: User Login Id[PATTERN]

To exclude users matching any of the user ID 's User001, User002, User088, then:

Decode: User001|User002|User088

To exclude users whose user ID 's start with 00012, then:

Decode: 00012*

See Also: For information about the supported patterns, visit http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html

To add entries in the lookup for exclusions during provisioning operations:

  1. On the Design Console, expand Administration and then double-click Lookup Definition.
  2. Create a new lookup definition, Lookup.ACME.UM.ProvExclusionList.

    Note:

    To specify user IDs to be excluded during reconciliation operations, create a new lookup definition called Lookup.ACME.UM.ReconExclusionList and add entries to that lookup.

  3. Click Add.
  4. In the Code Key and Decode columns, enter the first user ID to exclude.

    Note:

    The Code Key represents the resource object field name on which the exclusion list is applied during provisioning operations.

  5. Repeat Steps 3 and 4 for the remaining user IDs to exclude.

    For example, if you do not want to provision users with user IDs User001, User002, and User088 then you must populate the lookup definition with the following values:

    Code Key Decode

    User Login Id

    User001

    User Login Id

    User002

    User Login Id

    User088

    You can also perform pattern matching to exclude user accounts. You can specify regular expressions supported by the representation in the java.util.regex.Pattern class.

    See Also:

    For information about the supported patterns, visit http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html

    For example, if you do not want to provision users matching any of the user IDs User001, User002, and User088, then you must populate the lookup definition with the following values:

    Code Key Decode

    User Login Id[PATTERN]

    User001|User002|User088

    If you do not want to provision users whose user IDs start with 00012, then you must populate the lookup definition with the following values:

    Code Key Decode

    User Login Id[PATTERN]

    00012*
  6. Click Save.

5.11 Reconciliation of Complex Child Forms With Multiple Attributes

Learn how to configure reconciliation of complex child forms with multiple attributes.

This section discusses the following topic:

5.11.1 Mapping Child Tables with Attributes

After performing the configuration procedure described in Configuring the Search Operation, you can map a child table with more than one attribute as follows:

  1. Open and expand the transformation mappings created for the Search operation.

    Note:

    The complexMultiAttributes will be used to manage each complex child table in the transformation mappings that were created.

    Description of comchildform1.jpg follows
    Description of the illustration comchildform1.jpg

  2. Create required mappings for the User fields, after which you must map the complex child attribute. To do so, perform the following procedure:

    1. Add a "for each" loop to repeat the procedure through the child table values.

      For example, in this case, you have to repeat the procedure continuously for each "Role" attribute of the User. Each attributeValue will represent a Role and the procedure is repeated continuously through each "Role" using the "for each" loop.

      Description of comchildform2.jpg follows
      Description of the illustration comchildform2.jpg

    2. Add a "for each" loop to repeat the procedure through the values of each child table entry, and map it to the name and values in the complexAttributeValues.

      For example, in this case, you have to repeat the procedure continuously through roleName, roleStartDate, roleEndDate, and primary for each "Role" attribute. Each of the attributes of Role will be represented as a name-value pair.

      As an example, the name variable will have "RoleName" and the value variable will have "Developer". Similarly all the other attributes of Role such as RoleStartDate, RoleEndDate, and primary will also be represented by name-value pairs.

      Description of comchildform4.jpg follows
      Description of the illustration comchildform4.jpg

    The repetition of each attribute in the child table is done using the following code, which is present inside the "for-loop" to repeat the procedure through each "Role" attribute:

                 <xsl:for-each select="node()">
               <xsl:if test='(name() = "roleName") or ((name() = "roleStartDate") or ((name() = "roleEndDate") or (name() = "primary")))'>
                  <complexAttributeValues>
                    <name>
                      <xsl:value-of select="name()"/>
                    </name>
                    <value>
                      <xsl:value-of select="node()"/>
                    </value>
                  </complexAttributeValues>
                </xsl:if>
              </xsl:for-each>

5.11.2 Configuring Reconciliation of Complex Child Tables

After completing the above procedure, you are required to perform the following steps in Oracle Identity Manager:

  1. Log in to the Design Console.

  2. Create a new child table with more than one attribute as follows:

    1. Create a new child table by following the procedure specified in Adding Custom Child Forms in Oracle Identity Manager.

    2. Add all the attributes of the child table to the additional columns.

      For example, if you have created a child table for Role, you have to add the following attributes to the newly created child table:

      - RoleName

      - RoleStartDate

      - RoleEndDate

      - Primary

      Description of comchildform5.jpg follows
      Description of the illustration comchildform5.jpg

    3. In the Properties tab, click Add Property and add the required properties of the attributes as shown below:

      Description of comchildform6.jpg follows
      Description of the illustration comchildform6.jpg

    4. Click Save, and then click Make Version Active.

    5. Create a new version of the parent form and add the new child form to it. Once this is complete, make the new version of the parent form active by clicking Make Version Active.

  3. Add the new attribute to the list of reconciliation fields in the resource object as follows:

    1. Expand Resource Management, and double-click Resource Objects.

    2. Search for and open the SampleWS User resource object as per the example used in this procedure.

    3. On the Object Reconciliation tab, click Add Field.

    4. Enter the details of the field.

      For example, enter Role in the Field Name field and select Multi-Valued Attribute from the Field Type list.

      Description of comchildform7.jpg follows
      Description of the illustration comchildform7.jpg

    5. Click Save and close the dialog box.

    6. Right-click the newly created field and select Define Property Fields.

    7. In the Add Reconciliation Fields dialog box, enter the details of the newly created field.

      For example, enter RoleName in the Field Name field and select String from the Field Type list.

    8. Repeat step g for all the attributes of the child table with the following difference:

      • Enter RoleStartDate in the Field Name field and select String from the Field Type list.

      • Enter RoleEndDate in the Field Name field and select String from the Field Type list.

      • Enter Primary in the Field Name field and select String from the Field Type list.

      Click Save and close the dialog box repeatedly after you enter the details for each new attribute.

      Description of comchildform8.jpg follows
      Description of the illustration comchildform8.jpg

  4. Create a reconciliation field mapping for the new attribute in the process definition as follows:

    1. Expand Process Management, and double-click Process Definition.

    2. Search for and open SampleWS User process definition as per the example used in this procedure.

    3. On the Reconciliation Field Mappings tab of the process definition form, click Add Field Map.

    4. In the Add Reconciliation Table Mapping dialog box, select the field name and table name from the list displayed.

    5. Click Save and close the dialog box.

      The following screenshot displays the addition of field name Role to SampleWS User reconciliation mappings:

      Description of comchildform9.jpg follows
      Description of the illustration comchildform9.jpg

    6. Right-click the newly created field, and select Define Property Field Map.

    7. In the Field Name field, select the value for the field that you want to add.

      The following screenshot displays the addition of RoleName field of the child table Role:

      Description of comchildform10.jpg follows
      Description of the illustration comchildform10.jpg

    8. Repeat steps f and g for fields RoleStartDate, RoleEndDate, and Primary.

  5. Create an entry for the field in the lookup definition for reconciliation as follows:

    1. Expand Administration.

    2. Double-click Lookup Definition.

    3. Click Add and enter the Code Key and Decode values for the field. The Code Key and Decode values must be in the following format:

      Code Key: MULTIVALUED_FIELD_NAME~CHILD_RESOURCE_OBJECT_FIELD_NAME

      Decode: AttributeName~ObjectClass~TargetFieldName

      Note:

      Provide the values for AttributeName and ObjectClass as specified in AttributeName and ObjectClass under ComplexMultiAttributes in the SOA composite.

    4. Click Save.

    5. Repeat steps c and d for all the attributes of the child table.

      The below screenshot displays the Reconciliation Attribute Map of SampleWS User on completion of all the mappings:

      Description of comchildform11.jpg follows
      Description of the illustration comchildform11.jpg