| |||
|
by Gaurav Singh
Tips, Tricks, and Technical Insight into Customizations for the Oracle Identity Manager User Interface
February 2014
Downloads
Oracle Identity Manager
Customizing Oracle Identity Manager's (OIM) self-service console ("ID Console") fulfills a number of business requirements, including:
In this article, we will look at some behind-the-scenes details about how OIM (in sync with some other components) achieves this flexibility on UI. It is assumed here that the reader is familiar with the basic functionality of OIM and has knowledge of various application development framework artifacts, like EO.xml, VO.xml, pageDef.xml, tf.xml, .jsff files and managed beans (mBeans). This article applies to OIM 11gR2 and above.
Oracle Metadata Services (MDS) provides an upgrade-safe customization framework over XML files. Let's have a look at the example below to understand what that means:
Suppose an application provides the following OOTB XML document, with the path /metadata/sample-app-metadata.xml
managed by MDS.
<BaseDocument id="base"> <TagA id="tagA" name="Sample Tag A" prop="30" /> <TagB id="tagB" name="Sample Tag B" prop="25" /> <TagC id="tagC" name="Sample Tag C" prop="10" /> </BaseDocument>
Now, if the application guarantees that this XML can be customized at runtime, it will provide two strings for that. A customization layer name ("site" in the case of OIM) and a layer value ("site" again for OIM). Using this, a customization XML file can be created in directory /metadata/mdssys/cust/<layer-name>/<layer-value>/sample-app-metadata.xml.xml
(note the ".xml.xml
" extension), as follows:
<mds:customization version="11.1.1.61.15" xmlns:mds="http://xmlns.oracle.com/mds"> <mds:modify element="tagB"> <!-MODIFYING PROP OF TAG-B TO 15 --> <mds:attribute name="prop" value="15"/> </mds:modify> <mds:insert parent="base" position="first"> <!-INSERTING A CUSTOM ELEMENT AT THE BEGINNING OF ROOT TAG --> <Tag0 id="tag0" name="Custom Tag 0" prop="35" /> </mds:insert> </mds:customization>
At runtime, when the application now asks for sample-app-metadata.xml
, the following XML will come into effect (custom changes are in bold):
<BaseDocument id="base?> <Tag0 id="tag0" name="Custom Tag 0" prop="35" /> <TagA id="tagA" name="Sample Tag A" prop="30" /> <TagB id="tagB" name="Sample Tag B" prop="15" /> <TagC id="tagC" name="Sample Tag C" prop="10" /> </BaseDocument>
Now, since the customization XML is existing independently on its own, replacing the base document while upgrading to the next version will not affect the customizations. It is upgrade-safe.
OIM uses this concept, along with sandboxing from MDS, for UI customizations. Let's walk through a typical use case of adding a custom attribute to the user entity and dropping it onto create and view user pages. Side by side, we will see the artifacts being generated and their significance.
/mdsys/sandbox/active_mdsSandboxMetadata.xml
: This file identifies a sandbox zip. It contains the sandbox name, creator, last modifier, and the respective timestamps. If you wish to import the same sandbox with some other name, changing the name of zip file will not help. The name should be changed inside this file. OIM-created sandbox names have the prefix "IdM," which should never be removed when changing the name.oracle/iam/ui/common/model/user/entity[or view]/mdssys/cust/site/site/userEO[or VO].xml.xml
: These are two customization XML files over the userEO/VO.xml
. They contain the definition of the newly added attribute. Later, we will see how they look.oracle/iam/ui/runtime/form/model/user/entity[or view]/mdssys/cust/site/site/userEO[or VO].xml.xml
: These customization XML files over the userEO/VO.xml
are present ONLY for user creation and user modification flows. Since user creation/modification either takes a direct or an approval route based on the current user's authorization, these two flows are integrated behind the scenes with catalog, which transparently handles this.EO/VO.xml
files under a similar path while creating application instance forms since they are also integrated with catalog (non-transparently, though).xliffBundles/oracle/iam/ui/runtime/BizEditorBundle_en_US.xlf
: This is the resource bundle file in which the display label of the attribute is kept for localization. By default, this file is generated with the locale suffix of the browser locale under which the attribute was created. So, for example, while creating the attribute, if the label is in French, but your browser locale is English, the label will be used for the English locale browsers.userEO.xml.xml
file.<?xml version='1.0' encoding='UTF-8'?> <mds:customization version="11.1.1.64.93" xmlns:mds="http://xmlns.oracle.com/mds" motype_local_name="PDefEntityObject" motype_nsuri="http://xmlns.oracle.com/bc4j"> <!-- INSERT STATEMENT TO BE EXECUTED OVER OOTB USEREO.XML FILE--> <mds:insert parent="UserEO" position="last"> <!-- EO.XML ENTRY FOR ATTRIBUTE. NOTE THAT NAME IS ppNumber__c. --> <Attribute Name="ppNumber__c" IsPersistent="false" Precision="60" Scale="0" ColumnName="PPNUMBER__C" Type="java.lang.String" ColumnType="VARCHAR2(255)" SQLType="VARCHAR" xmlns="http://xmlns.oracle.com/bc4j"> <Properties> <!-- CERTAIN PROPERTIES OF ATTRIBUTE --> <Property Name="AttributeType" Value="Text"/> <Property Name="DISPLAYWIDTH" Value="60"/> <Property Name="ExtnCustom" Value="Y"/> <!-- REFERENCE TO BizEditorBundle.xlf FOR DISPLAY LABEL (CONTAINED IN THE SAME SANDBOX) --> <Property Name="LABEL_ResId" Value="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle'] ['oracle.iam.ui.common.model.user.entity.UserEO.ppNumber__c_LABEL']}"/> <!-- NAME OF ATTRIBUTE AS KNOWN BY OIM BACKEND --> <Property Name="oimRefAttrName" Value="ppNumber"/> </Properties> <CompOper Name="=" ToDo="2" Oper="=" MinCardinality="1" MaxCardinality="1"/> <CompOper Name="STARTSWITH" ToDo="2" Oper="STARTSWITH" MinCardinality="1" MaxCardinality="1"/> <CompOper Name="ENDSWITH" ToDo="2" Oper="ENDSWITH" MinCardinality="1" MaxCardinality="1"/> <CompOper Name="<>" ToDo="2" Oper="<>" MinCardinality="1" MaxCardinality="1"/> <CompOper Name="CONTAINS" ToDo="2" Oper="CONTAINS" MinCardinality="1" MaxCardinality="1"/> <CompOper Name="DOESNOTCONTAIN" ToDo="2" Oper="DOESNOTCONTAIN" MinCardinality="1" MaxCardinality="1"/> <CompOper Name="Dummy" ToDo="-2" Oper="Dummy" MinCardinality="1" MaxCardinality="1"/> </Attribute> </mds:insert> <mds:modify element="UserEO"> <mds:attribute name="StaticDef" value="oracle.iam.ui.common.model.user.entity.UserEO"/> </mds:modify> </mds:customization>
<af:inputText>
component in a .jsff
file and bind that to a particular attribute present in the ADF BC layer. This binding should be done through pageDef.xml
's <attribute>
binding. Let's export the sandbox and verify that this is what we actually have inside it.userCreateForm.jsff.xml
userCreateFormPageDef.xml.xml
Let's take a look at some components that are consumed by OIM for customizing the UI through MDS.
ADFContext.getCurrent.getMDSSessionAsObject(
) method.)EO.xml
, VO.xml
and AM.xml
). While creating a custom attribute for user/role/organization, BE is responsible for generating customization XML files over the corresponding EO/VO containing the new attribute. Again, these files get pushed to the current ADF context's MDS session to be managed by MDS. BE also comes into play when an application instance form is created. In that case, a new EO.xml
and VO.xml
is created at runtime and OOTB CatalogAM.xml
is edited to include the new VO.Apart from MDS-based customization framework, OIM provides a way to build custom ADF task flows and managed beans. These are generally used for custom validations, handling the action of custom links and buttons, or even building completely new screens and launching them through certain links. Here is the deployment process for such changes:
IDM_HOME/server/jdev.lib
directory.oracle.iam.ui.custom-dev-starter-pack.war
(file present in IDM_HOME/server/apps
) inside WEB-INF/lib
folder. Create a lib folder if not present OOTB inside WEB-INF
.oracle.iam.ui.custom
library in the WebLogic console to see the deployment path (which might not be deployed from IDM_HOME/server/apps
).oracle.iam.ui.custom
Library in the WebLogic Consoleoracle.iam.ui.custom
library deployment. Once the update is complete, start the two applications stopped previously.A few points must be kept in mind when developing custom mBeans:
pageFlowScope
or backingBeanScope
while registering a bean directly to adfc-config.xml
. Use session and request scopes instead. If you have built your own task flow, registering your bean in there can be done with any required scope.This article provides technical insight into the possible customizations over OIM UI, and walks through the most common use case—adding a new user attribute to the create and view details pages—and describes what happens behind the scenes. It also provides the basic steps that must be performed to inject into OIM UI custom ADF code that is available at runtime.
Gaurav Singh is part of the Oracle Identity Manager Developers' group. Since the very beginning of his career he has been interested in UI technologies and has been exploring Oracle ADF, Oracle Metadata Services, Oracle Composer, and similar tools to deliver next-generation user interfaces.