Tuesday, August 11, 2009

WebSphere Portal XMLAccess: discover different ways to refer resources in XML script

One of the important topics in XMLAccess is how to refer existing resources in portal. In most cases, three kinds of concepts are used, they are ObjectID, Symbolic object ID, and unique name. Here I make a comparison between them.

Comparison between ObjectID, Symbolic object ID, and unique name

Object ID

ID generating mode

Object Id

(Symbolic object ID)

Unique name

Used to Lookup of portal rescources

Yes. Globally uniqe.

No

Yes

Mandatory

Almost all portal resources have an objectid

Optional

Optional

Generation

Generated by portal when resource is created. The only way to get object IDs is from an xml report. Two object IDs that were automatically generated by different portal installations can never be the same.

Defined in xml file by user.

Set in Custom Unique Names portlet by user.

Representation in xml

objectid

objectid

uniquename

Object ID

Sample

      . . .

Usage

Use "real" object IDs in your scripts, when you want the objects in your XML to retain their identity. For example, when you use an XML export request and the resulting response file to copy a resource from a staging to a production system, the resource is created on the production system with the same object ID as on the staging system. This way you can establish a correspondence between the two resources. When you later transfer the same resource again, the XML processing looks up the resource by its object ID, finds that it already exists, and updates the existing resource instead of creating a new one.

ID generating mode

The ID generating mode is useful if you want to create an XML script that installs a group of new resources and is executed on many different portal installations.

Symbolic Oject ID

Sample

       . . .

Usage

·        If you do not want to copy the same resource to another portal, but you want to create a new resource instead, regardless of existing OIDs and without any chance of causing conflicts, you must either use symbolic object IDs or delete the objectid attribute from the XML script. In the latter case the portal creates a new object ID.
·        You might need to use objectid attributes to express references between resources in your XML script, but you do not want these to be read from or written to the portal database. For example, you might want to create a new theme and page, and reference the theme in the page. Nevertheless you want to let the portal chose an object ID for it because you do not want to accidentally overwrite an existing resource.
Restrictions
·        As the object ID values are purely symbolic, you cannot use them in a reference without first "defining" them in the same XML script. Before you can use the portletref="Welcome_Portlet" attribute specification in an XML update, you must also have a portlet with objectid="Welcome_Portlet" defined in the same XML; otherwise a syntax error is reported.
·        if you update a page layout in ID generating mode, all existing components of the page will be deleted and a new layout will be created instead - even if the new layout is identical to the old one ! This happens because components can only be looked up by their object IDs and lookup by object ID is not possible in ID generating mode. Therefore all the components specified in the XML are created, because they cannot be found for updating, and all existing components are deleted because they were not updated.

Unique Name

Sample

>

Usage

· When the real object id is unknown, you could use unique name to identify resource.

· As object IDs are not used to identify existing resources in ID generating mode, it is good practice to define unique names for all resources that are created in such scripts. That way, if the script is executed twice, the second execution can find and update the resource by its unique name, instead of creating two identical resources.

Restrictions

When you create a nested element, for example a component, with a uniquename attribute, the whole hierarchy upward from that element must also have uniquename attributes. Example XML export request snippet:

     
          
               
                    
                         . . . . .
                    
               
                                 
     

Example of the difference between object id and unique name

Since object id and unique name could be used to look up resources, what is the difference between them? Here is an example:

The following two screenshots come from two portal servers, lets it name is server A and server B.

Server A and Server B:


We see My Portal Page in both servers has the same unique name.

Now, lets export My Portal Page to see its object id in both servers (object id can only be get from xml report)

ServerA :

objectid="_6_00CG4NKRS908IPNN_35" ordinal="100" themeref="_J_00CG4NKRS908IPNN_3B" type="label" uniquename="wps.My Portal">

ServerB :

objectid="_6_00CG41HIKD082HH8_35" ordinal="100" themeref="_J_00CG41HIKD082HH8_3B" type="label" uniquename="wps.My Portal">

Therefore, if you want to create new resources on different installations and do not want to overwrite the existing ones, unique name is recommended. Unique name is installation independent.

Other ways to lookup of portal resources

Of course, there are other ways to lookup portal resource when object id and unique name are not given or failed to find.

In any case the lookup process first tries to find the resource by its object ID, if specified, and then by its unique name, if that is specified. Only when those attempts fail, other attributes are used for locating the resource.

Resource key

Attributes used for locating the resources

portal, global-settings, services-settings

None; these items always exist only once.

markup, virtual-resource, user, group, credential-segment, credential-slot, portlet

name

event-handler

classname

web-app, portlet-app

uid

servlet

refid

portletinstance

None; there is at most one portletinstance per component.

url-mapping-context

label

Resources

WebSphere Portal V6.0 InfoCenter.