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
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:
The folder for the class files has to be set like this:
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.
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:
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.
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.
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
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.
Meaning of the return values of the methods – ToExample
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:
If you get an DSEEntry object and want to retrieve the attributes use the get method:
|String entryName = entryToAdd.get(„entryName“);|