Disconnected App Instances in OIM and Sandboxes

I wanted to provide a quick guide to Disconnected App Instances in OIM and how to handle migrating them between environments using sandboxes.

First and foremost in regards to sandboxes, straight from the administration manual for R2 (http://docs.oracle.com/cd/E27559_01/admin.1112/e27149/sysadmin.htm#CACJDIFG) “…a sandbox is a temporary storage area to save a group of runtime page customizations before they are either saved and published to other users, or discarded.”  The middle phrase, “group of runtime page customizations”, is the key part of that sentence.  You need to understand what Oracle includes in their definition of runtime page customizations and what it considers outside of that.  The reason for this distinction is that some objects, like resources, may be created in a sandbox and only viewable within there, but they actually exist in the database rather than in the sandbox. 

Now, let’s look at an example of the whole process which shows the difference between how database objects and sandbox objects are handled.

If you were creating a disconnected application instance to provide an approval and audit trail for access to some system you would first create the sandbox.  With that sandbox active, you would create the App Instance, Resource, IT Resource Definition, and IT Resource, perhaps a Lookup or two as well.  So you export your sandbox to save a copy, and then publish it in your environment.  Everything works as expected without hiccups.

Now if you wanted to add that disconnected app instance to another system, you may think that since you have an exported sandbox that the only thing you need to do is import that sandbox and publish it.  If you were to do so, the sandbox would publish successfully and you might begin cheering.  If you then were to try and access your catalog, you will most likely be presented with any number of errors.  Most of them revolving around some Object or View Definition not being found as well as a NullPointerException or two.

The reason for this lies within the sandbox definition referenced earlier.  The user form, catalog entry, etc were contained within the sandbox as well as any modifications you may have done to them, but the App Instance, Resource, etc were not included.  Part of the reason for this division of objects is due to the fact that sandboxes only store front-end objects and modifications.  The Resource, IT Resource, etc are all back-end database objects.  These are objects you can interact with in design console or can view if you connect directly to the database and perform queries.

So now that I may have ruined your thoughts of some simple 1,2,3 process for migrating forms, you may be thinking it’s a complete and utter mess of a situation and its easier to recreate whatever you may need.  That’s the furthest thing from the truth.  You can migrate back-end objects as well as the sandboxes successfully, it just requires a couple more steps and some thought.

I mentioned Resources, IT Resources, and all the other fun objects to migrate.  If you’ve dealt with previous versions of OIM, then you are most likely familiar with Deployment Manager.  Deployment Manager (hereafter DM) allows the export/import of those back-end objects.

Exporting:

The first step to migrate a sandbox from one environment to another is to export the sandbox.  After that the database objects needed by your sandbox need to be exported using DM.  DM can be finicky from time to time.  My approach is to add objects one at a time to the export rather than select multiple categories and potentially have errors or conflicts.

First, search and select the Application Instance.  Select any children available.  Hold off on selecting Dependencies for the moment.

When that is finished, click “Add More” and then go and do the same thing for Resource (and children), IT Resource Definition and IT Resource.  When you are finished with those categories, export the file and save it.

If there are Lookups related to the App Instance, do them in a separate XML export all together.

You still need to export the Request Dataset.  Do so using DM.  Make sure to remove all children/dependencies since they will already be imported through the other XML we just finished.

The reason I am recommending breaking this process up into potentially three XML files is that DM seems to complain much less this way.  It is entirely possible this is extraneous work, but I haven’t narrowed down the situations where combined XML’s will and won’t work.

Modifications:

The final series of export steps is the biggest pain in the process.  You need to enter the previously saved sandbox zip file and go to /xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf  In this file there is first a section of User Defined Attributes at the top.  Leave those in the file.  Then there will be a series of Application Instance references.  You need to make sure that any Application Instances currently created in your destination environment (plus the one you are importing) are listed here with their fields.  If they are not, you need to create them manually.  Exporting a sandbox from the destination environment and getting the values from there is a good way to reduce any confusion.  Any Application Instances that are in the file that only exist in the source environment and not in the destination environment need to be eliminated.

Next you need to go in the sandbox zip file and modify /persdef/oracle/iam/ui/catalog/model/am/mdssys/cust/site/site/CatalogAM.xml.xml.  Here again you need to make sure that only the sandbox App Instance and destination App Instances are listed here.  If the destination App Instances are not listed here, again you need to create them.

If you don’t add current App Instance values from the destination system in either BizEditorBundle.xlf or CatalogAM.xml.xml, you will see ADF errors whenever the Catalog is called.

Importing:

Now you are prepared to import everything.  There are 2 categories of things to import: the database objects (in the form of the XML files you exported with DM) and the modified sandbox.

First import the XML files you created via DM.  Use DM to import them obviously.  You shouldn’t have to make any changes/substitution if its a fairly clean destination system.

After the XML files are imported, import the sandbox.  A quick test of everything is to activate the sandbox and then go to the catalog screen and search.  If you don’t get ADF errors here, you are probably good to go.  If you do get errors here, then there is something wrong with the sandbox and you need to verify that you removed the extraneous objects from the source system and added any additional objects from the destination system.  Fix those mistakes in the sandbox and re-import it.

You may notice that the fields are missing when you add the App Instance to your Cart when the Sandbox is activated.  This is because you need to reassociate the App Instance and the form.  Login to sysadmin, activate the sandbox, and go to the Application Instance.  The form dropdown is probably blank.  Select the proper form and hit apply.

Also, double-check the Organizations tab.  Verify that Top is included and “include sub-orgs” is checked as well.  Click Apply again.

 

Assuming you made all of the proper modifications and you are not seeing any errors in the activated sandbox, you can publish the sandbox and your disconnected application instance will be present in your destination system.

 

Note 1: Just because you have created a database object (i.e. an IT Resource) in a sandbox does not mean that the main MDS line or other sandboxes can use that IT Resource.  Until that sandbox is published, that IT Resource is inaccessible (in most cases) from the non-Sandboxed experience.

Note 2:  One reference that everyone should review is: http://docs.oracle.com/cd/E27559_01/dev.1112/e27150/uicust.htm#BABBBIAJ.  Managing concurrency conflicts explains what will/won’t cause issues when you have multiple people working in the same/multiple sandboxes as well as when multiple sandboxes will conflict with one another.  These couple paragraphs can save many headaches.  The concurrency concepts listed here dictate the modifications we needed to make in the sandboxes.