test

Sun Identity Manager Deployment Guide

Customizing Data Exporter

Data exporting has two levels of schema in effect, the internal (ObjectClass) and the external (Export) schemas. These schemas provide a data “interface” that can be proven to be compliant over multiple releases of the Identity Manager. Compliant means that the attribute names, data types, and data meanings will not change. An attribute may be removed, but the attribute name cannot be re-used to mean something different. Attributes may be added at any time. A compliant schema allows reports to be written against a version of the schema and run without modification against any later version.

The ObjectClass schema tells programs in the Identity Manager server what the data should look like, while the external schema tells the warehouse what the data should look like. The internal schema will vary from release to release, but the external schema will stay compliant across releases.

Identity Manager ObjectClass Schema

The ObjectClass schema can be extended for User and Role types, but otherwise cannot be changed. The ObjectClass schema is used by programs executing on the Identity Manager servers to provide access to the data objects themselves. This schema is compiled into Identity Manager and represents the data that is stored and operated on within Identity Manager.

This schema may change between versions of Identity Manager, but is abstract to the data warehouse because of the export schema. The ObjectClass schema provides a schema abstraction on top of the Identity Manager Persistent Object layer, which are the data objects stored in the Identity Manager repository.

Custom User and Role attributes, also known as extended attributes, are defined in the IDMSchemaConfiguration object. See Chapter 10, Editing Configuration Objects for information about adding extended attributes to the ObjectClass schema.

Export Schema

The export schema defines what data can be written to the warehouse. By default, it is limited to a subset of the ObjectClass schema, although the difference between the two is very small. The ObjectClass schema is represented by Java objects, but the export schema must have a bi-directional mapping between Java objects and RDBMS tables.

After you have added an extended attribute to the IDMSchemaConfiguration object, you must define the same attribute in the export schema, which is defined in the $WSHOME/model-export.xml file. Locate the Role or User model in this file and add a field element that defines the attribute. The field element can contain the following parameters.

Table 5–2 Export attribute parameters

Parameter  

Description  

name 

The name of the attribute. This value must match the name assigned in the IDMSchemaConfiguration object.

type 

The data type of the attribute. You must specify the full Java class name, such as java.lang.String or java.util.List.

introduced 

Optional. Specifies the release that the attribute was added to the schema. 

friendlyName 

The label that is displayed on the Data Exporter configuration pages. 

elementType 

If the type parameter is java.util.List, then this parameter specifies the data type of the items in the list. Common values include java.lang.String and com.sun.idm.object.ReferenceBean.

referenceType 

If the elementType parameter is com.sun.idm.object.ReferenceBean, then this parameter references to another Identity Manager object or pseudo-object.

forensic 

Indicates the attribute is used to determine relationships. Possible values are User and Role.

exported 

When set to false, the attribute is not exported. If you want to hide a default attribute from the Data Exporter data type configuration page, add exported=’false’ to the attribute definition.

You must create a custom WIC library to be able to export an attribute in the default schema that has exporting disabled. 

queryable 

When set to false, the field is not available for forensic queries. 

max-length 

The maximum length of a value. 

The following example adds an extended attribute named telno to the export schema as part of the User model:

<field name=’telno’
    type=’java.lang.String’
    introduced=’8.0’
   max-length=’20’
   friendlyName=’Telephone Number’>
   <description>The phone number assigned to the user.</description>
</field>

Modifying the Warehouse Interface Code

The Warehouse Interface Code (WIC) is provided in binary and source form in Identity Manager. Many deployments will be able to use the WIC code in binary form (no modifications), but some deployments may want to make other changes. The WIC code must implement two interfaces to be used for exporting, and a third interface to be used by the Forensic Query interface.

The default WIC implementation writes to a set of RDBMS tables. For many applications this is sufficient, but you could create custom WIC code to write the date to a JMS queue or to some other consumer.

The com.sun.idm.exporter.Factory and com.sun.idm.exporter.Exporter classes are used to export data. The export code is responsible for converting models (Java data objects) to a form suitable for storage. Typically, this means writing to a relational database. As a result, the WIC code is responsible for Object to Relational transformation.

The default WIC implementation uses Hibernate to provide the Object/Relational mapping. This mapping is controlled by the Hibernate .hbm.xml mapping files, which are in turn generated based on the export schema. Hibernate prefers to use a Java bean-style data object for its work, and has various get and set methods to accomplish this. The WIC code generates the corresponding Bean and hibernate files that match the export schema. If Hibernate provides the necessary mapping features, there may be no need to modify any WIC code manually.

The WIC files are located in the InstallationDirectory/REF/exporter directory.

Generating a New Factory Class

Identity Manager allows you to add custom User and Role attributes to the ObjectClass schema. These attributes, known as extended attributes, cannot be exported unless you also add them to the export schema, regenerate the Warehouse Interface Code (WIC), and deploy the code.

When extended attributes are added, you will need to edit the export schema control file and add the attributes. If attributes are to be excluded from the exporter, then you can simply mark the schema fields with exported=’false’ and regenerate the WIC code.

To modify the WIC code you will need the following installed on your system

The steps required to export extended attributes are as follows:

ProcedureTo Export Extended Attributes

  1. Get the WIC source code from the REF kit

  2. Set the WSHOME environment variable to the installation directory of Identity Manager

  3. Back-up the export schema control file $WSHOME/model-export.xml then edit it.

  4. Change directories to the WIC source top-level directory. This directory should contain files named build.xml, BeanGenerator.java, and HbmGenerator.java.

  5. Stop the application server.

  6. Remove CLASSPATH from the environment.

    Note –

    You must remove CLASSPATH from the environment before performing executing ant rebuild in the next step.

  7. Rebuild the WIC code with the ant rebuild command.

  8. Deploy the modified WIC code to the application server with the ant deploy command.

  9. Restart the application server.

    Note –

    If you change model-export.xml and rebuild the WIC as shown in the preceding steps, a new warehouse DDL is generated. You must drop the old tables and load the new DDL, which deletes any data that is already in the tables.

Adding Localization Support for the WIC

The export schema contains numerous strings that are displayed on the Data Exporter Type Configuration pages. Use the following procedure to display the strings in a language that is not officially supported:

ProcedureTo Add Localization Support for the WIC

  1. Extract the contents of the $WSHOME/WEB-INF/lib/wicmessages.jar file.

  2. Navigate to the com/sun/idm/warehouse/msgcat directory.

  3. Translate the contents of WICMessages.properties file. Make sure the final results are saved in a file that contains the locale.

    You do not need to save the message catalog to the System Configuration object.