How to use custom classes in the SAP NetWeaver Identity Management

[Former Member]

How to use the IdM-API – According to the custom passes FromCustom and ToCustom

One of the largest advantages of the SAP Identity Management is that it supplies not only the predefined passes to the well-known target systems but also has a Java-API delivered right out with the installation of the Identity Center. With the help of the API jobs can be equipped with passes which handle the connection to custom systems. So the IdM-Java-API can be used to implement a connection to every system which handles users, their attributes, roles, etc.

The following systems applications have been used in this blog:

• SAP NetWeaver Identity Management 7.0 SP02 Patch 2
• MS SQL Server 2005 Database
• Eclipse Europa (Version 3.3) using
• Java SE SDK 6.0

Knowledge experience in the following areas are necessary helpful:

• Java programming language
• Basic API knowledge

Scenario description

Imagine the following. There is a system in your company which is essential to the daily work but costs a lot of maintaining work administering the users, their attributes, access roles, etc. Not to forget the everlasting problem caused by passwords resets. As there exists already a SAP IdM which handles all of the systems but this last one, it would be great to administer them all using the IdM. Unfortunately there are no passes which can be used in jobs to do this in a swift way, like we are used to.

For this little problem exists a powerful IdM-DSE-Java-API, especially the classes used in the FromCustom and ToCustom passes. What now has to be done is to write the system’s implementation on the base of the classes of the Identity Center API. Note that the target system has to exhibit a way to access the users, their attributes, roles or whatever shall be retrieved using their Java-API. For other systems different passes have to be used, for other programming languages the Windows runtime engine has to be selected instead of the Java runtime.

Preparations in the IdM

Before you start the implementation for your system, the classpaths of your later class files and custom Java-API have to be set up. This is done in the Identity Center: Go to Tools => Options => Java => Classpath extension. Note that classfiles must not be referenced with their complete path but with their folder they are in. If there shall be more than one entry, they have to be separated by semicolons.

A jar-file entry then looks like:
C:\\SomeFolder\\APIs\\CustomAPI.jar

The folder for the class files has to be set like this:
C:\\SomeFolder\\CLASSES

For further information on this please refer to the documentation of the Identity Center.

With this the preparations in the Identity Center are finished and the creation of the passes can begin. The implementation of the classes will follow afterwards.

Setting up the passes and the needed information

As the passes have to be set up as FromCustom and ToCustom ones, you have to set up the tabs Source and Destination and if needed the Delta, too. The Repository tab has to be set according to the usage. Also the information about the repository has to be specified in the Identity Center. In this example I use only one attribute at a time to avoid information overload.  \ Instead of the server’s name, there are attributes possible like the user name and password which is used for the connection, the port, the database name, etc. All depending on the system which shall be accessed.

Repository information

To avoid having to rewrite and compile the classes again every time, you use a new repository or change the settings otherwise, there is a possibility to hand over the needed information. That is, the classes can a bit more generic.

There is a way to avoid changing and compiling the classes again and again, if you want to use a different system. Just hand over the needed attributes and retrieve them in the classes. This information have to be specified in the constants of the management section of the repository. How this is done the class in detail is explained in the section Retrieval of necessary attributes.

FromPass - Source tab

In the field Pass type the path to the class has to be specified. That is the folders are separated by dots ending with the class name itself, without .class as shown in the example. Using the FromExample.class, its unique package (see the implementation section below) and the classpath above, the file would be located in:
C:\\SomeFolder\\CLASSES\\idm\\blog\\apiexample\\FromExample.class

The only parameter in this example which will be handed over, is the server’s name. The name example.server.name only contains dots because it is easier to read then, they have no special meaning. Any parameter name will do as long it is unique in this pass. As the value is retrieved from the information stored in the repository, the variable %$rep.Example_Server_Name% can retrieve it during runtime.

FromPass - Destination tab

In the Database field simply insert the variable for the Identity Center as %$ddm.identitycenter%. Specify the table to which the entries shall be written to in the Table name field. Using the Table update options you can specify what has to happen to the table.

In the field below the Insert template button the table’s schema will be specified. Only what you enter here will be written to the database. In this example there is only a user Id entered. The Target, Type and Size fields are for the table. The Source is specified is the key used in the class building up the DSEEntry object.

FromPass - Delta tab

Not needed here in the from pass.

ToPass - Source tab

Depending on whether you use the Identity Store or not, you have to check the Use identity store button. The Database field is set accordingly. The SQL query has to be entered manually in the SQL statement field or generated using the button right of this field.

ToPass - Destination tab

As in the Source tab of the FromPass the Pass type is the path to the class. Also the paramater-value pairs are the same as in that section.
The only parameter in this example for the server’s name example.server.name and the variable %$rep.Example_Server_Name% are used here.

Note that only inserted attributes can be retrieved within your classes.

ToPass - Delta tab

