Clarity PPM: General Migration XOG Guidelines
search cancel

Clarity PPM: General Migration XOG Guidelines

book

Article ID: 54133

calendar_today

Updated On:

Products

Clarity PPM On Premise

Issue/Introduction

What are the general guidelines to migrate data from one environment to another using XML Open Gateway (XOG)?
What are the general migration XOG guidelines to keep in mind when migrating Clarity data from one environment to the another?

 



Environment

Release:
Component: STUDIO

Resolution

The following information may be used as a recommendation to follow for both stock and custom objects between like Clarity installations.

Generally, work in reverse order of the content pack structure in order to ensure dependencies are brought over first

  • Divide the content pack into smaller discrete chunks (always a good idea to remove views and XOG these separately)
  • Dependent lookups need careful attention and sometimes correction post-XOG
  • It is more reliable to do dynamic lookups after objects
  • Views can be made to work; with effort. Views for inactive partitions and "detached" partitions should NOT come out in the XOG output but we've found that they do. These will need to be removed from the write XML.

IMPORTANT: If at any time errors are encountered due to corrupt or invalid XML, reduce the number of items in the section you are working with to 1 and if successful, continue adding another 1 at a time until the culprit is found or the objects are successfully brought over.

General Order for Migration XOG:

  1. Entities, Departments, Locations and Fiscal Time periods
  2. Any additional (regular) OBS structures other than Financial OBS units 
  3. Partitions
  4. Investment Type (INV_TYPE) static dependent lookups - XOG individually. This type of lookup does not XOG out correctly when included in the Project Object and if included may throw an error.
  5. Project Object. (very tricky must be done carefully - see details below)
  6. Other Objects & Views. (much more simple than the project object). Same concept though. Scale down the objects and views to just what is needed.
  7. Portlets and Portlet Pages
  8. Report Definitions
  9. Processes. It's important to separate out "template" processes from regular ones. We found at least at 8.1FP03 that if you combine say a process tied to an idea and a template process tied to the project object in the same XOG XML, the resulting idea process will be tied to the project template! So I keep them in separate XOG XML files. The safest bet by far is to have one file per process.
  10. Instance data (users, resources, projects, etc...)

Project Object XOG:

Step(1) Check and see if the project object has any attributes which are tied to lookups with queries which hit any other custom objects. These custom objects and their respective lookups must be xogged in prior to this object. Navigate (Admin Tool=>Lookups), filter by clicking on the binoculars and select the object. A list of all associated lookups to this object will be returned. Review these lookups. If they have queries which reference a custom object, make sure that the object also exists on the destination environment otherwise you'll encounter dependency errors.

Step(2) Once associated custom objects and their lookups have been taken care of, you need to make note of all the remaining project object lookup ID's and the source for each one as this will be used in the XML read file in step(3).

NOTE: In the example XML read file, there are 3 possible types (source) of lookups that can be extracted (Dependent, Static, Dynamic). It's imperative that you place the correct lookup ID in the correct filter when this is run, otherwise XOG won't find them. You can simply copy/paste the appropriate filter within the XML for use if there are multiple lookups of each source type to bring over.

Step(3) Once these lookups are identified, then you can modify a copy of the content_pack.xml read file to bring them out. The lookups of source "Dependent" should be Xogged out and into the destination first, then "Static". Lookups of type "Dynamic" will be brought over after the project object has been Xogged. In the example below, you would replace the lookup code placeholders with the actual lookup codes within the proper filter and can delete the other filters that are not being used. Save each "read" XML as a separate file with a meaningful name.

Sample Lookup read XOG:

<?xml version="1.0" encoding="UTF-8"?> 
<NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="../xsd/nikuxog_read.xsd"> 
<Header version="14.2.0.237" action="read" objectType="contentPack" externalSource="NIKU"> 
<!-- the contentType is used to determine which filter goes where --> 
<args contentType="job_definition" name="order_by_1" value="code"/> 
<args contentType="menu" name="order_by_1" value="code"/>
<args contentType="view" name="order_by_1" value="code"/> 
<args contentType="process" name="order_by_1" value="code"/> 
<args contentType="object" name="order_by_1" value="code"/>
</Header> 
<LookupQuery> 
<!-- Dependent Lookup --> 
<Filter name="code" criteria="EQUALS">PLACE DEPENDENT LOOKUP ID HERE</Filter> 
</LookupQuery> 
<LookupQuery> 
<!-- Static lookup --> 
<Filter name="code" criteria="EQUALS">PLACE STATIC LOOKUP ID HERE</Filter> 
</LookupQuery> 
<!-- Dynamic Lookup --> 
<LookupQuery> 
<Filter name="code" criteria="EQUALS">PLACE DYNAMIC LOOKUP ID HERE</Filter> 
</LookupQuery> 
<ObjectQuery> 
<Filter name="object_code" criteria="EQUALS">PLACE OBJECT ID HERE</Filter>
</ObjectQuery> 
</NikuDataBus>

NOTE: Once you have these Xogged out, check the order for the other included static-dependent lookups. They are often out of order (child before parent) and will throw an error when xogging in. Just re-arrange the order of the static-dependents to be parent first.

NOTE: In some cases our services folks have found attribute descriptions on the LIST view that had malformed captions <nls> sections without a "name" attribute. If you encounter this, you'll have to manually remove these before Xogging or an invalid XML error will be thrown.

Step(4) Once these dependent and static lookups are successfully in the destination server, you can bring over the project object itself without any views, partition data, portlets or pages. Just the object. Use the object_read.xml to bring out the object which will create a "write" XML file. Be sure to save a copy of the full object XML for use in each step so you don't overwrite your original XOG.

Sample Object read XML:

<?xml version="1.0" encoding="UTF-8"?>
<NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="../xsd/nikuxog_read.xsd"> 
<Header version="14.2.0.237" action="read" objectType="contentPack" externalSource="NIKU">
<!-- the contentType is used to determine which filter goes where -->
<args contentType="job_definition" name="order_by_1" value="code"/>
<args contentType="menu" name="order_by_1" value="code"/>
<args contentType="view" name="order_by_1" value="code"/> 
<args contentType="process" name="order_by_1" value="code"/> 
<args contentType="object" name="order_by_1" value="code"/> 
</Header>
<ObjectQuery> 
<Filter name="object_code" criteria="EQUALS">project</Filter> 
</ObjectQuery>
</NikuDataBus>

Step (5) Once the object itself has been successfully Xogged into the destination, you can then bring over any "Dynamic" lookups using the template in step(3).

Step(6) Once the object is in, it's time for the views. These are very tricky. List views should be brought over first, then any PropertySet, Property then finally Filter.

NOTE: XOG in the views by themselves, PER PARTITION. Remove all other "stuff" that comes out with them (lookups, objects, partition Model). These have already been sent, so are just extra stuff you don't need.

Additional Information

Q. Does XOG do notes?


XOG will not be able to migrate specific Clarity notes on time periods, projects, and tasks.

The out-of-box notes is not an attribute which is under project object. When reviewing the prj_projects_write.xml , it referes to the name space "nikuxog_project.xsd"
<NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_project.xsd">

Upon opening and inspecting the XSD file, the list of attributes shown is what XOG allows, however PRNOTE is not included.


Q. How can the XML Open Gateway (XOG) client be obtained?


Go to Administration > General Settings > Client Downloads 


Choose either the Windows or Unix(cross-platform) version and unzip it a CLARITY_XOG_LOCATION on the local computer.  

https://ent.box.com/shared/static/eokq2mbzt6r2746jlgkd5u1atwteb7zr




 
Powered by Wolken Software