IBM Security Identity Governance and Intelligence: …public.dhe.ibm.com/.../isim/adapters/igi/igi_sap_hr_book.pdfSAP Netweaver Application Server ABAP with SAP Basis Component with

IBM Security Identity Governance and Intelligence

SAP HR feed adapter Installation andConfiguration Guide

IBM

IBM Security Identity Governance and Intelligence

SAP HR feed adapter Installation andConfiguration Guide

IBM

ii IBM Security Identity Governance and Intelligence: SAP HR feed adapter Installation and Configuration Guide

Contents

Figures . . . . . . . . . . . . . . . v

Tables . . . . . . . . . . . . . . . vii

Chapter 1. Overview . . . . . . . . . 1Features of the adapter . . . . . . . . . . . 1Architecture . . . . . . . . . . . . . . 1Supported configurations . . . . . . . . . . 2

Chapter 2. Planning. . . . . . . . . . 5Roadmap for IBM Tivoli Directory Integrator basedadapters, for IBM Security Identity Governance andIntelligence . . . . . . . . . . . . . . . 5Prerequisites . . . . . . . . . . . . . . 7Software downloads . . . . . . . . . . . . 7Installation worksheet . . . . . . . . . . . 8

Chapter 3. Installing . . . . . . . . . 9Installing the dispatcher . . . . . . . . . . 9Installing the adapter stylesheets . . . . . . . 9Installing the adapter binaries or connector . . . . 9Installing the SAP Java Connector (JCo) . . . . . 10Enabling the SAP Java Connector (JCo) trace . . . 11Enabling Unicode . . . . . . . . . . . . 12Verifying the adapter installation . . . . . . . 13Configuring the rule for the unique user ID . . . 14Restarting the adapter service . . . . . . . . 15Importing the adapter profile . . . . . . . . 15Importing attribute mapping file . . . . . . . 16Adding a connector . . . . . . . . . . . 17Enabling connectors . . . . . . . . . . . 18Reviewing and setting channel modes for each newconnector . . . . . . . . . . . . . . . 19

Attribute Mapping . . . . . . . . . . . . 20Service/Target form details . . . . . . . . . 21

Adapter Details tab. . . . . . . . . . . 22SAP Connection Details tab . . . . . . . . 22Reconciliation Advanced Mapping tab . . . . 22Dispatcher Attributes tab . . . . . . . . . 23

Verifying that the adapter is working correctly . . 23

Chapter 4. Upgrading . . . . . . . . 25Upgrading the Dispatcher . . . . . . . . . 25Upgrading the adapter profile . . . . . . . . 25

Chapter 5. Configuring . . . . . . . . 27Customizing the adapter profile . . . . . . . 27XSL stylesheets . . . . . . . . . . . . . 28BAPI method execution with stateful connection . . 29Improving the reconciliation operation performance 30

Chapter 6. Troubleshooting . . . . . . 31Techniques for troubleshooting problems . . . . 31Logs . . . . . . . . . . . . . . . . . 33Error messages and problem solving . . . . . . 33

Chapter 7. Uninstalling . . . . . . . . 37

Chapter 8. Reference . . . . . . . . 39Adapter attributes and object classes . . . . . . 39Adapter configuration properties . . . . . . . 43

Index . . . . . . . . . . . . . . . 45

iii

iv IBM Security Identity Governance and Intelligence: SAP HR feed adapter Installation and Configuration Guide

Figures

1. The architecture of the SAP HR feed adapter 12. Example of a single server configuration . . . 2

3. Example of a multiple server configuration 3

v

vi IBM Security Identity Governance and Intelligence: SAP HR feed adapter Installation and Configuration Guide

Tables

1. Prerequisites to install the adapter . . . . . 72. Required information to install the adapter 83. Adapter components . . . . . . . . . 144. Prerequisites for enabling a connector . . . . 185. Specific warning and error messages and

actions . . . . . . . . . . . . . . 34

6. Supported attributes . . . . . . . . . 397. USER_ERC attribute mapping . . . . . . 398. OrganizationalUnit_ERC attribute mapping 42

vii

viii IBM Security Identity Governance and Intelligence: SAP HR feed adapter Installation and Configuration Guide

Chapter 1. Overview

An adapter is an interface between a managed resource and the IBM® SecurityIdentity server. The SAP HR feed adapter uses the Tivoli® Directory Integratorfunctionality to enable communication between the IBM Security Identity serverand the SAP Netweaver Application Server ABAP.

Adapters can be installed on the managed resource. The IBM Security Identityserver manages access to the resource by using the security system. The adapterruns as a service, independently of whether you are logged on to the IBM SecurityIdentity server.

Features of the adapterThe adapter is designed to reconcile personal and organizational information fromthe target system.

It checks the connection between the SAP Netweaver Application Server ABAPand IBM Security Identity Governance and Intelligence server.

You can install the XSL stylesheet with the adapter to customize and configure theadapter extension to meet the business requirements.

ArchitectureSeveral components are involved in running and using the adapter. Install all thesecomponents so that the adapter can function correctly.

The adapter requires the following components:v Dispatcherv Tivoli Directory Integrator connectorv IBM Security Identity Adapter profile

Figure 1 describes the components that work together to complete the user accountmanagement tasks in a Tivoli Directory Integrator environment.

RMI callsIBM SecurityIdentity Server

Dispatcher Service(an instance of the IBMTivoli Directory Integrator)

Adapter resource

Figure 1. The architecture of the SAP HR feed adapter

1

Supported configurationsThe adapter supports both single and multiple server configurations.

The fundamental components in each environment are:v The IBM Security Identity serverv The IBM Tivoli Directory Integrator serverv The managed resourcev The adapter

The adapter must be installed directly on the server that runs the Tivoli DirectoryIntegrator server.

Single server configuration

In a single server configuration, the following components are installed in oneserver to establish communication with the SAP Application Server:v IBM Security Identity serverv Tivoli Directory Integrator serverv SAP HR feed adapter

The SAP Netweaver Application Server ABAP is installed on a different server asshown in Figure 2.

Multiple server configuration

In a multiple server configuration, the following components are installed ondifferent servers.v IBM Security Identity serverv Tivoli Directory Integrator serverv SAP HR feed adapterv SAP Netweaver Application Server ABAP

TheTivoli Directory Integrator server and the SAP HR feed adapter are installed onthe same server as shown in Figure 3 on page 3.

IBM SecurityIdentity Server

Tivoli DirectoryIntegrator Server

Adapter

Managedresource

Figure 2. Example of a single server configuration

2 IBM Security Identity Governance and Intelligence: SAP HR feed adapter Installation and Configuration Guide

The SAP HR feed adapter is configurable and customizable.

Note: Support can extend only to the configuration of the adapter such as addingthe mapping for additional attributes and XSL stylesheets. Support does not coverthe additions or modifications of the Tivoli Directory Integrator Assembly Linescripts for example.

IBM SecurityIdentity Server Tivoli Directory

Integrator server Managedresource

Adapter

Figure 3. Example of a multiple server configuration

Chapter 1. Overview 3


Chapter 2. Planning

Installing and configuring the adapter involves several steps that you mustcomplete in a specific sequence. Follow the roadmap for the main tasks.

Roadmap for IBM Tivoli Directory Integrator based adapters, for IBMSecurity Identity Governance and Intelligence

Follow this section when using the guide to install, configure, troubleshoot, oruninstall the adapter.

Note: There is a separate instruction for installing, upgrading or uninstallingadapters from the IBM Security Identity Governance and Intelligence virtualappliance.

Pre-installation

Complete these tasks.1. Verify that your environment meets the software and hardware requirements

for the adapter. See Prerequisites.2. Obtain the installation software. See Software downloads.3. Obtain the necessary information for the installation and configuration. See

Installation worksheet.

Installation

Complete these tasks.1. Install the dispatcher.2. Install the adapter binaries or connector.3. Install 3rd party client libraries.4. Set up the adapter environment.5. Restart the adapter service.6. Import the adapter profile.7. Load attribute mapping.8. Set account defaults.9. Create an adapter service/target.

10. Install the adapter language package.11. Verify that the adapter is working correctly.

Upgrade

To upgrade the adapter, do a full installation of the adapter. Follow the Installationroadmap.

Configuration

Complete these tasks.1. Configure secure communication between the IBM Security Identity server and

the adapter.

5

a. Configure 1-way authentication.b. Configure 2-way authentication.