The delta database has to be enabled while using the ToPass. So activate it and select the database by using the %$ddm.identitycenter% variable. The Delta identifier, the Delta key and the Source key have to be set accordingly, too.

Preparations in Eclipse

Now we are ready to create a new Eclipse Java project to do the programming work. If you choose to work local on your own machine you have to copy the class files on the server to the location specified above. The other option is to set the projects workspace and ist output folder in a way that it matches the previously specified location of the classpath.
However, I choose to work completly local and only copy the class files to server when needed. To do this efficiently I wrote a little copy batch file which I stored in my Java project. Note that the batch file may vanish from time to time, if it is placed in the binary folder of the project.
To be able to extend the FromCustom and ToCustom classes, it is necessary to import the jar-file they are located in to the Java Build Path of the Eclipse project. For this import the DSE.jar using „Add external JARs“ in the properties. Both classes can be found in the package com.sap.idm.ic.
Now we are finally ready to write the system’s classes.

Implementing the system’s classes

At first we will create a custom FromExample class using FromCustom as superclass. After that a ToExample class extending ToCustom will be implemented.

FromCustom

Create a class and name it like FromExample.java. This class has to extend the FromCustom class as superclass and will be placed it in a package of your choice. It is advisable to use unique names like idm.blog.apiexample for the package declaration to avoid any interference with other classes. The checkbox for "Inherited abstact methods" has to be checked, too.
After the creation and some cleaning up the FromExample class looks like shown below.

Method	Parameter	Description	Return value
initCustom	None	The initCustom retrieves all information which is stored in the IdM repository about the target system to built up a connection to your target system.	A boolean which indicates the success of the initialization
hasMore	None	The hasMore method checks if there are still entries of the type DSEEntry left.	A boolean which indicates that there are more DSEEntry objects available
getNextEntry	None	The getNextEntry retrieves the next DSEEntry object.	A DSEEntry object
exit	None	The exit method is designed to do the cleaning up work in your system. If you need to close connections which were established previously, close them here.	As this is a void method, nothing will be given back.

How the hasMore and getNextEntry methods are implemented in detail cannot be stated here, because every system is at least a bit different.

Meaning of the return values of the methods - FromExample

Method	Return values
initCustom	true means that the initialization in the custom system was successful	false means that the initialization in the custom system was not successful
hasMore	true means that there are more entries in the custom system	false means that there are no more in the custom system left
getNextEntry	A non-null value with a filled DSEEntry object means that this entry will be processed to what was specified in the destination tab of the pass	A null as return value means that the pass will throw an error because there is a no object given back

ToCustom

Create a class and name it like ToExample.java. This class has to extend the ToCustom class as ist superclass and will be placed it in a package of your choice. It is advisable to use unique name like idm.blog.apiexample for the package declaration to avaoid any interference with other classes. The checkbox for „Inherited abstact methods“ has to be checked. After the creation the ToCustom class something looks like shown below. There are five inherited methods which have to be filled with your custom code.

Method	Parameter	Description	Return value
initCustom	None	The initCustom retrieves all information which is stored in the IdM repository about the target system to built up a connection to your target system.	A boolean which indicates the success of the initialization
addEntryCustom and modEntryCustom	A DSEEntry object which contains one or more attributes	The addEntryCustom and modEntryCustom are quite similar because both take a DSEEntry object. This object is created in the Identity Center pass and will be described in the section where the passes are created. Depending on your target system both add and modify method	A boolean which indicates a successful adding or modification
deleteEntryCustom	A string with a unique identity	The deleteEntryCustom takes only a string, e.g. with the user name in it. If more information were passed over, the splitting work can be done here.	An integer which indicates the success of the deletion
exit	None	The exit method is designed to do the cleaning up work in your system. If you need to close connections which were established previously, close them here.	As this is a void method, nothing will be given back.

Meaning of the return values of the methods - ToExample

Method	Return values
initCustom	true means that the initialization in the custom system was successful	false means that the initialization in the custom system was not successful
addEntryCustom and modEntryCustom	true means that the adding/modifying in the custom system was successful	false means that the adding/modifying in the custom system was not successful
deleteEntryCustom	-1 means that the deletion in the custom system was successful	Any integer above -1 means that the deletion was not successful

Retrieval of necessary attributes

So, how to get the information which were handed over from the FromCustom and ToCustom passes? Remember what was specified in the passes above? The values of can be retrieved using the getPassAttr in the initCustom methods. Simply hand over the parameter you entered in the pass. For example the server name of the custom system can be retrieved as follows:

String exampleServerName = getPassAttr("example.server.name");

The second thing refers to the DSEEntry objects. As there are two way these objects are used, there are two different access methods for them. In the case you have to give an DSEEntry object back, simply create a new DSEEntry object and put all necessary attributes in it:

nextEntry.put("entryName“, entryName);

If you get an DSEEntry object and want to retrieve the attributes use the get method:

String entryName = entryToAdd.get(„entryName“);