Object IDs in XML scripts

All resources in HCL Portal, except for the resources portal and the settings, have an object ID that uniquely identifies them in the portal. That ID is generated by the portal when the resource is created. These object IDs are represented by the objectid attributes in an XML export.

References between resources are represented by these object IDs: One resource has a reference attribute that contains the object ID of another resource. For example, a portlet instance that is to be displayed on a page must reference a portlet. Therefore the portletinstance tag has a portletref attribute that corresponds to the objectid attribute of the portlet. Consequently, you see the following snippets in an XML export:

<portlet action="update" . . . objectid="Z3_G0Q03FH200A5202QRHAG4320G0" . . . >
      . . .
<portletinstance action="update" . . . portletref="Z3_G0Q03FH200A5202QRHAG4320G0" . . . >

All resources get an object ID assigned in the portal when they are created. That object ID can not be altered later. When you create new resources in the portal administrative user interface, they automatically get a new object ID generated by the portal. When you create a new resource with XML, it also always gets a new object ID, if you do not specify one in the XML. Note that you can not simply "invent" object IDs for new resources, because they must conform to a correct internal representation. The only way to get valid object IDs is from an XML export.

In XML scripts the objectid attribute of a resource is used for the following purposes:

  • To look up the resource, if the action is locate, export, update or delete.
  • To set the object ID for a new resource, if the action is create.
  • To set the object ID for a new resource, if the action is update and no resource with that object ID exists.
  • To describe links from one resource to another.

You can use object IDs to uniquely specify resources that you want to administer. For example, the following snippet deletes a specific known page. (You would normally get the object ID of the page from an XML export.)

   <content-node action="delete" objectid="Z6_G0Q03FH200A5202QRHAG4320O0"/>

The following snippet looks up a page with a specific object ID. If it cannot find the object ID, it creates it. If it already exists, it updates it.

   <content-node action="update" objectid="Z6_G0Q03FH200A5202QRHAG4320O0" type="page" . . . >

The next snippet creates or updates a theme with a specific object ID and then assigns that theme to a label:

        <theme action="update" objectid="ZJ_G0Q03FH200A5202QRHAG4320S1" . . .>
            . . .
        <content-node action="update" objectid="Z6_G0Q03FH200A5202QRHAG4320O0" 
                     type="label" themeref="ZJ_G0Q03FH200A5202QRHAG4320S1" . . . >

If the theme already exists with the specified object ID, you can directly use that object ID in references without having to include the theme in the XML script. The next snippet assumes that the theme has already been created. For example, it might have been copied from another server in a previous step. Therefore the snippet only assigns the theme to the label:

        <content-node action="update" objectid="Z6_G0Q03FH200A5202QRHAG4320O0" 
             type="label" themeref="ZJ_G0Q03FH200A5202QRHAG4320S1" . . . >

In this case, the theme is looked up in the portal data store using its object ID ZJ_G0Q03FH200A5202QRHAG4320S1. If no theme with that object ID is defined in the portal, you get an error during the XML validation.

An object ID is globally unique. Two object IDs that were automatically generated by different portal installations can never be the same. Therefore you can exchange resources between different portal installations using XML export and update requests without having to worry about possible object ID conflicts. The only way that you can ever duplicate an object ID is by transferring a resource (including the object ID) to another portal with an XML export and update.

In many cases, this is the required behavior. However, 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.