4 Extending the Functionality of the SAP SuccessFactors Connector

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

The following topics are discussed in this section:

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 for information about managing lookups by using the Form Designer in the Oracle Identity Manager System Administration console.

4.1 Adding New User Attributes for Reconciliation

The connector provides a default set of attribute mappings for reconciliation between Oracle Identity Manager and the target system. If required, you can add new user attributes for reconciliation.

The default attribute mappings for reconciliation are listed in Table 1-24 and Table 1-28.

Note:

Only single-valued attributes can be mapped for reconciliation.

The following topics discuss the procedure to add new attributes for users:

4.1.1 Adding New Attributes on the Process Form

To add a new attribute on the process form:

  1. Log in to the Oracle Identity Manager Design Console.
  2. Expand Development Tools, and double-click Form Designer.
  3. Search for and open the UD_SFSF_USR process form.
  4. Click Create New Version, and then click Add.
  5. Enter the details of the field.

    For example, if you are adding the LASTNAME field, enter UD_SFSF_USR_LASTNAME in the Name field and then enter other details such as Variable Type, Length, Field Label, and Field Type.

  6. Click the Save icon, and then click Make Version Active.
    The following screenshot shows the new field added to the process form.

    Figure 4-1 New Field Added to the Process Form

    Description of Figure 4-1 follows
    Description of "Figure 4-1 New Field Added to the Process Form"

4.1.2 Adding Attributes to the Resource Object

You can add the new attribute to the resource object in the Resource Objects section of Oracle Identity Manager Design Console.

To add the new attribute to the list of reconciliation fields in the resource object:
  1. Expand Resource Management, and double-click Resource Objects.
  2. Search for and open the SuccessFactors User process form.
  3. On the Object Reconciliation tab, click Add Field.
  4. Enter the details of the field.
    For example, enter LASTNAME in the Field Name field and select String from the Field Type list. Later in this procedure, you enter the field name as the Code value of the entry that you create in the lookup definition for reconciliation.
  5. Click the Save icon.
    The following screenshot shows the new reconciliation field added to the resource object:

    Figure 4-2 New Reconciliation Field Added to the Resource Object

    Description of Figure 4-2 follows
    Description of "Figure 4-2 New Reconciliation Field Added to the Resource Object"
  6. Click Create Reconciliation Profile.

4.1.3 Creating Reconciliation Field Mapping

You create a reconciliation field mapping for the new attribute in the Process Definition section of Oracle Identity Manager Design Console.

To create reconciliation field mapping for the new attribute in the process definition:
  1. Expand Process Management, and double-click Process Definition.
  2. Search for and open the SuccessFactors User process definition.
  3. On the Reconciliation Field Mappings tab of the process definition, click Add Field Map.
  4. From the Field Name list, select the field that you want to map.
  5. Double-click the Process Data Field field, and then select the column for the attribute. For example, select UD_SFSF_USR_LASTNAME.
  6. Click the Save icon.
    The following screenshot shows the new reconciliation field mapped to a process data field in the process definition:

    Figure 4-3 New Reconciliation Field Mapped to a Process Data Field in the Process Definition

    Description of Figure 4-3 follows
    Description of "Figure 4-3 New Reconciliation Field Mapped to a Process Data Field in the Process Definition"

4.1.4 Creating Entries in Lookup Definitions

You create an entry for the newly added attribute in the lookup definition that holds attribute mappings for reconciliation.

To create an entry for the newly added attribute in the lookup definition:
  1. Expand Administration.
  2. Double-click Lookup Definition.
  3. Search for and open the Lookup.SuccessFactors.UM.ReconAttrMap lookup definition.
  4. Click Add and enter the Code Key and Decode values for the field.
  5. Click the Save icon.
    The following screenshot shows the entry added to the lookup definition:

    Figure 4-4 Entry Added to the Lookup Definition

    Description of Figure 4-4 follows
    Description of "Figure 4-4 Entry Added to the Lookup Definition"