2. Configure secure communication between the adapter and the managed target.a. Configure 1-way authentication.b. Configure 2-way authentication.

3. Configure the adapter.4. Modify the adapter profiles.5. Customize the adapter.

Troubleshooting

See the following topics.v Techniques for troubleshooting problemsv Configure debuggingv Logsv Error messages and problem solving

Uninstallation

Complete these tasks.1. Stop the adapter service.2. Remove the adapter binaries or connector.3. Remove 3rd party client libraries.4. Delete the adapter service/target.5. Delete the adapter profile.

Reference

See the following topics.v Adapter attributes and object classesv Adapter attributes by operationsv Special attributes


PrerequisitesVerify that your environment meets the software and hardware requirements forthe adapter.

Table 1 identifies the prerequisites for the adapter installation.

Table 1. Prerequisites to install the adapter

Prerequisite Description

Directory Integrator v IBM Tivoli Directory Integrator Version7.1.1 + 7.1.1-TIV-TDI-FP0004 +7.2.0-ISS-SDI-LA0008

v IBM Security Directory Integrator Version7.2

Note:

v Earlier versions of IBM Tivoli DirectoryIntegrator that are still supported mightfunction properly. However, to resolveany communication errors, you mustupgrade your Directory Integrator releaseto the versions that the adapter officiallysupports.

v The adapter supports IBM SecurityDirectory Integrator 7.2, which is availableonly to customers who have the correctentitlement. Contact your IBMrepresentative to find out whether youhave the entitlement to download IBMSecurity Directory Integrator 7.2.

IBM Security Identity server The following servers are supported:

v IBM Security Identity Governance andIntelligence server Version 5.2.2

SAP Netweaver Application Server ABAPwith SAP Basis Component with SAP HRmodule installed.

Tested with SAP Netweaver 730, Componentversion SAP ECC 6.0 with SAP HR Fix Pack22 installed

Tivoli Directory Integrator adapters solutiondirectory

A Tivoli Directory Integrator work directoryfor adapters. For more information, see, theDispatcher Installation and Configuration Guide.

System administrator authority You must have system administratorauthority to complete the adapterinstallation procedure.

Software downloadsLog in to your account on the IBM Passport Advantage® website and downloadthe software.

Go to IBM Passport Advantage. See the IBM Security Identity Governance andIntelligence Download Document.

Note: You can also obtain adapter information from IBM Support.

Chapter 2. Planning 7

http://www.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

Installation worksheetThe installation worksheet lists the information that is required to install andconfigure the adapter. Complete this worksheet before you start the installationprocedure for ease of reference. Make a copy of the worksheet for each adapterinstance you install.

Table 2. Required information to install the adapter

Required information Description Value

Tivoli DirectoryIntegrator HomeDirectory

The ITDI_HOME directory contains thejars/connectors subdirectory, whichcontains the files for the adapters.

Windows:

v drive\ProgramFiles\IBM\TDI\V7.2

UNIX:

v /opt/IBM/TDI/V7.2

Adapter SolutionDirectory

See the Dispatcher Installation andConfiguration Guide.

Windows:

v drive\ProgramFiles\IBM\TDI\V7.2\timsol

UNIX:

v /opt/IBM/TDI/V7.2/timsol


Chapter 3. Installing

Installing the adapter mainly involves importing the adapter profile and creatingan adapter service. Depending on the adapter, several other tasks can be involvedto completely install it.

Depending on your adapter, the Tivoli Directory Integrator connector mightalready be installed as part of the Tivoli Directory Integrator product and nofurther action is required. If the connector is not pre-installed, install it after theDispatcher.

Installing the dispatcherIf this is the first Tivoli Directory Integrator-based adapter installation, you mustinstall the RMI Dispatcher before you install the adapter. Install the RMIDispatcher on the same Tivoli Directory Integrator server where you want to installthe adapter.

If you already installed the RMI Dispatcher for another adapter, you do not needto reinstall it.

If you have not yet installed the RMI Dispatcher in the Tivoli Directory Integratorenvironment, download the Dispatcher installer from the IBM Passport Advantagewebsite. For more information about the installation, see the Dispatcher Installationand Configuration Guide.

Installing the adapter stylesheetsThe SAP HR feed adapter requires a set of stylesheets, which are used by theadapter’s IBM Tivoli Directory Integrator assembly lines.

About this task

The adapter stylesheets must be copied from the SAP HR feed adapter package toan xsl directory.

Procedure1. If the Dispatcher is installed in the Tivoli Directory Integrator adapters solution

directory (for example, timsol), navigate to that directory. Otherwise, navigateto the ITDI_HOME directory.

2. Create a directory with the name xsl, if one does not exist.3. Depending on your Dispatcher installation, copy the files from the tdi/xsl

directory of the adapter package to the xsl directory of the IBM TivoliDirectory Integrator solution directory or ITDI_HOME directory.

Installing the adapter binaries or connectorThe adapter binaries establish that communication to the managed target. Someadapters relies on the Security Directory Integrator and don't include any binaries.For those adapters that do provide binary distribution, follow the adapter'sinstallation steps.

9

http://www.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

Before you beginv The Dispatcher must be installed.

