+

Search Tips   |   Advanced Search

Task register-iwidget-definition

Run the portal configuration task register-iwidget-definition to register individual iWidget definitions on HCL WebSphere Portal.

Identify the iWidget definition by an absolute URL that points to the iWidget definition XML file. Executing this task downloads the iWidget definition XML file from the specified location and creates a corresponding iWidget Wrapper portlet clone. If an iWidget Wrapper portlet clone for the given iWidget URL exists already, no new portlet clone is created, but the existing portlet is updated with the information loaded from the specified iWidget definition XML file.

Syntax: Invoke this task as part of the ConfigEngine script file as follows:

Mandatory parameters that we can specify through the command line or in wkplc.properties:

Mandatory parameters specified only through the command line:

Optional parameters specified only through the command line:

Assumptions/Prerequisites: HCL WebSphere Portal is running. If HCL WebSphere Portal is not running, the task will start it.

Error Conditions: NoneTask dependencies: NoneTasks invoked: NoneExamples: We can register the iWidget definition XML file located at http://server_name:port_number/someWidget/someWidget/someWidget.xml as follows:

You can refresh the IWidget Wrapper portlet clone with the unique name someWidget:

You can register the iWidget definition XML file located at http://server_name:port_number/someWidget/someWidget/someWidget.xml considering titles and descriptions from the Mashup Center catalog XML file located at http://server_name:port_number/someWidget/someWidget/catalog.xml:

You can refresh the IWidget Wrapper portlet clone with the unique name someWidget, considering titles and descriptions from the Mashup Center catalog XML file located at http://server_name:port_number/someWidget/someWidget/catalog.xml:

You can perform a bulk registration of iWidget definition XML files or a refresh of IWidget Wrapper portlet clones by using an Mashup Center catalog XML file:

Notes:

  1. The URL can point to the portal server itself or to an external server. Configure the portal AJAX proxy to allow access to that server. For details refer to the following section.

  2. If the definition element of an entry in the Mashup Center catalog XML file contains a relative URL, the URL is resolved into an absolute form using the URL from the IWidgetCatalog parameter as a base URL. Only that absolute URL is used for further processing such as accessing the iWidget definition XML file. The absolute URL is also compared with the IWidgetDefinition parameter value or the iWidget definition URL of the IWidget Wrapper portlet clone identified by the PortletDefinition parameter in order to determine whether or not to consider titles and descriptions from the catalog XML file entry when parsing creating or updating the IWidget Wrapper portlet clone.

  3. The register-iwidget-definition task only updates titles and descriptions of an IWidget Wrapper portlet clone when set the following portlet preferences to true: com.ibm.portal.replace.titles and com.ibm.portal.replace.descriptions.

  4. When the titles and the descriptions of an IWidgetWrapper portlet clone are set using values from an IBM Mashup Center catalog XML file, the portlet preferences com.ibm.portal.replace.titles (default: true) and com.ibm.portal.replace.descriptions are set to false on the IWidget Wrapper portlet clone. Those portlet preferences prevent the titles and the descriptions of the IWidget Wrapper portlet clone from being overwritten when performing subsequent updates. This is particularly useful when running the register-iwidget-definition task to update all IWidget definitions registered in HCL WebSphere Portal. The task only considers iWidget definitions that comply with the iWidget specification and does not process IBM Mashup Center catalog XML files.

  5. When you refresh IWidget Wrapper portlet clones, values of iWidget attributes ( items of the iWidget attributes item set) are not updated unless the attributes are flagged as read only in the iWidget definition XML file. As a result, values of iWidget attributes customized after registering the iWidget in HCL WebSphere Portal are prevented from getting lost during a refresh operation.


Register an iWidget hosted on a Portal server

To register iWidgets deployed as WAR or EAR files directly on the portal server, we can use server relative URLs pointing to the corresponding iWidget definition XML files; for example:

Do not forget the leading slash "/" in your iWidget definition URL.


Register an iWidget hosted on an external server

If we use an iWidget definition URL that points to a server different from the portal server, we need to make sure that your current AJAX proxy configuration allows accessing this server. For details about this refer to the topics about AJAX proxy Configuration. One way of configuring this is to make sure that the URL to the iWidget definition XML file is mapped to the default_policy dynamic policy in the global AJAX proxy configuration file. We can map a given URL, for example http://server_name:port_number/someWidget/someWidget/someWidget.xml, to that policy by adding a custom property such as the following to the WP ConfigService Resource Environment Provider in the WebSphere Application Server administrative console:

Notes:

  1. The updated policy will not be effective until you restart either the portal server or the AJAX proxy Configuration enterprise application running on the portal server.

  2. If we use a URL prefix, do not omit the trailing asterisk ( * ).


Register light weight iWidgets stored in the WebDAV file store

Additional to HTTP or HTTPs based iWidget definition URLs, we can also use WebDAV file store URIs pointing to iWidget definition XML files located in the WebDAV file store. Such URIs have the following format:

For example, we might have an archive or compressed file with a light weight iWidget that contains an iWidget definition XML file called someWidget.xml in the file root folder of the archive or compressed file. In this case you typically first copy the archive or compressed file to the WebDAV file store by using a generic WebDAV client or using the configuration task webdav-deploy-zip-file as follows:

This extracts your light weight iWidget package represented by the file /tmp/SomeWidgetPackage.zip into the folder /iwidgets/SomeWidget of the WebDAV file store. Make sure to add the trailing slash ( / ) in the parameter TargetURI. After the extraction we can register the iWidget definition XML file someWidget.xml as follows:

Parent topic: Manage iWidgets in the portal