4.1.5 Performing Changes in a New UI Form

You must replicate all changes made to the Form Designer of the Design Console in a new UI form.

To perform changes in a new UI form:
  1. Log in to Oracle Identity System Administration.
  2. Create and activate a sandbox.
  3. Create a new UI form to view the newly added field along with the rest of the fields.
  4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form, and then save the application instance.
  5. Publish the sandbox.

4.2 Adding New User Attributes for Provisioning

The connector provides a default set of attribute mappings for provisioning between Oracle Identity Manager and the target system. If required, you can add new user attributes for provisioning.

The default attribute mappings for provisioning are listed in Table 1-26.

The following topics discuss the procedure to add new user attributes for provisioning:

4.2.1 Adding New Attributes for Provisioning

You add a new attribute on the process form in the Form Designer section of Oracle Identity Manager Design Console.

To add a new attribute on the process form:

Note:

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

  1. Log in to the Oracle Identity Manager Design Console.
  2. Expand Development Tools, and double-click Form Designer.
  3. Search for and open the UD_SFSF_USR process form.
  4. Click Create New Version, and then click Add.
  5. Enter the details of the attribute.
    For example, if you are adding the LASTNAME, enter UD_SFSF_USR_LASTNAME in the Name field, and then enter the rest of the details of this field.
  6. Click the Save icon, and then click Make Version Active.
    The following screenshot shows the new field added to the process form:

    Figure 4-5 New Field Added to the Process Form

    Description of Figure 4-5 follows
    Description of "Figure 4-5 New Field Added to the Process Form"

4.2.2 Creating Entries in Lookup Definitions for Provisioning

You create an entry for the newly added attribute in the lookup definition that holds attribute mappings for provisioning.

To create an entry for the newly added attribute in the lookup definition:
  1. Expand Administration.
  2. Double-click Lookup Definition.
  3. Search for and open the Lookup.SuccessFactors.UM.ProvAttrMap lookup definition.
  4. Click Add and then enter the Code Key and Decode values for the attribute.

    For example, enter LASTNAME in the Code Key column and then enter LASTNAME in the Decode column.

4.2.3 Creating a Task to Enable Update Operations

You create a task to enable updates on the new user attribute during provisioning operations. If you do not perform this procedure, you cannot modify the value of the attribute after you set a value for it during the Create User provisioning operation.

If you do not perform this procedure, then you will not be able to modify the value of the attribute after you set a value for it during the Create User provisioning operation.
To enable the update of the attribute during provisioning operations, add a process task for updating the new user attribute as follows:
  1. Expand Process Management, and double-click Process Definition.
  2. Search for and open the SuccessFactors User process definitions.
  3. Click Add.
  4. On the General tab of the Creating New Task dialog box, enter a name and description for the task and then select the following:
    • Conditional
    • Required for Completion
    • Allow Cancellation while Pending
    • Allow Multiple Instances
  5. Click the Save icon.

    The following screenshot shows the new task added to the process definition:

    Figure 4-6 New task Added to the Process Definition

    Description of Figure 4-6 follows
    Description of "Figure 4-6 New task Added to the Process Definition"
  6. In the provisioning process, select the adapter name in the Handler Type section as follows:
    1. Go to the Integration tab, click Add.
    2. In the Handler Selection dialog box, select Adapter.
    3. From the Handler Name column, select adpSUCCESSFACTORSUPDATEOBJECTTASK.
    4. Click Save and close the dialog box.
      The following screenshot shows the list of adapter variables:

      The list of adapter variables is displayed on the Integration tab.

      Figure 4-7 List of Adapter Variables

      Description of Figure 4-7 follows
      Description of "Figure 4-7 List of Adapter Variables"
  7. In the Adapter Variables region, click the ParentFormProcessInstanceKey variable.
  8. In the dialog box that is displayed, create the following mapping:

    • Variable Name: ParentFormProcessInstanceKey

    • Map To: Process Data

    • Qualifier: Process Instance

  9. Click Save and close the dialog box.
  10. If you are enabling update provisioning operations for a User attribute, then repeat Steps 7 through 9 for the remaining variables listed in the Adapter Variables region.
    The following table lists values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:
    Variable Map To Qualifier Literal Value

    Adapter Return Value

    Response Code

    NA

    NA

    Object Type

    Literal

    String

    User

    itResourceFieldName

    Literal

    String

    UD_SFSF_USR_SERVER

    FieldName

    Literal

    String

    LASTNAME

    procInstanceKey

    ProcessData

    Process Instance

    NA
  11. On the Responses tab, click Add to add at least the SUCCESS response code, with Status C. This ensures that if the task is successfully run, then the status of the task is displayed as Completed.
  12. Click the Save icon and close the dialog box, and then save the process definition.

