Problem

Novell Identity Manager has a number of drivers to connect to a variety of systems. One example driver is the SAP HR system driver. This connects the SAP Human Resources system to eDirectory, so that as users get hired they can be provisioned into eDirectory, and then as they change from Human Resources perspective, the change will propogate to eDirectory.

SAP is a large, complicated system. The driver uses two different interfaces, one for the Publisher channel (iDOCS) and the other for the Subscriber channel (JConnect).

The Publisher channel monitors a specific directory in the file system. The driver watches for files being placed there and interprets them as they come in. Much like the Delimited Text Driver, which looks for text files, the Publisher channel looks for a specific format called iDOCs (Intermediate Documents) that are well known in the EDI (Electronic Data Interchange) world.

The Subscriber channel uses Jconnect, a SAP-specific protocol library, and needs to use Java libraries from SAP. Getting the file is discussed in the article: http://www.novell.com/communities/node/2792/idm-sap-hr-driver-where-get-jconnect-libraries

At the end of that document I mention that you need to watch the version of the libraries that you get, depending on the operating system and the bit depth of the operating system. SAP runs on a number of operating systems: 32-bit and 64-bit. If the host operating system that the remote loader will be running on is 32-bit or 64-bit, you need to get the matching library set. There are actually two components, a Java library and a native library.