Procedure1. Copy tdi/connectors/*.jar from the adapter package to the

ITDI_HOME/jars/connectors directory.2. Copy tdi/functions/*.jar from the adapter package to the

ITDI_HOME/jars/functions directory.

Installing the SAP Java Connector (JCo)The connector might or might not be available with the base Tivoli DirectoryIntegrator or Security Directory Integrator product. The connector is required toestablish communication between the adapter and the Dispatcher. After youdownload the JCo package, unpack the contents and then follow these instructions.

Before you beginv Download the SAP Java Connector (JCo).

The adapter requires access to the SAP Java Connector (JCo) API at run time.This API must be downloaded from the SAP support portal. Access to thiswebsite requires authentication with a valid SAP support ID (S-ID). Contact yourSAP marketing representative to obtain one of these IDs.

v Unpackage the content of the file.

Procedurev Windows:

1. Copy the sapjco3.jar file into ITDI_HOME/jars/3rdparty/others.2. Copy the sapjco3.dll file into ITDI_HOME/libs. On Windows, JCo 3 requires

additional Microsoft Visual C++ 2005 libraries to be installed. Installationdetails for the package that contains these libraries are specified in MicrosoftKnowledge Base article 973544.

3. Restart the adapter service.v UNIX or Linux:

1. Create a symbolic link to the sapjco3.jar file in ITDI_HOME/jars/3rdparty/others:ln -s <sapjco_install_dir>/sapjco3.jar

ITDI_HOME/jars/3rdparty/others/sapjco3.jar

2. Add the SAP JCo installation directory to the dynamic library path:export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<sapjco_install_dir>export LIBPATH=$LIBPATH:<sapjco_install_dir>

3. Restart the Dispatcher. For assistance, see “Restarting the adapter service” onpage 15.

Note: These steps ensure that the sapjco3 libraries are included in theexecutable path and in the loadable library path, when required. Theenvironment variable for dynamic library path and the command forrestarting the Dispatcher might vary on different UNIX operation systems.

v Linux on System z 64-bit architecture (s390x)

1. Create a symbolic link to the sapjco3.jar file in ITDI_HOME/jars/3rdparty/others:ln -s <sapjco_install_dir>/sapjco3.jar

ITDI_HOME/jars/3rdparty/others/sapjco3.jar


2. Add the SAP JCo installation directory to the dynamic library path:export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<sapjco_install_dir>export LIBPATH=$LIBPATH:<sapjco_install_dir>

3. SAP JCo is supported on Linux on System z only for 64-bit architecture. TheIBM Tivoli Directory Integrator is packaged only with the 31-bit version ofJava™. Additionally, it must be configured to run with the 64-bit version ofJava. The following steps change the JVM for the complete IBM TivoliDirectory Integrator instance, not only for the Dispatcher.a. Stop the Dispatcher:

/etc/init.d/ITIMAd stop

b. Install the IBM Java 1.5 64-bit release (for exampleibm-java2-s390x-5.0.9.rpm)

4. Change the IBM Tivoli Directory Integrator JRE to become 64 bit:mv ITDI_HOME/jvm/jre ITDI_HOME/jvm/jre32ln -s JAVA_1.5_64BIT_HOME/jre ITDI_HOME/jvm/jre

5. Start the Dispatcher:/etc/init.d/ITIMAd start

Enabling the SAP Java Connector (JCo) traceActivate traces to get more information that can help you analyze errors that arerelated to connection issues.

Procedure1. Navigate to the IBM Tivoli Directory Integrator adapters solution directory. For

example, ITDI_HOME\timsol.2. Open the file in an editor.

For Windows operating systemsOpen the file ibmdiservice.props

For UNIX or Linux operating systemsOpen the file ibmdisrv

3. Edit the following property:v For Windows operating systems

jvmcmdoptions=-Djco.trace_level=10 -Djco.trace_path=E:\jco_trace\ -Djco.rfc=1

Where:

-Djco.trace_level=NThe trace level can be 0 - 10, where 10 being the most detailed trace.

-Djco.trace_path=<PATH>If a trace path is set, the JCo traces are written to one or multiple filesthat are named JCO<date>_<time>.<no>.trc in thespecified PATH directory. Otherwise, the JCo traces are written to thestandard output stream, where, by default is an output to the console.

Note: The jco_trace directory must be available.

-Djco.jrfc=1If set to 1, JCo trace is enabled for all connections. This configurationshould be the last resort.

v For UNIX or Linux operating systems-Djco.trace_level=10 -Djco.trace_path=/opt/jco_trace/ -Djco.rfc=1

Chapter 3. Installing 11

Where:

-Djco.trace_level=NThe trace level can either be 0 or 10, where 10 being the most detailedtrace.

-Djco.trace_path=<PATH>If a trace path is set, the JCo traces are written to one or multiple filesthat are named JCO<date>_<time>.<no>.trc in thespecified PATH directory. Otherwise, the JCo traces are written to thestandard output stream, where, by default is an output to the console.

Note: The jco_trace directory must be available.

-Djco.jrfc=1If set to 1, JCo trace is enabled for all connections. This configurationshould be the last resort.

For example:"%TDI_JAVA_PROGRAM%" -Xdebug -Xnoagent -Djava.compiler=NONE -Djco.trace_level=10-Djco.trace_path=/opt/jco_trace/ -Djco.rfc=1-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5555 -classpath"%TDI_HOME_DIR%\IDILoader.jar" %ENV_VARIABLES% com.ibm.di.loader.ServerLauncher %*set RC=%ERRORLEVEL%

4. Save your changes.5. Restart the adapter service.

Enabling UnicodeTo support multibyte character encoding, you must configure the Dispatcher JVMproperties.

About this task

The Dispatcher process is a running instance of the IBM Tivoli Directory Integratorserver.

The IBM Tivoli Directory Integrator is a Java application that is running its ownJVM. You can supply standard JVM properties to the Dispatcher such as:v Encodingv Memory allocation initial sizev Memory allocation maximum size

Complete these steps to set up the Dispatcher encoding to UTF-8.

Procedurev On Windows operating systems

1. Stop the IBM Tivoli Directory Integrator (Security Adapters) service.2. Navigate to the adapter timsol directory.3. Open the ibmdiservice.props file with a text editor.4. Set the value of the jvmcmdoptions property to the Java property value that

you want to change to. For example, if you want the Dispatcher JVM to runwith UTF-8 encoding, then setjvmcmdoptions=- Dfile.encoding=UTF-8


Note: When you set multiple properties, separate two properties with aspace.

5. Save and close the ibmdiservice.props file.6. Start the IBM Tivoli Directory Integrator (Security Adapters) service.

v On UNIX or Linux operating systems

1. Navigate to the ITDI_HOME installation directory.2. Run the following command:

vi ibmdisrv

3. Modify the string value in the following format:"$JRE_PATH/java" -cp "/opt/IBM/TDI/V7.1.1/jars/3rdparty/IBM/db2jcc_license_c.jar" "-Dlog4j.configuration=file:etc/log4j.properties" -jar "/opt/IBM/TDI/V7.1.1/IDILoader.jar"com.ibm.di.server.RS "$@"

For example, if you want the JVM to use UTF-8 encoding, then modify thecommand as:"$JRE_PATH/java" -cp "/opt/IBM/TDI/V7.1.1/jars/3rdparty/IBM/db2jcc_license_c.jar" "-Dfile.encoding=UTF-8" "-Dlog4j.configuration=file:etc/log4j.properties" -jar"/opt/IBM/TDI/V7.1.1/IDILoader.jar" com.ibm.di.server.RS "$@"

4. Restart the Dispatcher service. Run one of the following commands to restartthe process:

On AIX® operating systems/opt/IBM/TDI/V7.1.1/timsol/ITIMAd restartsrc

On Linux, Solaris, and HP-UX operating systems/opt/IBM/TDI/V7.1.1/timsol/ITIMAd restart

v Enabling UTF-8 encoding for the Dispatcher and adapter log file is suggested.Logging capabilities are provided by IBM Tivoli Directory Integrator. Encodingsettings can be enabled as follows:1. Open the file ITDI_HOME/solution/etc/log4j.properties in a text editor.2. After the line log4j.appender.Default.file=logs/ibmdi.log, add the

following setting:log4j.appender.Default.file.encoding=UTF-8

3. The resulting entry looks like the following example:log4j.appender.Default=org.apache.log4j.FileAppenderlog4j.appender.Default.file=logs/ibmdi.loglog4j.appender.Default.file.encoding=UTF8log4j.appender.Default.layout=org.apache.log4j.PatternLayoutlog4j.appender.Default.layout.ConversionPattern=%d{ISO8601} %-5p [%c] - %m%nlog4j.appender.Default.append=false

4. Restart the IBM Tivoli Directory Integrator Adapter Dispatcher service.

Verifying the adapter installationAfter you install the adapter, verify the adapter components on the IBM TivoliDirectory Integrator server. If the adapter is installed correctly, the adapter JAR fileexists in the specified directory. If the JAR file does not exist, the installation is notsuccessful and the adapter cannot function as expected. You must copy the JAR filein the specified location.

These adapter components must exist on the IBM Tivoli Directory Integratorserver.


Table 3. Adapter components

Directory Adapter component

ITDI_HOME/jars/connectors SapNWUserConnector.jar, SapNWSupport.jar

ITDI_HOME/jars/functions SapNWRfc.jar

ITDI_HOME/jars/3rdparty/other sapjco3.jar

ITDI_HOME/libs sapjco3.dll

ITDI_HOME/solution/xsl v sapnw_bapi_errors.properties

v sapnw_bapi_person_getdetail_precall.xsl

v sapnw_bapi_person_address_precall.xsl

v sapnw_bapi_person_email_precall.xsl

v sapnw_bapi_person_getdetail_postcall.xsl

Configuring the rule for the unique user IDComplete this task to configure the rule for the unique user ID for HR feedprofiles. You must add the Generate Unique UserID rule to the USER_ADD flowprocess.

About this task

The USER_ADD flow process does not include the Generate Unique UserID ruleby default. You must manually add the Generate Unique UserID rule before youcan successfully import HR feed data.

Procedure1. Log in to the IBM Security Identity Governance and Intelligence

Administration Console.2. Click Access Governance Core.3. Click Configure > Rules > Rules.4. In the Rules tab on the left pane, complete the following fields:

a. In the Rule Class field, select Live Events.b. In the Queue field, select IN.c. In the Rule Flow field, select USER_ADD.

5. In the USER_ADD flow process, expand and select the User Add defaultgroup folder for the rule group.

6. In the right pane, expand Rules Package.7. In the Rules Package pane, select Generate Unique UserID.8. From the Actions menu, click Add. In the left pane, Generate Unique UserID

is displayed in the rule group that is named User Add default group.9. In the left pane, move Generate Unique UserID so it is located after Create

OrgUnit From User Data before Create User.10. Restart the IBM Security Identity Governance and Intelligence server.

a. On the Appliance Dashboard of the Identity Governance and Intelligencevirtual appliance console, locate the Server Control widget.

b. Select .c. Click Restart.


Restarting the adapter serviceVarious installation and configuration tasks might require the adapter to berestarted to apply the changes. For example, you must restart the adapter if thereare changes in the adapter profile, connector, or assembly lines. To restart theadapter, restart the Dispatcher.

The adapter does not exist as an independent service or a process. The adapter isadded to the Dispatcher instance, which runs all the adapters that are installed onthe same Security Directory Integrator instance.

See the topic about starting, stopping, and restarting the Dispatcher service in theDispatcher Installation and Configuration Guide.

Importing the adapter profileYou can import a profile definition file, which creates a profile in IBM SecurityIdentity Governance and Intelligence server. Use this option for importing adapterprofiles.

Before you beginv The IBM Security Identity Governance and Intelligence server is installed and

running.v You have administrator authority on the IBM Security Identity Governance and

Intelligence server.v The file to be imported must be a Java archive (JAR) file. The

<Adapter>Profile.jar file includes all the files that are required to define theadapter schema, account form, service/target form, and profile properties. Ifnecessary, you can extract the files from the JAR file, modify the files, andrepackage the JAR file with the updated files.

About this task

Target definition files are also called adapter profile files. The profile definition filesare provided with the various IBM Security Identity Adapter. The adapter profilemust be imported because it defines the types of resources that the IdentityGovernance and Intelligence server can manage.

The adapter profile definition file is used to create a target profile on the IdentityGovernance and Intelligence server and to establish communication with theadapter. If the adapter profile is not imported, you cannot create a connector forthat adapter type.

An upload error might occur when no file is selected, or when the file is empty, ordue to any upload operation error, such as a timeout or connection error. If theadapter profile is not installed correctly, the adapter cannot function correctly. Youcannot create a connector with the adapter profile or open and account on theservice. You must import the adapter profile again.

This task can be completed from the Enterprise Connectors module in theAdministration Console. To import an adapter target profile, complete these steps:

Procedure1. Log in to the Identity Governance and Intelligence Administration Console.2. From the Administration Console, select Enterprise Connectors.


3. Select Manage > Profiles.4. Optional: Click Filter to toggle the filter on to refine your search results, or

click Hide Filter to toggle the filter off. When the filter is visible, you canspecify search criteria for your requests, and then click Search.

5. Click Actions > Import.6. On the Import page, complete these steps:

a. Select Profile.b. Click Browse to locate the JAR file that you want to import.c. Click Upload file. A message indicates that you successfully imported a

profile.7. Click Close. The new profile is displayed in the list of profiles.

Results

The upload is synchronous but has a timeout. The progress bar on the Import pageaccurately indicates the upload status. However, when a timeout is reached, thefollowing message occurs: "The import is still in progress and will completeshortly. Close this window to proceed." If you see that message, allow a fewminutes for the upload to complete and for the profile to be available.

What to do next

After the target profile is imported successfully, complete these tasks.v Import the attribute mapping file. See “Importing attribute mapping file.”v Create a connector that uses the target profile. See “Adding a connector” on

page 17.

Importing attribute mapping fileAfter importing the adapter profile, you must import an attribute map from aprofile mapping definition file.

About this task

This task involves importing an account attribute mapping definition file, which isincluded in the adapter package. The imported file must be a DEF file.

Procedure1. Log in to the Identity Governance and Intelligence Administration Console.2. From the Administration Console, select Enterprise Connectors.3. Select Manage > Profiles.4. Optional: Click Filter to toggle the filter on to refine your search results, or


5. Click Actions > Import.6. On the Import page, complete these steps:

a. Select Attribute Mapping.b. Click Browse to locate the attribute mapping file that you want to import.c. Click Upload file. A message indicates that you successfully imported the

file.7. Click Close.


Adding a connectorAfter you import the adapter profile on the Identity Governance and Intelligenceserver, add a connector so that Identity Governance and Intelligence server cancommunicate with the managed resource.

Before you begin

Complete “Importing the adapter profile” on page 15.

Note: If you migrated from Identity Governance and Intelligence V5.2.2 or V5.2.2.1and want to add or configure a connector, see Adding and configuring a connector foreach target in the IBM Security Identity Governance and Intelligence productdocumentation.

About this task

The connectors consolidate, extract, and reconcile user identities, organizationunits, permissions, and user entitlements with the most common enterpriseapplications. Configure a connector to keep the Access Governance Core repositorysynchronized with the target system.

This task can be completed from the Enterprise Connectors module in theAdministration Console.

Procedure

To add a connector, complete these steps.1. Log in to the Identity Governance and Intelligence Administration Console.2. From the Administration Console, select Enterprise Connectors.3. Select Manage > Connectors. A list of connectors is displayed on the

Connectors tab.4. Optional: Click Filter to toggle the filter on to refine your search results, or


5. Optional: To view all of the columns in the list of connectors, expand theConnectors pane.

6. Click Actions > Add. The Connector Details pane is enabled for your input.7. On the Connector Details tab, complete these steps:

a. Assign a name and description for the connector.b. Select the target profile type as Identity Brokerage and its corresponding

target profile.c. Select the entity, such as Account or User. Depending on the connector

type, this field might be preselected.d. Optional: Select Trace ON and the corresponding Trace Level to enable

trace logs. The available trace levels are DEBUG, INFO, and ERROR.e. Optional: Select History ON to save and track the connector usage.f. Click Save. The fields for enabling the channels for sending and receiving

data are now visible.g. Select and set the connector properties in the Global Config accordion

pane. For information about the global configuration properties, see GlobalConfig accordion pane.


https://www.ibm.com/support/knowledgecenter/SSGHJR_5.2.3/com.ibm.igi.doc/CrossIdeas_Topics/ECONN/configureConnectorDriver.htm

https://www.ibm.com/support/knowledgecenter/SSGHJR_5.2.3/com.ibm.igi.doc/CrossIdeas_Topics/ECONN/configureConnectorDriver.htm

h. Click Save. The fields for enabling the channels for sending and receivingdata are now visible.

Results

The connector is saved and added to the list of connectors in the Connectors pane.

If you cannot create a connector with the target profile or open an account on anexisting connector, the target profile was not installed correctly during the import.You must import the target profile again.

What to do next

Enable the channel modes to synchronize the data between the target systems andIdentity Governance and Intelligence. For more information, see “Enablingconnectors.”

Enabling connectorsAfter you create a connector, by default it is in a disabled state. You must enable aconnector to use it.

Before you begin

Table 4. Prerequisites for enabling a connector

Prerequisite Find more information

A connector must exist in IdentityGovernance and Intelligence.

“Adding a connector” on page 17.

Ensure that you enabled the appropriatechannel modes for the connector.

“Reviewing and setting channel modes foreach new connector” on page 19.

Procedure

To enable a connector, complete these steps:1. Log in to the Identity Governance and Intelligence Administration Console.2. From the Administration Console, select Enterprise Connectors.3. Select Manage > Connectors. A list of connectors is displayed on the




6. Select the connector that you want to enable.7. On the Connector Details tab, complete these steps:

a. Select the channel modes that you want to enable, and then click Save.Depending on the channels that you enable, the corresponding Channeltabs are displayed.

Enable write-to channelPropagates every change in the Access Governance Core repositoryinto the target system.


For connectors that are not HR feed, the check boxes for enablingthe read-from channel and the write-to channel are available.

Enable read-from channelReads the INPUT EVENTS and USER DATA from the target system.Imports data from the target system to the Access Governance Corerepository.

For HR feed connectors, only the check box for enabling theread-from channel is available.

Enable reconciliationSynchronizes the modified data between the Access GovernanceCore repository and the target system.

Results

The connector is enabled

What to do next

Enable the channel modes to synchronize the data between the target systems andIdentity Governance and Intelligence.

Reviewing and setting channel modes for each new connectorUse this procedure to set up the read-from and write-to channels and to set thesynchronization schedule for each new connector.

About this task

Note: Legacy Identity Governance and Intelligence Enterprise connectors useReconciliation channel, whereas Identity Brokerage Enterprise connectors useRead From Channel and Change Log Sync.

For more information about any of tasks in the following steps, see the IBM®

Security Identity Governance and Intelligence product documentation.

Procedure

To enable the read-from and write-to channels, and to set the change logsynchronization schedule for each new connector, complete these steps in IdentityGovernance and Intelligence V5.2.3:1. Log in to the Identity Governance and Intelligence Administration Console.2. From the Administration Console, select Enterprise Connectors.3. Select Manage > Connectors. A list of connectors is displayed on the




6. Select the connector that you want to enable.7. On the Connector Details tab, complete these steps:


a. Select the channel modes that you want to enable, and then click Save.Depending on the channels that you enable, the corresponding Channeltabs are displayed, in which you can do more configuration, such asmapping attributes and setting up rules.

Enable write-to channelPropagates every change in the Access Governance Core repositoryinto the target system.

Enable read-from channelReads the INPUT EVENTS and USER DATA from the targetsystem. Imports data from the target system to the AccessGovernance Core repository.

Enable reconciliationSynchronizes the modified data between the Access GovernanceCore repository and the target system.

8. Select Monitor > Change Log Sync Status. A list of connectors is displayed.9. On the Change Log Sync Status tab, complete these steps:

a. Optional: Click Filter to toggle the filter on to refine your search results, orclick Hide Filter to toggle the filter off. When the filter is visible, you canspecify search criteria for your requests, and then click Search.

b. Select a connector, and click Actions > Sync Now. The synchronizationprocess begins.

c. Optional: To view the status of the synchronization request, select SyncHistory in the right pane. Information about the synchronization isdisplayed in the Sync History tab.

10. Set the change log synchronization schedule for each new connector that youmigrated.

11. When the connector configuration is complete, enable the connector bycompleting these steps:a. Select Manage > Connectors.b. Select the connector that you want to enable, and then select the Enable

check box in the Connector Details tab.c. Click Save. For more information, see “Enabling connectors” on page 18.

For Identity Brokerage connectors that are not HR feed, the check boxes forenabling the read-from channel and the write-to channel are available.For Identity Brokerage HR feed connectors, only the check box for enablingthe read-from channel is available.

12. Start the connector by selecting Monitor > Connector Status. Select theconnector that you want to start, and then select Actions > Start.

Attribute MappingAttribute mapping is required to define which target attributes correspond to theIdentity Governance and Intelligence user or OU attributes.

About this task

This task involves either an user or OU attribute mapping definition file, which areboth included in the HR adapter package.


The file consists of Identity Governance and Intelligence user or OU attributes andtheir equivalent attributes in the managed HR target. The file is structured as<IGI_attribute> = <HR_target_attribute>.

The <IGI_attribute> is fixed and must not be modified. Edit only the<HR_target_attribute>. Some <IGI_attribute> already has a fixed equivalent<HR_target_attribute> of ersaphraccount. For example:GIVEN_NAME=ersaphrgivenname

Some <IGI_attribute> do not have a defined <HR_target_attribute> and you canassign the mapping. For example:USER_TYPE=USER_TYPEATTR1=ATTR1

Note:

v The default mapping is already included out-of-the box. If there are no changesto the attribute mapping, there is no need to import the attribute mapping files.

v It might take up to 10 minutes for the attribute mapping changes to take effectonce the file is imported.

Procedure1. Open the mapping definition file by using any text editor.2. Edit the mapping.3. If the target attribute has a list of predefined values, use the following syntax to

convert its values to the corresponding Identity Governance and Intelligenceattribute values.[conversion].<HR_target_attribute>.<IGI_attribute> =[<HR_target_attribute_value1>=<IGI_attribute_value1>;...;<HR_target_attribute_valuen>=<IGI_attribute_valuen>]

For example:[conversion].ersaphrgender.GENDER=[M=0;F=1;U=]

[conversion].erptigidisabled.DISABLED=[Y=1;N=0][conversion].erptigigender.GENDER=[M=0;F=1]

4. For attributes that contains date and time, use the following syntax to convertits values. For example:[conversion.date].ersaphrdob.BIRTHDAY=[yyyyMMdd=dd/MM/yyyy HH:mm:ss][conversion.date].ACCOUNT_EXPIRY_DATE.ACCOUNT_EXPIRY_DATE=[dd/MM/yyyy HH:mm:ss=dd/MM/yyyy HH:mm:ss]

5. Import the updated mapping definition file through the Enterprise Connectorsmodule. For more information, see Attribute-to-permission mapping service in theIBM Security Identity Governance and Intelligence product documentation.

Service/Target form detailsComplete the service/target form fields.

The SAP HR feed adapter service form has several tabs, each containinginformation that you must specify:v Adapter Details tabv SAP Connection Details tabv “Reconciliation Advanced Mapping tab” on page 22v Dispatcher Attributes tab


Adapter Details tabThis tab describes service details.

Service nameSpecify a name that defines this service on the IBM Security IdentityGovernance and Intelligence Server.

Note: Slash (/) and backslash (\) characters are not allowed in the servicename.

Description Optional: Specify a description for this service.

IBM Tivoli Directory Integrator location

Optional: Specify the URL for the IBM Tivoli Directory Integrator instance.

Valid syntax is rmi://ip-address:port/ITDIDispatcher, where ip-address isthe IBM Tivoli Directory Integrator host and port is the port number for theDispatcher. For example, rmi://localhost:1099/ITDIDispatcher.

For information about changing the port number, see the DispatcherInstallation and Configuration Guide.

Service prerequisitePrerequisite services names.

OwnerService owner.

SAP Connection Details tabThis tab describes the parameters that have to be specified to establish a remoteconnection to the SAP resource from IBM Tivoli Directory Integrator.

Target ClientThe SAP instance client number. This field is mandatory.

Login IDThe SAP User account login ID that adapter uses to connect to the SAPinstance. This field is mandatory.

Password Password for SAP User account. This field is mandatory.

SAP System (DNS hostname or IP)Host name of the SAP server host computer only if DNS is set up correctly.Otherwise, use the IP address. This field is mandatory.

SAP Systems Number The SAP server system number. This field is mandatory.

SAP Logon Language The language ISO identifier to be used by the adapter. This parameter isoptional.

Reconciliation Advanced Mapping tabSettings in this tab apply only during reconciliation and search operation requests.

The following attributes of this tab are all optional service attribute.v Search Person Basic Iterate Request XSL Stylesheetsv Search Person Basic Iterate Response Stylesheet


Dispatcher Attributes tabThis tab describes Dispatcher attributes.

Assembly Line File System Path

Specify the file path from where the Dispatcher loads the assembly lines. Ifyou do not specify a file path, the Dispatcher loads the assembly lines thatare received from IBM Security Identity Governance and Intelligence.

For example:

Windows operating systemC:\Files\IBM\TDI\V7.2\profiles

UNIX and Linux operating system/opt/IBM/TDI/V7.2/profiles

Max Connection Count

Specify the maximum number of assembly lines that the Dispatcher canexecute simultaneously for the service.

For example, enter 10 if you want the Dispatcher to execute a maximum of10 assembly lines simultaneously for the service. If you enter 0, theDispatcher does not limit the number of assembly lines that are executedsimultaneously for the service.

Assembly lines occupy the JVM memory. Too many assembly lines cancause an out-of-memory scenario in the IBM Tivoli Directory Integratorserver. Each assembly line also creates multiple connections to the endpoint. The end point might have a limit on the number of remoteconnections allowed. As such, the adapter requests might fail.

Disable Assembly Line Cache

Select the check box to disable the assembly line caching in the Dispatcherfor the service. When disabled, the assembly lines for the Add, Modify,Delete, and Test operations are not cached.

Select the check box if the requirement is to enable caching. When enabled,the entire assembly line object is saved in the cache. The connection to theSAP resource is maintained. The next request that the adapter receives canreuse this connection.

Creating a new connection to the SAP resource can take a lot of time.Caching data can save time and resource utilization.

Verifying that the adapter is working correctlyAfter you install and configure the adapter, verify that the installation andconfiguration are correct.

Procedure1. Test the connection for the service that you created on the IBM Security Identity

Governance and Intelligence server.2. Run a full reconciliation from the IBM Security Identity Governance and

Intelligence server.3. Run all supported operations such as add, modify, and delete on one user

account.4. Verify the ibmdi.log file after each operation to ensure that no errors are

reported.


5. Verify the trace.log file to ensure that no errors are reported when you run anadapter operation.


Chapter 4. Upgrading

Upgrading an IBM Tivoli Directory Integrator-based adapter involves tasks such asupgrading the dispatcher, the connector, and the adapter profile. Depending on theadapter, some of these tasks might not be applicable. Other tasks might also berequired to complete the upgrade.

See the Release Notes for the supported software versions or for specificinstructions.

To upgrade the connector, see “Installing the adapter binaries or connector” onpage 9.

Upgrading the DispatcherThe new adapter package might require you to upgrade the Dispatcher.

Before you upgrade the Dispatcher, verify the version of the Dispatcher.v If the Dispatcher version that is mentioned in the release notes is later than the

existing version on your workstation, install the Dispatcher.v If the Dispatcher version that is mentioned in the release notes is the same or

earlier than the existing version, do not install the Dispatcher.

Note: The Dispatcher installer stops the Dispatcher service before the upgrade andrestarts it after the upgrade is complete.

Upgrading the adapter profileRead the adapter Release Notes for any specific instructions before you import anew adapter profile.

Note: Restart the Dispatcher service after importing the profile. Restarting theDispatcher clears the assembly lines cache and ensures that the dispatcher runs theassembly lines from the updated adapter profile.

25


Chapter 5. Configuring

After you install the adapter, configure it to function correctly. Configuration isbased on your requirements or preference.

See the IBM Security Dispatcher Installation and Configuration Guide for additionalconfiguration options such as:v JVM propertiesv Dispatcher filteringv Dispatcher propertiesv Dispatcher port numberv Logging configurationsv Secure Sockets Layer (SSL) communication

Customizing the adapter profileYou can customize the adapter profile to change the account form or the serviceform. To customize the adapter profile, you must modify the adapter JAR file.

About this task

Use the Form Designer or the CustomLabels.properties file to change the labels onthe forms. Each adapter has a CustomLabels.properties file.

The JAR file is included in the adapter package that you downloaded from theIBM Passport Advantage website. The JAR file and the files in the JAR file varydepending on your operating system.

Note: You cannot modify the schema for this adapter. You cannot add or deleteattributes from the schema.

The adapter JAR file includes the following files:v CustomLabels.properties

v erSapHRAccount.xml

v erSapHRService.xml

v SapHRSearch.xml

v SapHRTest.xml

v schema.dsml

v service.def

Procedure1. Edit the JAR file.

a. Log on to the workstation where the SAP HR feed adapter is installed.b. On the Start menu, select Programs → Accessories → Command Prompt.c. Copy the JAR file into a temporary directory.d. Extract the contents of the JAR file into the temporary directory by running

the following command. The following example applies to the SAP HR feedadapter profile. Type the name of the JAR file for your operating system.

27

cd c:\temp cd /tmpjar -xvf SapHRProfile.jar

The jar command extracts the files into the SapHRProfile directory.e. Edit the file that you want to change

After you edit the file, you must import the file into the IBM SecurityIdentity server for the changes to take effect.

2. Import the file.a. Create a JAR file by using the files in the directory. Run the following

commands:

Windowscd c:\tempjar -cvf SapHRProfile.jar SapHRProfile

UNIXcd /tmpjar -cvf SapHRProfile.jar SapHRProfile

b. Import the JAR file into the IBM Security Identity Governance andIntelligence application server.

c. Stop and start the IBM Security Identity server.d. Restart the adapter service.

XSL stylesheetsThe adapter can be configured by modifying the XSL stylesheet advancedmappings.

The adapter can function without configuring any advanced mapping XSLtransformations. The default values for each advanced mapping are used. Anyadvanced mappings that are configured by the user, override the listed default XSLtransformations.

RECONCILIATION ADVANCED MAPPING TABSettings of this tab apply only during reconciliation and search operationrequests.

Search Person Basic Iterate Request XSL Stylesheet

This attribute is a multi-valued attribute. The value is a list of XSLtransformation file names that are separated by space (“ ”).

Each transform is run in the defined order and produce an RFCrequest. Each RFC request is run by the adapter. Each RFC that isrun is responsible for returning parts of the user account details.

If more than one transform and resulting RFC is run, the result ofeach RFC call is appended to an XML result document with a roottag named <bapiResults>. This result list is passed to the SearchPerson Basic Iterate Request XSL Stylesheet. If only one XSL filename is supplied, the resulting RFC is run. The response is passeddirectly to Search Person Basic Iterate Request XSL Stylesheet.

Each XSL transform file must be deployed with the adapter in thexsl directory relative to the Dispatcher solution directory.

If no value is supplied, the adapter runs the following XSLtransformations and resulting RFC calls:


xsl/sapnw_bapi_person_getdetail_precall.xslxsl/sapnw_bapi_person_address_precall.xslxsl/sapnw_bapi_person_email_precall.xsl

Search Person Basic Iterate Response Stylesheet

This attribute is a single-valued attribute. The value is the filename of an XSL transformation that processes the SAP response orresponses from the RFC calls. The calls are run based on thesetting of Search Person Basic Iterate Response Stylesheet. Theresult of running this transform is sent to the IBM Security IdentityGovernance and Intelligence server.

The XSL transform file must be deployed with the adapter in thexsl directory relative to the Dispatcher solution directory.

If no value is supplied, the adapter runs the following XSLtransformation and resulting RFC call:sapnw_bapi_person_getdetail_postcall.xsl

BAPI method execution with stateful connectionThe SAP JCo 3.x connection between SAP R3 and IBM Security IdentityGovernance and Intelligence, is not stateful by default. The stateful connection isrequired in case of transactional BAPIs.

To make the connection stateful between Business Application ProgrammingInterfaces (BAPIs) method execution, add the following tags to the XSL filesaccording to your requirement.

To begin a stateful connection, add this tag to your XSL:<CONTEXT_BEGIN> & </CONTEXT_BEGIN> or <CONTEXT_BEGIN/>

To end a stateful connection, add this tag to your XSL:<CONTEXT_END> & </CONTEXT_END> or <CONTEXT_END/>

It is not necessary to have both <CONTEXT_BEGIN/> and <CONTEXT_END/> tags in thesame XSL. Nested <CONTEXT_BEGIN/> and <CONTEXT_END/> tags can also beimplemented, if the tags are nested correctly, else unexpected result can occur.Stateful connection started by each <CONTEXT_BEGIN/> tag gets ended by itsassociated <CONTEXT_END/> tag.

Note: Stateful connection that is started by each <CONTEXT_BEGIN/> tag gets endedby its associated <CONTEXT_END/> tag. If the <CONTEXT_BEGIN/> tag does not haveits associated <CONTEXT_END/> tag, the stateful connection gets terminated at theend of JCo connection.

For example, the <CONTEXT_BEGIN/> and <CONTEXT_END/> tags are added to thefollowing files:v sapnw_bapi_charact_create.xsl file

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"version="1.0"xmlns:xalan="http://xml.apache.org/xslt">

.....

.....<BAPI_CHARACT_CREATE><CONTEXT_BEGIN/>..........

Chapter 5. Configuring 29

</BAPI_CHARACT_CREATE>..........</xsl:stylesheet>

v sapnw_bapi_transaction_commit.xsl file<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

version="1.0"xmlns:xalan="http://xml.apache.org/xslt">

.....

.....<BAPI_TRANSACTION_COMMIT>..........<CONTEXT_BEGIN/></BAPI_TRANSACTION_COMMIT>..........</xsl:stylesheet>

Improving the reconciliation operation performanceUse the Java settings to improve the performance of the reconciliation operation.

Procedure1. Navigate to the JAVA_Home/lib directory.2. Rename jaxp.properties.sample to jaxp.properties.3. In the jaxp.properties file, remove the comment tags for the following

properties:javax.xml.transform.TransformerFactory=

com.ibm.xtq.xslt.jaxp.compiler.TransformerFactoryImpljavax.xml.xpath.XPathFactory=

org.apache.xpath.jaxp.XPathFactoryImpljavax.xml.parsers.SAXParserFactory=

org.apache.xerces.jaxp.SAXParserFactoryImpljavax.xml.parsers.DocumentBuilderFactory=

org.apache.xerces.jaxp.DocumentBuilderFactoryImpl

4. Check the performance of the reconciliation operation. If it fails, continue tostep 5.

5. Set the following system property:export IBM_JAVA_OPTIONS=-Djavax.xml.transform.TransformerFactory=

org.apache.xalan.processor.TransformerFactoryImpl

6. Check the performance of the reconciliation operation again.For more information about the settings, see the following resources:

http://xalan.apache.org/xalan-j/usagepatterns.html

http://www-03.ibm.com/systems/z/os/zos/tools/xml/perform/performjava.html

http://publib.boulder.ibm.com/infocenter/javasdk/v1r4m2/index.jsp?topic=%2Fcom.ibm.java.doc.user.aix64.142%2Fhtml%2Fsdkguide.aix64.htm


http://xalan.apache.org/xalan-j/usagepatterns.html






Chapter 6. Troubleshooting

Troubleshooting is a systematic approach to solving a problem. The goal oftroubleshooting is to determine why something does not work as expected andhow to resolve the problem. This topic provides information and techniques foridentifying and resolving problems that are related to the adapter, includingtroubleshooting errors that might occur during the adapter installation.

Techniques for troubleshooting problemsCertain common techniques can help with the task of troubleshooting. The firststep in the troubleshooting process is to describe the problem completely.

Problem descriptions help you and the IBM technical-support representative findthe cause of the problem. This step includes asking yourself basic questions:v What are the symptoms of the problem?v Where does the problem occur?v When does the problem occur?v Under which conditions does the problem occur?v Can the problem be reproduced?

The answers to these questions typically lead to a good description of the problem,which can then lead you to a problem resolution.

What are the symptoms of the problem?

When you start to describe a problem, the most obvious question is “What is theproblem?” This question might seem straightforward; however, you can break itdown into several more-focused questions that create a more descriptive picture ofthe problem. These questions can include:v Who, or what, is reporting the problem?v What are the error codes and messages?v How does the system fail? For example, is it a loop, hang, crash, performance

degradation, or incorrect result?

Where does the problem occur?

Determining where the problem originates is not always easy, but it is one of themost important steps in resolving a problem. Many layers of technology can existbetween the reporting and failing components. Networks, disks, and drivers areonly a few of the components to consider when you are investigating problems.

The following questions help you to focus on where the problem occurs to isolatethe problem layer:v Is the problem specific to one operating system, or is it common across multiple

operating systems?v Is the current environment and configuration supported?v Do all users have the problem?v (For multi-site installations.) Do all sites have the problem?

31

If one layer reports the problem, the problem does not necessarily originate in thatlayer. Part of identifying where a problem originates is understanding theenvironment in which it exists. Take some time to completely describe the problemenvironment, including the operating system and version, all correspondingsoftware and versions, and hardware information. Confirm that you are runningwithin an environment that is a supported configuration. Many problems can betraced back to incompatible levels of software that are not intended to run togetheror are not fully tested together.

When does the problem occur?

Develop a detailed timeline of events that lead up to a failure, especially for thosecases that are one-time occurrences. You can most easily develop a timeline byworking backward: Start at the time an error was reported (as precisely as possible,even down to the millisecond), and work backward through the available logs andinformation. Typically, you use the first suspicious event that you find in adiagnostic log.

To develop a detailed timeline of events, answer these questions:v Does the problem happen only at a certain time of day or night?v How often does the problem happen?v What sequence of events leads up to the time that the problem is reported?v Does the problem happen after an environment change, such as upgrading or

installing software or hardware?

Responding to these types of questions can give you a frame of reference in whichto investigate the problem.

Under which conditions does the problem occur?

Knowing which systems and applications are running at the time that a problemoccurs is an important part of troubleshooting. These questions about yourenvironment can help you to identify the root cause of the problem:v Does the problem always occur when the same task is being done?v Is a certain sequence of events required for the problem to occur?v Do any other applications fail at the same time?

Answering these types of questions can help you explain the environment inwhich the problem occurs and correlate any dependencies. Remember that justbecause multiple problems might occur around the same time, the problems arenot necessarily related.

Can the problem be reproduced?

From a troubleshooting standpoint, the ideal problem is one that can bereproduced. Typically, when a problem can be reproduced you have a larger set oftools or procedures at your disposal to help you investigate. Problems that you canreproduce are often easier to debug and solve.

However, problems that you can reproduce can have a disadvantage: If theproblem is of significant business impact, you do not want it to recur. If possible,re-create the problem in a test or development environment, which typically offersyou more flexibility and control during your investigation.v Can the problem be re-created on a test system?


v Do multiple users or applications have the same type of problem?v Can the problem be re-created by running a single command, a set of

commands, or a particular application?

LogsWhen the adapter is initially configured, a default directory is selected to store thelog files that record the adapter activities. Logs can help you determine thebackground or cause of an issue and to find the proper solution.<Log Level> [<Assembly Line_ProfileName>_<Request Id>]_[<Connector Name>] - <message>

Log LevelSpecifies the logging level that you configured for the adapter. The optionsare DEBUG, ERROR, INFO, and WARN. For information about using thelog4j.properties file to configure logging, see the Dispatcher Installationand Configuration Guide.

Assembly LineSpecifies the name of the assembly line that is logging the information.

ProfileNameSpecifies the name of the profile. Profile names can vary based on theadapter that is running or the operating system.

Request IDSpecifies the number of the request. The Request ID is used to uniquelyidentify a specific request.

Connector NameSpecifies the adapter connector.

MessageSpecifies the informational message.

When you click the Test button on the SAP HR feed adapter service form, theservice, environment, and configuration values are sent to the IBM Tivoli DirectoryIntegrator log during the test. These collected information can help diagnoseissues.

Error messages and problem solvingA warning or error message might be displayed in the user interface to provideinformation about the adapter or when an error occurs.

The following table contains warnings or errors, which might be displayed whenthe SAP HR feed adapter is installed on your system.

Chapter 6. Troubleshooting 33

Table 5. Specific warning and error messages and actions

Message Action

Test Connection Fails: CTGIMU107WThe connection to the specified service cannotbe established. Verify the service information,and try again.

ibmdi.logCTGIMT401E An error occurred while startingthe AssemblyLines/SapHRTest_SAP -TV2_test-no-requestid_9dbf1884-29b1-11b2-689a-00000a020011 agent. Error:java.lang.ExceptionInInitializerError: Errorgetting the version of the native layer:java.lang.UnsatisfiedLinkError: sapjco3 (Notfound in java.library.path) operation on theIBM Tivoli Directory Integrator server. Error:{1}

The Microsoft Visual C++ 2005libraries are not installed, or thepermissions for the .dll file arenot correct. Verify the installationsteps and permissions.


ibmdi.logCTGDIS067E Unable to find configuration forAssemblyLine SapHRTest_SAP_R/3_NW_test-no-requestid_c41b1d60-28f8-11b2-e832-00001ff87342.]

The service name might containspecial characters that IBM TivoliDirectory Integrator can nothandle. For example, “/”.


ibmdi.logCTGDIS809E handleException - cannot handleexception , scriptjava.lang.NoClassDefFoundError:com.sap.conn.jco.ext.DestinationDataProvider

SAP JCo is not installed, orpermissions for the .jar file are notcorrect. Verify the installationsteps and permissions.

Test Connection Fails: CTGIMU107W The connection to the specified service cannotbe established. Verify the service information,and try again.

ibmdi.logCaused by: java.io.FileNotFoundException:app/itdi611/solution/xsl/sapnw_bapi_errors.properties (No such file ordirectory)

The property and .xsl files werecopied to the wrong directoryduring the adapter installation, orfile permissions are not correct.Verify the installation steps andpermissions.


Table 5. Specific warning and error messages and actions (continued)

Message Action


ibmdi.logCTGDIS809E handleException - cannot handleexception , scriptjava.lang.ExceptionInInitializerError: Errorgetting the version of the native layer:java.lang.UnsatisfiedLinkError: sapjco3 (Notfound in java.library.path)

The path for the SAP JCodynamic library is not correct.

Correct it and restart the IBMSecurity Identity Governance andIntelligence adapter service.


ibmdi.logException Class:org.xml.sax.SAXParseExceptionorg.xml.sax.SAXParseException:Invalid byte 1 of 1-byteUTF-8 sequence.

Java property"–Dfile.encoding=UTF-8" needs tobe added.

Add the property as described inthe Installation and ConfigurationGuide, and Release Notes.

Restart the IBM Security IdentityGovernance and Intelligenceadapter service.

Chapter 6. Troubleshooting 35

Table 5. Specific warning and error messages and actions (continued)

Message Action

Reconciliation doesn't return all SAP accounts.Reconciliation is successful but some accounts aremissing.

For the adapter to reconcile alarge number of accountssuccessfully, you might need toincrease Websphere's JVMmemory. Complete the followingsteps on the WebSphere® hostmachine:Note: Do not increase the JVMmemory to a value higher thanthe system memory.

1. Log in to the WebSphereAdministrative Console.

2. From the left menu, selectServers and then ApplicationServers. A table displays thenames of known applicationservers on your system.

3. Click the link for yourprimary application server.

4. On the Configuration tab,select Process Definition.

5. Select the Java VirtualMachine property.

6. Enter a new value forMaximum Heap Size. Thedefault value is 256 MB.

If the allocated JVM memory isnot large enough, the attempt toreconcile a large number ofaccounts using the IBM SecurityAccess Manager adapter willresult in log file errors. Thereconciliation process will notcomplete successfully. The adapterlog files will contain entries thatstate ErmPduAddEntry failed. TheWebSphere_install_dir/logs/itim.log file will containjava.lang.OutOfMemoryErrorexceptions.


Chapter 7. Uninstalling

To remove an adapter from the IBM Security Identity server for any reason, youmust remove all the components that were added during installation. Uninstallingan IBM Tivoli Directory Integrator-based adapter mainly involves removing theconnector file and the adapter profile from the IBM Security Identity server.Depending on the adapter, some of these tasks might not be applicable, or therecan be other tasks.

Procedure1. Stop the IBM Security Identity Governance and Intelligence Dispatcher Service.2. Remove the SAP HR feed adapter JAR files.

a. Delete SapHRProfile.jar and SAPNWConnector.jar, SAPNWUserConnector.jarfrom the ITDI_HOME/jars/connectors directory.

b. Delete SapNWRfc.jar from the ITDI_HOME/jars/functions directory.

Note: If you are using this IBM Tivoli Directory Integrator to provision to aSAP NetWeaver target then do not delete theSAPNWConnector.jar,SAPNWUserConnector.jar and SapNWRfc.jar.

3. Remove the adapter stylesheets from the ITDI_HOME/solution/xsl directory.4. Delete the adapter profile from the IBM Security Identity Governance and

Intelligence server.

Note: The Dispatcher component must be installed on your system for theadapter to function correctly in a IBM Tivoli Directory Integrator environment.When you delete the adapter profile for the SAP HR feed adapter, do notuninstall the Dispatcher.

37


Chapter 8. Reference

Reference information is organized to help you locate particular facts quickly, suchas adapter attributes, registry settings, and environment variables.

Adapter attributes and object classesThe IBM Security Identity server communicates with the adapter by usingattributes, which are included in transmission packets that are sent over a network.

The SAP HR feed adapter supports a standard set of attributes.

Table 6. Supported attributes

Attribute Name Description RequiredManaged ResourceAttribute

erUid Employee number YES PERNR

ersaphrgivenname First name of person NO FIRSTNAME

ersaphrlastname Last name of person NO LASTNAME

ersaphrgender Gender NO GENDER

ersaphrdob Date of birth NO DATEOFBIRTH

ersaphrbirthplace Place of birth NO BIRTHPLACE

ersaphrbirthcountry Country of birth NO COUNTRYOFBIRTH

ersaphrzipcode Zip Code NO POSTALCODECITY

ersaphrcountry Country NO NAMEOFCOUNTRY

ersaphrphoneno Phone number NO TELEPHONENUMBER

ersaphraddress Address NO STREETANDHOUSENO

ersaphrcity City NO DISTRICT

ersaphremailid Email ID NO EMAIL

ersaphrpersonou Organizational unit NO ORGANIZATION NAME

USER_ERC attribute mapping

The following table lists which adapter attributes are mapped to the attributesstored in the IBM Security Identity Governance and Intelligence USER_ERC table.

Table 7. USER_ERC attribute mapping

USER_ERC attributes Description RequiredSAP HR feed adapterattribute name

ID Table unique identifier.

The sequence user_erc_seqmight be called to generatethis unique number.

YES

39

Table 7. USER_ERC attribute mapping (continued)


PM_CODE USER ID or User Code.

It is not required. USER IDcan be generated using arule.

NO

OU Organizational unit code.

Used to store the user inthe OU available in thesystem.

This attribute might ormight not be in thedatabase. Create the newOU in the root.

YES ersaphrpersonou

USER_TYPE User type name.

This attribute might ormight not be in thedatabase. It can be createddynamically using a customrule.

NO

PROCESSED Deprecated NO

LAST_MOD_USER Contains the name of thelast user or process thatmodified the USER_ERCtable.

NO

LAST_MOD_TIME Contains the date and timewhen the last changeoccurred.

Default format isdd/MM/yyyy HH:mm:ss.Format can be changed.

NO

POST_EVENT Deprecated NO

SKIP Deprecated NO

ACTION_TYPE SAP HR propertyinformation.

NO

ACTION_CAUSE SAP HR propertyinformation.

NO

ACTION_TYPE_LAST SAP HR propertyinformation.

NO

ACTION_CAUSE_LAST SAP HR propertyinformation.

NO

GIVEN_NAME User name YES ersaphrgivenname

SURNAME User surname YES ersaphrlastname

GENDER v 0 = male

v 1 = female

NO ersaphrgender

BIRTHDAY Birthday NO ersaphrdob

BIRTH_PLACE Birth place NO ersaphrbirthplace




BIRTH_COUNTRY Birth country NO ersaphrbirthcountry

ACCOUNT_EXPIRY_DATE The Identity Governanceand Intelligence accountcan be created with anexpiration date.


NO

IDENTIFICATION_NUMBERUser ID present into HRsystem

NO eruid

CURRENTOU Deprecated NO

NATION Nation NO

ZIPCODE Zip code NO ersaphrzipcode

COUNTRY Country NO ersaphrcountry

PHONE_NUMBER Phone number NO ersaphrphoneno

DISABLED Indicates that the user isdisabled and it disables alluser accounts

NO

DELETED Use this attribute toimplement a particularlogic when a user is deletedfrom HR system.

For example, a user cankeep all his account for 3weeks and then the user isdeleted

NO

ATTR1 Spare attribute NO















SCHEDULE Deprecated NO

ADDRESS User address NO ersaphraddress

Chapter 8. Reference 41



CITY User city NO ersaphrcity

EMAIL User email NO ersaphremailid

OrganizationalUnit_ERC attribute mapping

The following table lists which adapter attributes are mapped to the attributesstored in the IBM Security Identity Governance and IntelligenceOrganizationalUnit_ERC table.

Table 8. OrganizationalUnit_ERC attribute mapping

OrganizationalUnit_ERCattributes Description Required

SAP HR feed adapterattribute name

ID Table unique identifier.

The sequenceorganizational_unit_erc_seqmight be called to generatethis unique number.

YES

PARENT Organizational unit parentcode

This attribute might ormight not be in thedatabase. Create the newOU in the root.

NO

OU Organizational unit code(unique identifier)

YES ersaphrorgid

DESCRIPTION Description NO ersaphrorgdesc

NAME Organizational unit name YES ersaphrorgname

LAST_MOD_USER Contains the name of thelast user or process thatmodified the USER_ERCtable.

NO

LAST_MOD_TIME Contains the date and timewhen the last changeoccurred.


NO

TIPO Organizational unit typename.

This attribute might ormight not be in thedatabase. It can be createddynamically using a customrule.

NO

SCHEDULE Deprecated NO



Table 8. OrganizationalUnit_ERC attribute mapping (continued)

OrganizationalUnit_ERCattributes Description Required

SAP HR feed adapterattribute name















Adapter configuration propertiesTo set the IBM Tivoli Directory Integrator configuration properties for theoperation of the SAP HR feed adapter, see the Dispatcher Installation andConfiguration Guide.

Chapter 8. Reference 43


Index

Aaccount

management automation 1adapter

account management automation 1attribute 39customization steps 27details tab, attributes 22features 1installation 9installation worksheet 8profile

upgrading 25stylesheets 9supported configurations 2uninstall 37

after installation 27automation, account management 1

Cconfiguration

properties 43CUA

status 28

Ddispatcher

installation 9Dispatcher 1

attributes tab 23location 9upgrades 25

Dispatcher JVM properties 12download, software 7

Eerror messages 33

Ffirst steps 27

Iinstallation

adapter 9preparation 5troubleshooting 31uninstall 37verify 13worksheet 8

JJCo pachage 10

Llog level 33logging information format 33

Oobject classes 39operating system prerequisites 7overview of the adapter 1

Pperformance 30

Rreconciliation

advanced mapping tab, serviceattribute 22

operation 30runtime 33

SSAP connection details tab, attributes 22SAP Java Connector (JCo) 10SAP NetWeaver Adapter

overview 1properties 43upgrade 25

SAP RFC 28service

restart 15start 15stop 15

softwaredownload 7requirements 7website 7

supported configurationsadapter 2overview 2

Ttivoli directory integrator connector 1troubleshooting

adapter installation 31identifying problems 31techniques for 31

troubleshooting and supporttroubleshooting techniques 31

Uunicode 12uninstallation 37

updatingadapter profile 27

upgradesadapter profiles 25Dispatcher 25

Vverification

dispatcher installation 9installation 13operating system

prerequisites 7requirements 7

softwareprerequisites 7requirements 7

XXSL stylesheets 28

45


IBM®

Printed in USA

Documents

IBM Security Identity Governance and Intelligence: …public.dhe.ibm.com/.../isim/adapters/igi/igi_sap_hr_book.pdfSAP Netweaver Application Server ABAP with SAP Basis Component with