Import/export Deployment Artifacts

On this page you will find how to import/export OIM configuration artefacts which usually comprise significant part of project configuration. In 11g Oracle provides a WEB-based tool named Deployment Manager based on Nexaweb. On this page the underlying API is described along with a bit of theory.

Understanding import/export operations

  1. The tcExportOperationsIntf ([http://docs.oracle.com/cd/E23549_01/apirefs.1111/e17334/Thor/API/Operations/tcExportOperationsIntf.html]) interface is used for all export operations.
  2. The tcImportOperationsIntf ([http://docs.oracle.com/cd/E23549_01/apirefs.1111/e17334/Thor/API/Operations/tcImportOperationsIntf.html]) interface is used for all import operations.
  3. Both tcExportOperationsIntf and tcImportOperationsIntf are remote services, so they can be used both on the server and cliend sites.
  4. Due to the remote nature of services only objects of classes implementing the java.lang.Serializable interface can be used as arguments and return values of all service methods.
  5. Objects of the RootObject class are used both for import and export operations.
  6. Objects of the FilePreview class are additionally used for import operations.
  7. Though most import methods use RootObject for passing data, this type is rarely mentioned in method signatures, usually RootObjects are passed as members of collections. So if you see java.util.Collection in any method signature of tcExportOperationsIntf or tcImportOperationsIntf it really means Collection<RootObject>.
  8. You can use any kind of java.util.Collection provided that it implements the java.lang.Serializable interface.
  9. The type of a RootObject (the physicalType field value) must be one of the supported types (the one returned by retrieveCategories() method):.
    1. eventhandlers
    2. Process Form
    3. Organization
    4. ITResource
    5. NOTIFICATIONTEMPLATE
    6. PasswordPolicy
    7. RequestDataset
    8. Role and Orgs UDF
    9. DataObjectDef
    10. RequestTemplate
    11. UserGroup
    12. PrepopAdapter
    13. Process
    14. ITResourceDef
    15. Resource
    16. OESPolicy
    17. EmailDef
    18. TaskAdapter
    19. SystemProperties
    20. GenericConnector
    21. GTCProvider
    22. Rule
    23. ApprovalPolicy
    24. Job
    25. Lookup
    26. scheduledTask
    27. User UDF
    28. ErrorCode
  10. a RootObject can have references to other RootObjects. If some object A refers some object B, then A depends on B and A is child of B. These references for children/dependants network. tcExportOperationsIntf provides means to traverse both types of these relations.
  11. a RootObject does not hold all the export data, it might contain some type information and some structural relation to other RootObjects
  12. objects other than RootObjects belong to some RootObject and can be retrieved only along with their RootObject in XML. You can only retrieve all that data at once, you cannot select which data to retrieve, and which not. If you do not need some of the data, editing the resulting XML is your only option.

Export operations

Obtaining a service handle

tcExportOperationsIntf exportIntf = oimClient.getService(tcExportOperationsIntf.class);

See Open a client connection to OIM server.

Query repository (findObjects)

In this example we'll query the repository for a RootObject matching the following criteria: category="Resource", name="AD User".

Collection<RootObject> roots = exportIntf.findObjects("Resource", "AD User");
System.out.println(roots);

the output will look like this:

[AD User [Resource] (exportable) (shared)]

Export to XML (getExportXML)

In this example we export a RootObject of the type "Resource" with a name "AD User".

Collection<RootObject> resources = exportIntf.findObjects("Resource", "AD User");
String xml = exportIntf.getExportXML(resources, "Some description");
System.out.println(xml);

the output will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<xl-ddm-data version="2.0.1.0" user="XELSYSADM" database="jdbc:oracle:thin:@localhost:1521/orcl" exported-date="1340011686189" description="">
  <Resource repo-type="RDBMS" name="AD User">
    <OBJ_AUTO_PREPOP>0</OBJ_AUTO_PREPOP>
    <OBJ_ALLOWALL>1</OBJ_ALLOWALL>
    <OBJ_ALLOW_MULTIPLE>1</OBJ_ALLOW_MULTIPLE>
    <OBJ_TYPE>Application</OBJ_TYPE>
    <OBJ_UPDATE>1324553455000</OBJ_UPDATE>
...

Getting descendants (retrieveChildren)

In the following example we'll first find some RootObject, then recursively populate it with all descendants (child objects and their child objects).

Collection<RootObject> roots = exportIntf.findObjects("Resource", "AD User");
System.out.println(roots);
Collection<RootObject> withChildren = exportIntf.retrieveChildren(roots);
System.out.println(withChildren);

prints:

[AD User [Resource] (exportable) (shared)]
[AD User [Resource] (exportable) (shared)
  AD User [Process] (exportable)
    UD_ADUSER [Process Form] (exportable)
      UD_ADUSRC [Process Form] (exportable)
    adpADCSMUSTCHANGEPWD [TaskAdapter] (exportable)
    adpFTSCREATEUSER [TaskAdapter] (exportable)
    adpADCSSETUSERPASSWORD [TaskAdapter] (exportable)
    adpADCSCHANGEATTRIBUTE [TaskAdapter] (exportable)
    adpADCSLOCK_UNLOCKUSER [TaskAdapter] (exportable)
    adpADCSUPDATEADDUSERTOGROUP [TaskAdapter] (exportable)
    adpADCSENABLEUSER [TaskAdapter] (exportable)
    adpADCSADDUSERTOGROUP [TaskAdapter] (exportable)
    adpADCSREMOVEUSERFROMGROUP [TaskAdapter] (exportable)
    adpADCSRENAMEUSERACCOUNT [TaskAdapter] (exportable)
    adpADCSSETACCOUNTEXPDATE [TaskAdapter] (exportable)
    adpADCSDISABLEUSER [TaskAdapter] (exportable)
    adpADCSPWDNEVEREXPIRES [TaskAdapter] (exportable)
    adpADCSCREATEUSER [TaskAdapter] (exportable)
    adpADCSEXECUTEREMOTESCRIPT [TaskAdapter] (exportable)
    adpADCSUPDATEREDIRECTMAILID [TaskAdapter] (exportable)
    adpADCSDELETEUSER [TaskAdapter] (exportable)
    adpADCSMOVEUSER [TaskAdapter] (exportable)]

Getting dependencies (getDependencies)

In the following example we'll find some RootObject, then get the list of all other RootObjects this object dependents on directly. Note that the list returned by getDependencies(Collection) already includes the original object itself.

Collection<RootObject> roots = exportIntf.findObjects("Resource", "AD User");
System.out.println(roots);
Collection<RootObject> dependencies = exportIntf.getDependencies(roots);
System.out.println(dependencies);

prints:

[AD User [Resource] (exportable) (shared)]
[AD User [Resource] (exportable), SYSTEM ADMINISTRATORS [UserGroup] (exportable), RESOURCE ADMINISTRATORS [UserGroup] (exportable), RECONCILIATION ADMINISTRATORS [UserGroup] (exportable)]

The "AD User" Resource lists 3 roles as object administrators.

Getting dependency tree (retrieveDependencyTree)

In the following example we first find some RootObject, then populate it with complete dependency tree.

Then dependency tree is constructed, the following happens:

  1. all direct dependencies added to the result set with getDependencies()
  2. all descendants are added to the result set for the result set obtained at the previous step with retrieveChildren()
  3. the result set is rebuild as trees
Collection<RootObject> roots = exportIntf.findObjects("Resource", "AD User");
System.out.println(roots);
Collection<RootObject> dependencyTree = exportIntf.retrieveDependencyTree(roots);
System.out.println(dependencyTree);

prints:

[AD User [Resource] (exportable) (shared)]
[AD User [Resource] (exportable) (shared)
  AD User [Process] (exportable)
    UD_ADUSER [Process Form] (exportable)
      UD_ADUSRC [Process Form] (exportable)
    adpADCSMUSTCHANGEPWD [TaskAdapter] (exportable)
    adpFTSCREATEUSER [TaskAdapter] (exportable)
    adpADCSSETUSERPASSWORD [TaskAdapter] (exportable)
    adpADCSCHANGEATTRIBUTE [TaskAdapter] (exportable)
    adpADCSLOCK_UNLOCKUSER [TaskAdapter] (exportable)
    adpADCSUPDATEADDUSERTOGROUP [TaskAdapter] (exportable)
    adpADCSENABLEUSER [TaskAdapter] (exportable)
    adpADCSADDUSERTOGROUP [TaskAdapter] (exportable)
    adpADCSREMOVEUSERFROMGROUP [TaskAdapter] (exportable)
    adpADCSRENAMEUSERACCOUNT [TaskAdapter] (exportable)
    adpADCSSETACCOUNTEXPDATE [TaskAdapter] (exportable)
    adpADCSDISABLEUSER [TaskAdapter] (exportable)
    adpADCSPWDNEVEREXPIRES [TaskAdapter] (exportable)
    adpADCSCREATEUSER [TaskAdapter] (exportable)
    adpADCSEXECUTEREMOTESCRIPT [TaskAdapter] (exportable)
    adpADCSUPDATEREDIRECTMAILID [TaskAdapter] (exportable)
    adpADCSDELETEUSER [TaskAdapter] (exportable)
    adpADCSMOVEUSER [TaskAdapter] (exportable), SYSTEM ADMINISTRATORS [UserGroup] (exportable)
  OIM Roles [RoleCategory] (exportable), RESOURCE ADMINISTRATORS [UserGroup] (exportable)
  OIM Roles [RoleCategory] (exportable), RECONCILIATION ADMINISTRATORS [UserGroup] (exportable)
  OIM Roles [RoleCategory] (exportable)]

List categories (retrieveCategories)

This example shows how to get the list of all possible object types.

Collection<String> categories = exportIntf.retrieveCategories();
for(String category : categories)
  System.out.println(category);

Complete example: export entire connector

In the following example we will export to XML all the data provided with the Microsoft Active Directory connector.

String[] lookupNames = new String[] {
  "lookup.AD.GroupChildData",
  "Lookup.ADReconciliation.TransformationMap",
  "Lookup.ADReconciliation.Organization",
  "Lookup.ADReconciliation.GroupLookup",
  "Lookup.ADReconciliation.FieldMap",
  "Lookup.ADGroupReconciliation.FieldMap",
  "Lookup.ADAMReconciliation.FieldMap",
  "Lookup.ADAMGroupReconciliation.FieldMap",
  "Lookup.AD.FieldsForValidation",
  "Lookup.AD.Domains",
  "Lookup.AD.Country",
  "Lookup.AD.Constants",
  "Lookup.AD.Configuration",
  "Lookup.AD.BLOBAttribute.Values",
  "Lookup.AD Group Type",
  "Atmap.RM",
  "AtMap.ADOrg",
  "AtMap.ADGroup",
  "AtMap.ADAMGroup",
  "AtMap.ADAM",
  "AtMap.AD.RemoteScriptlookUp",
  "AtMap.AD",
};
 
Set<RootObject> exportSet = new HashSet<RootObject>();
 
exportSet.addAll(exportIntf.findObjects("scheduledTask", "AD *"));
exportSet.addAll(exportIntf.findObjects("Resource", "AD *"));
exportSet.addAll(exportIntf.findObjects("Process", "AD *"));
exportSet.addAll(exportIntf.findObjects("ITResourceDef", "AD Server"));
exportSet.addAll(exportIntf.findObjects("ITResource", "GCADITResource"));
exportSet.addAll(exportIntf.findObjects("ITResource", "ADITResource"));
exportSet.addAll(exportIntf.findObjects("TaskAdapter", "adpADCS*"));
exportSet.addAll(exportIntf.findObjects("PrepopAdapter", "adpADCS*"));
exportSet.addAll(exportIntf.findObjects("Process Form", "UD_AD*"));
exportSet.addAll(exportIntf.findObjects("Process Form", "UD_OU"));
exportSet.addAll(exportIntf.findObjects("User UDF", "USR"));
 
for(String lookupName : lookupNames)
  exportSet.addAll(exportIntf.findObjects("Lookup", lookupName));
 
String xml = exportIntf.getExportXML(exportSet, "Some description");

Note: the resulting file needs some manual clean up. I contains the following data which is not part of MSAD connector:

  1. descriptions for ALL UDFs for the USR form, while the MSAD connectors adds only one user-defined field ("USR_UDF_OBGUID")
  2. the "UserXml" element.

Import

TODO

Import from XML text

Import all artifacts from the text in the xml variable.

tcImportOperationsIntf importIntf = oimClient.getService(tcImportOperationsIntf.class);
importIntf.acquireLock(true);
Collection<RootObject> justImported = importIntf.addXMLFile(filename, xml);
importIntf.performImport(justImported);
configurationexportimporttcexportoperationsintftcimportoperationsintfxml
page revision: 26, last edited: 22 Jun 2012 14:49
Edit Rate (0) Tags History Files Print Site tools + Options
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License