The problem that can arise is that there are several versions of the Remote Loader you can use (see article: http://www.novell.com/communities/node/2994/many-faces-remote-loaders-idm). The fancy, thick Remote Loader includes a JVM from Novell, and it turns out this is a 32-bit 1.5 JVM (depends on the version of IDM as to which JVM specifically is included, but as of this moment they are all 32-bit), which normally is a non-issue.

In the case of the SAP Jconnect libraries, you need to match the JVM to the OS to the versions of the library. In the end, the best way to configure this would be to use the stripped down remote loader, the dirxml_jremote.

The issue is that the JVM included with the Remote Loader is a 32-bit JVM that tries to use a Java class (in sapjco.jar) that calls a native library (libsapjcorfc.so). The library has to match the bit depth of the calling Java class. The dirxml_jremote lets you choose the JVM to use, and then get all the libraries match correctly.

What makes this problem trickier to troubleshoot, is that Novell includes a great test tool, a Java class called JCOTest. The documentation tells you how to use it, but in that case, you use the default native JVM with the libraries you installed. So, on a 64 bit OS (I was using AIX when I ran into this), the default JVM is usually a 64-bit JVM, with the 64-bit Jconnect libraries, and it works fine. However, when you try to use the standard Remote Loader, it will fail to load, with an error in the engine trace of:

Driver: \ACME-DEV\acme\services\idm\IDMSet\SAP-HR351
Channel: Publisher
Status: Fatal
Message: com.sap.mw.jco.JCO (initialization failure)

which just passes through the same basic error from the remote loader side, that the JCO class cannot be intialized.

Solution

To use the dirxml_jremote remote loader,

1. Find the tar.gz file on the Novell Identity Manager media. It may be on a physical CD or DVD, or you may need to open the ISO and get the file itself. This includes the basic stripped down Remote loader as a Java class, with the most basic set of driver libraries.

2. Choose the location in the filesystem where you will be using it and extract it to there.

3. Find the lib directory that has the basic Java classes.

4. Get the SAPShim.jar and 64-bit sapjco.jar files, and copy them into the lib directory.

5. Because the libsapjcorfc.so needs to be in the path, your best bet is to symbolic-link it from the remote loader directory into /usr/lib so it can be found by all apps that need it.

6. Get a copy of the HRMD meta file. In my case, the JCOTest class reported that we were using the HRMD_A06 definition, so I renamed the HRMD_A05 that ships with the driver to match. This is the recommended method, or you can use the meta file generating tool to generate a new one for your instance.

7. Provide a configuration file to the Remote Loader class. The format is the same across all the remote loaders, as far as I know, so you can look at any you might have defined, to see the basic format.

Configuration File

The syntax for the configuration file is pretty simple - a command prefixed by a dash, one per line. My sample named rdxml-sap.conf looks like this:

-commandport 8001
-connection "port=8090 keystore='/idm/iff.keystore' storepass='dirxml'"
-trace 3
-tracefile /idm/trace8000.log
-description sap-hr
-class com.novell.nds.dirxml.driver.SAPShim.SAPDriverShim

My example needed a command port of 8001, since the AIX server had a service already using port 8000 already. This is nice and easy to configure here.

The connection string includes the port that the engine will be trying to talk to, and thus will be listening on the remote loader server. The keystore="" aspect is optional. In the end, I disabled it, because this implementation was not sending passwords in either direction; the servers were both inside the clients firewall, on the server network, and they had a policy not to use SSL internal to the site. They also had a firewall configured on the server itself such that the only clients that could connect on either port I had configured was the engine server to add some additional security.

The password for the keystore is an interesting issue. When you use the included create_keystore tool, it gets the public key of the Trusted Root certificate of your eDirectory's tree Certificate Authority. It's much like providing the RootCert.der for an Active Directory driver (although that one wants it in B64 format) or any other platform. On UNIX and Linux platforms, the keystore is almost always encrypted, and in reality, the public key is as the name suggests completely public. It really does not matter who gets a copy; in fact, you want it as widely distributed as possible so that clients who see a certificate signed by it will not report an error. Thus, the password for the remote loader class is a well-known default of DirXML. (It seems kind of silly to use a password that is well-known to encrypt something public that you actually want people to know. Such is life, it would seem!)

The tag -trace indicates the trace level. This is the Remote loader trace, which is needed only for intial debugging. If you are an optimist and believe it will just work, you can leave this line out, or set it to "0" to disable the trace. Generally, "3" is what you want enabled to see events and debug most things. This is usually true for engine or remote loader traces. Some drivers have interesting information added at higher levels of trace, but sometimes there is too much information. On the remote loader trace for the Identity Manager for JDBC, if you set trace to level 5, you will see it show the generation of the state file, where it compares the timestamp of each attribute in the database and decide what has changed. Databases often have thousands to millions of rows, so you can imagine that tracing this kind of output can kill performance. In the case of the JDBC driver, it can make it impossible to proceed, as the delay of writing out a value for each attribute compared takes so much time that nothing else ever seems to happen!

In general, level 3 is enough, unless Novell Techincal Support asks you to run at a higher level. Then you'll want to run at the higher level just long enough to catch the troublesome event in the log, and then set it to a lower value, if not zero. Remember to reset the value down to zero once you are done with development, as it adds unneeded load to the remote loader to trace events to the log file.

The companion setting to "-trace" is, of course, "-tracefile", to specify the location to write the trace out to.

The -description tag sets a name in the trace file for the remote loader instance. It's probably not needed but harmless enough to have.

The last tag is probably the most important, as it tells the Remote Loader which Java class to use for the driver you are trying to run. If you look at a Remote Loader on Windows, such as for the Active Directory Remote Loader, you will see that the tag is not "-class". Rather, it is "-module" to indicate the difference between a Java class and a Windows native DLL file.

Launching the Remote Loader

Once you have this configuration file ready, the basic command to launch the remote loader, assuming you are using /idm as your base directory (for simplicity's sake) would be something like this:

M

/idm/dirxml_jremote -config /idm/rdxml-sap.conf &

The first time you run that you will get an error, since there is no remote loader and driver password specified. It turns out you need to specify the "-sp" switch, with two passwords on the command line, just once. This will generate the encrypted password files in the current directory. They will usually be named "lpwd1f41" and "dpwd1f41". I am not sure what these passwords are encrypted with, but the remote loader knows the decrypt key and can read them. I know that the model is the same across remote loaders, and that some local events can be encrypted with this key. I was troubleshooting a problem with support, and they needed these files to use to decrypt the events we were trying to identify in the remote loader's cache.

Thus you need to run the command, just once, such as:

/idm/dirxml_jremote -config /idm/rdxml-sap.conf -sp password password

Make sure the values for password match those in the Driver configuration on the engine. (You would set these via iManager on the first page of the driver properties.)

Once you have that done, you need to decide the user you will be running the service as, on the UNIX server. The remote loader does not need root access, since all it needs to do on the local UNIX server is to read and write files to the filesystem (iDOCS) and make Jconnect calls (which uses the SAP authorization model, not the UNIX rights). Make sure the SAP system that is creating the iDOCS in the file system creates them with rights that allow your service account to read them, and then write to them. That's because the driver renames that as they are being processed from IDOCNAME to IDOCNAME.proc, and when completed, to IDOCNAME.done. If there is an error, then the event with an issue is stored in a file IDOCNAMEW.warn, and if there is a future-dated event in the iDOC it is written into a file IDOCNAME.futr. The structure of the IDOCNAME value is something involving the SAP System number, a counter value, and some other things I am not completely sure of. But the name itself is mostly immaterial.

In the case of the thick Java Remote Loader, you get a start/stop script and some nice complexity. With this stripped down dirxml_jremote, you are on your own to get it started.

One useful tip is to use "nohup" to launch it as a user and be able to have it continue running when you log out of the session. Thus, you could possibly use a command like this:

nohup /idm/dirxml_jremote -config /idm/rdxml-sap.conf &

One further trick to watch out for is that the remote loader/driver password files should be in the current directory that this command is executed from.