Custom transformation provider for OIM GTC connector

GTC based connector is one of the most used approaches for reconciling data into OIM, specially through the use of flat files. A common issue is that some customers do not allow direct communication between OIM and the HR system (for different reasons like outsourced HR system, security constraints and others), hence a flat file is made available to OIM so that it reconcile users.

Very often, there is a need to manipulate the data to be reconciled in OIM through the GTC connector. When that is true, most of customers end up creating event handlers to manipulate reconciled data. The problem with this approach is that in OIM 11g, only 'post process' event handlers can be used to manipulate reconciliation data (and the data can only be manipulated after reconciled into OIM), and this can make some manipulations really tricky and/or cumbersome.



OIM GTC framework provides a nice feature called 'Transformation Provider'. A 'Transformation Provider' is invoked by GTC at reconciliation data load time, before GTC creates the reconciliation event. Transformation providers are invoked per attribute, and different providers can be used for different attributes. They are all configured during the GTC reconciliation mapping stage.


The picture below shows where a custom transformation provider will show up in the GTC configuration:

This post shows an example of a custom transformation provider as well as how to deploy it. The objective of this transformation provider is delete enclosing double-quotes from the attribute data loaded from the flat file: the attribute value loaded from the file is "attrValue" and it will be transformed to attrValue. As you may be aware, GTC is not capable of doing that character trimming in the out-of-the-box configuration.

The transformation provider consists of a XML descriptor, a jar file containing the compiled code and a resource bundle file containing the errors messages. The XML file must be loaded into the MDS database, whereas the jar file must be uploaded to OIM.

Below the XML file that defines the provider:

<?xml version='1.0' encoding='UTF-8'?>
<Provider>
   <Transformation>
     <TransformationProvider class="oracle.iam.demo.gtc.CustomTransformationProvider" name="CustomTransformationProvider">
       <Configuration>
         <Parameter type="Runtime" datatype="String" required="YES" encrypted="NO" name="Input"/>
         <Response code="REMQUOTES_INPUTSTR_MISSING" description="Input String is Missing"/>
       </Configuration>
     </TransformationProvider>
  </Transformation>
</Provider> 

This file MUST be loaded to the MDS location below:

/db/GTC/ProviderDefinitions

Below the Java code with the transformation provider implementation:
package oracle.iam.demo.gtc;

package oracle.iam.demo.gtc;

import com.thortech.xl.gc.exception.ProviderException;

import com.thortech.xl.gc.spi.TransformationProvider;

import java.util.Hashtable;

public class CustomTransformationProvider implements TransformationProvider {
    
    public CustomTransformationProvider() {}

    private static String providerType = "TransformationProvider";
    private static String providerName = "CustomTransformationProvider";
    private static String errorRespNullInput = "REMQUOTES_INPUTSTR_MISSING";
    
    public String transformData(Hashtable input, Hashtable utils) throws ProviderException  {
        
        try  {         
            String wholeString = (String)input.get("Input");    
                
            return wholeString.substring(1,wholeString.length()-1);
        } 

        catch (Exception ex) {
            
            StringBuffer responseCode = new StringBuffer();
            responseCode.append(providerType);
            responseCode.append(".");
            responseCode.append(providerName);
            responseCode.append(".");
            responseCode.append(errorRespNullInput);
           
            throw new ProviderException(responseCode.toString(),"message");
        }                                            
    }
}

The class must be deployed within a jar file. The jar file must be loaded with '$OIM_HOME/server/bin/UploadJars.sh<bat>' as a 'JavaTask'`.

The resource bundle (and its translations) must be loaded as 'connectorResource' in OIM using the '$OIM_HOME/server/bin/UploadResourceBundles.sh<bat>' script. Below an example of the resource:

###### Transformation Provider  ######
GC.GCPROV.TransformationProvider.CustomTransformationProvider.REMQUOTES_INPUTSTR_MISSING=Input String Missing
GC.GCPROV.TransformationProvider.CustomTransformationProvider.REMQUOTES_INPUTSTR_MISSING.description=The input string is missing.

Make sure that the resource bundle is named after the transformation provider: CustomTransformationProvider.properties in this case. At least one translation must be loaded (like CustomTransformationProvider_en.properties).

Once you have the three pieces (XML, jar file and resources) deployed to OIM, you should be able to see the transformation provider available to be used in the GTC attribute mapping screen (as shown in the picture in this post).

The material and solution available in this post were gently provided by John Kimble, a co-worker at Oracle.