4.2.4 Replicating Form Designer Changes to a New UI Form

You must replicate all changes made to the Form Designer of the Design Console in a new UI form.

To replicate all changes in a new UI form:
  1. Log in to Oracle Identity System Administration.
  2. Create and activate a sandbox.
  3. Create a new UI form to view the newly added field along with the rest of the fields.
  4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form, and then save the application instance.
  5. Publish the sandbox.

4.3 Configuring Validation of Data During Reconciliation and Provisioning

You can configure validation of reconciled and provisioned single-valued data according to your requirements.

For example, you can validate data fetched from the User Name attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the User Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations. For data that fails the validation check, the following message is displayed or recorded in the log file: Validation failed for attribute ATTRIBUTE_NAME.

To configure validation of data:

  1. Write code that implements the required validation logic in a Java class.
    The validation class must implement validate method with the following method signature: 
    boolean validate(HashMap hmUserDetails, HashMap hmEntitlementDetails, String field)

    The following sample validation class checks if the value in the User Name attribute contains the number sign (#):

    public boolean validate(HashMap hmUserDetails,
HashMap hmEntitlementDetails, String field) { /*
*       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 sUserName=(String) hmUserDetails.get(field); for(int i=0;i<sUserName.length();i++){
if (sUserName.charAt(i) == '#'){ valid=false;
break;}
              }
         return valid;
                 }
  2. Create a JAR file to hold the Java class.
  3. Copy the JAR file to Oracle Identity Manager database.

    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. Specify 1 as the value of the JAR type.

  4. If you created the Java class for validating a process form field for reconciliation, then:
    1. Log in to the Design Console.
    2. Create a lookup definition named Lookup.SuccessFactors.UM.ReconValidation.
    3. Save the changes to the lookup definition.
    4. Search for and open the Lookup.SuccessFactors.UM.Configuration lookup definition.
    5. In the Code Key column, enter Recon Validation Lookup. In the Decode column, enter Lookup.SuccessFactors.UM.ReconValidation.
    6. Save the changes to the lookup definition.
  5. Add an entry in the Lookup.SuccessFactors.UM.Configuration lookup definition to enable transformation as follows:
    1. Expand Administration, and then double-click Lookup Definition.
    2. Search for and open the Lookup.SuccessFactors.UM.Configuration lookup definition.
    3. In the Code Key column, enter Recon Transformation Lookup. In the Decode column, enter Lookup.SuccessFactors.UM.ReconTransformation.
    4. Save the changes to the lookup definition.

4.4 Configuring Transformation of Data During User Reconciliation

You can configure transformation of reconciled single-valued account data according to your requirements.

For example, you can use User Name and Last Name values to create a value for the Full Name field in Oracle Identity Manager.

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

  1. Write code that implements the required transformation logic in a Java class.

    The transformation class must implement the transform method with the following method signature:

    Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField)

    The following sample transformation class creates a value for the Full Name attribute by using values fetched from the User Name and Last Name attributes of the target system:

    package oracle.iam.connectors.common.transform;
import java.util.HashMap;
public class TransformAttribute {
/*
Description:Abstract method for transforming the attributes
param hmUserDetails< String,Object>
HashMap containing parent data details
param hmEntitlementDetails < String,Object>
HashMap containing child data details
*/
public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails,String sField) {
/*
*       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 sUserName= (String)hmUserDetails.get("User Name"); String sLastName= (String)hmUserDetails.get("Last Name"); String sFullName=sUserName+"."+sLastName;
return sFullName;
}
}
  2. Create a JAR file to hold the Java class.
  3. Copy the JAR file to Oracle Identity Manager database.

    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. Specify 1 as the value of the JAR type.

  4. If you created the Java class for transforming a process form field for reconciliation, then:
    1. Log in to the Design Console.
    2. Create a lookup definition named Lookup.SuccessFactors.UM.ReconTransformation.
    3. In the Code Key column, enter the resource object field name on which you want to apply transformation. For example, User Name. In the Decode column, enter the name of the class that implements the transformation logic. For example, oracle.iam.connectors.common.transform.TransformAttribute.
    4. Save the changes to the lookup definition.
  5. Add an entry in the Lookup.SuccessFactors.UM.Configuration lookup definition to enable transformation as follows:
    1. Expand Administration, and then double-click Lookup Definition.
    2. Search for and open the Lookup.SuccessFactors.UM.Configuration lookup definition.
    3. In the Code Key column, enter Recon Transformation Lookup. In the Decode column, enter Lookup.SuccessFactors.UM.ReconTransformation.
    4. Save the changes to the lookup definition.

4.5 Configuring the Connector for Multiple Installations of the Target System

You must create copies of the connector to configure it for multiple installations of the target system.

The following example illustrates this requirement:

The 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 create copies of the connector. See Cloning Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager for more information.

4.6 Defining the Connector

Defining a connector is equivalent to registering the connector with Oracle Identity Manager. You can define a customized or reconfigured connector using Oracle Identity System Administration. After you define a connector, a record representing the connector is created in the Oracle Identity Manager database.

A connector is automatically defined when you install it using the Install Connectors feature or when you upgrade it using the Upgrade Connectors feature. You must manually define a connector if:

  • You import the connector by using the Deployment Manager.

  • You customize or reconfigure the connector.

  • You upgrade Oracle Identity Manager.

The following events take place when you define a connector:

  • A record representing the connector is created in the Oracle Identity Manager database. If this record already exists, then it is updated.

  • The status of the newly defined connector is set to Active. In addition, the status of a previously installed release of the same connector automatically is set to Inactive.

See Defining Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed information about the procedure to define connectors.

4.7 Understanding OData API Dictionary

The OData API Dictionary component stores a bundle of object entities. Each SuccessFactors instance contains ready-to-use object entities. The object entities in the OData API Dictionary can also be customized as per requirement.

The following topics are discussed in this appendix:

4.7.1 About OData API Dictionary

Every SuccessFactors instance has several object entities. The OData API Dictionary bundles these object entities and presents them in a tabular format. The SuccessFactors object entities contain information such as allowed operations, attributes (also referred to as property name) and labels.

4.7.2 Viewing OData API Dictionary in the SAP SuccessFactors Connector

SAP SuccessFactors provides an option to view existing object entities listed under the OData API Dictionary link.

To view an existing OData API Dictionary:
  1. Log in to your SuccessFactors instance.
  2. Search for OData API Dictionary in the Tool Search text field on the Admin Center page. The OData API Dictionary link listed under My Favorites link category.
  3. Click OData API Dictionary link. The OData API Entities list appears.
    The displayed list includes both ready-to-use object entities along with your customized object entities.

    Figure 1-3 shows a list of OData API Entities.

    Figure 4-8 OData API Entities

    Description of Figure 4-8 follows
    Description of "Figure 4-8 OData API Entities"

4.7.3 Adding Custom Attributes and Object Entities in Oracle Identity Manager

SAP SuccessFactors provides a ready-to-use OData API Dictionary. Apart from the ready-to-use object entities present in the OData API Dictionary, if you require a new attribute and a new object entity, then you need to customize the OData API Dictionary. Using the OData API Dictionary component, all customized object entities are mapped to their corresponding attributes in the target system.

Adding custom attributes and object entities to Oracle Identity Manager is a two-step operation as follows:

  • Firstly in your SuccessFactors instance, you need to search for the custom attribute that is present in the OData API Dictionary. Make a note of the custom attribute and the entity object below which this custom attribute is listed. For more information about customizing the OData API Dictionary, contact SAP SuccessFactors support .

  • After obtaining the required information about custom attribute and object entity, you need to add this new attribute to Oracle Identity Manager. This new attribute (with the help of Code key and Decode values) provides a mapping between the custom attribute and the target system.
To associate the attribute with an object entity:
  1. Log in to your SuccessFactors instance.
  2. Search for OData API Dictionary in the Tool Search text field on the Admin Center page. The OData API Dictionary link listed under My Favorites link category.
  3. Click OData API Dictionary link. The OData API Entities list appears.
  4. From the list of OData API Entities, scroll and search for the attribute under consideration.
  5. For the attribute under consideration, make a note of Property Name and Label along with Object Entity to which this attribute belongs.
    As an example, consider business unit is the attribute under consideration. Scroll and search for this attribute in the OData API Entities. After finding this attribute, make a note of: bussinetUnit to be the Property Name, Business Unit to be the Label and these two are present under the EmpJob object entity list.
  6. Log in to Oracle Identity Manager Design Console.
  7. Expand Administration and then double-click Lookup Definition.
  8. Search for and open the Lookup.SuccessFactors.UM.ProvAttrMap Lookup definition.
  9. Click Add to add a new attribute.
  10. Enter values for the Code Key and for the Decode in their corresponding text boxes. Use the format provided below:
    Code Key Format: LABEL ; Decode : OBJ_ENTITY.PROP_NAME

    In this format, replace LABEL, OBJ_ENTITY, and PROP_NAME with the values from the Label, Object Entity, and Property Name columns from the OData API Dictionary you noted in Step 4.

  11. Click Save to save your changes.

4.7.4 Providing Values in Static Lookups

SuccessFactors provides an option to add values to the static lookup definition. Adding values is a requirement to associate code key and decode values in the target system. To add values in the static lookups for SuccessFactors, first you need to check if any code value is present for the attribute under consideration. If a code value is present, then the same needs to be added to the corresponding lookup definition in Oracle Identity Manager.

Consider the below illustration shown in Figure 4-9. In the illustration, observe that the value in the location field is San Mateo (US_SFO). The US_SFO is the value which needs to be provided as the Code Key and the value San Mateo (US_SFO) or just the name of the location San Mateo as the Decode value for the static Lookup Location. These two values need to be present under Lookup.Location in Oracle Identity Manager Process Form page.

Figure 4-9 Providing Values in a Static Lookup

Description of Figure 4-9 follows
Description of "Figure 4-9 Providing Values in a Static Lookup"
To provide values for the Lookup.SuccessFactors.Location static lookup:
  1. Log in to the Oracle Identity Manager Design Console.
  2. Expand Administration and then double-click Lookup Definition.
  3. Search for and open Lookup.SuccessFactors.Location Lookup definition.
  4. Click Add to add a new attribute.
  5. Enter values for the Code Key and for the Decode in their corresponding text boxes. Use the format provided below:
    Code Key Format: LOCATION_LABEL ; Decode : LOCATION_NAME

    In this format, replace LOCATION_LABEL, and LOCATION_NAME with the values from the (US_SFO), and San Mateo (US_SFO) respectively.

  6. Click Save to save your changes.