+

Search Tips   |   Advanced Search

Task register-iwidget-definition


To register individual iWidget definitions, run the portal configuration task...

Identify the iWidget definition by an absolute URL pointing 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:

./ConfigEngine.sh register-iwidget-definition  \
                 -DIWidgetDefinition=http://server:port/path/to/definition.xml \
                 -DIWidgetCatalog=dav:fs-type1/iwidgets/IWidget_name/catalog.xml  \
                 -DPortalAdminPwd=wpsadmin  \
                 -DWasPassword=wpsadmin


Parameters specified through command line or in wkplc.properties

WasUserid User ID for WAS
WasPassword Password that corresponds to the user ID for WAS
PortalAdminId Administrator ID for WebSphere Portal
PortalAdminPwd Password that corresponds to the administrator ID for WebSphere Portal
WPS_SOAP_PORT SOAP port that connects the portal server to remote connections


Parameters specified through command line only

IWidgetDefinition URL of the iWidget definition XML file


Parameters specified through command line only

IWidgetCatalog URL of an IBM Mashup Center catalog XML file. If specified the task register-iwidget-definition parses the referenced catalog XML file to register IWidget definitions or to refresh existing IWidget Wrapper portlet clones. If the parsed catalog XML file contains an entry with a definition element pointing to the same iWidget definition file as the parameter IWidgetDefinition or the IWidget Wrapper portlet clone identified by the parameter PortletDefinition , the titles and descriptions from the matching catalog entry are considered for creating or updating the IWidget Wrapper portlet clone. More precisely, the titles and descriptions from the catalog entry are only set on the IWidget Wrapper portlet clone if the corresponding iWidget definition does not define the titles or descriptions in its idescriptor item set. When you run register-iwidiget-definition and provide the IWidgetCatalog parameter but omit IWidgetDefinition and PortletDefinition, IWidget Wrapper portlet clones for all iWidget definitions referenced in the given catalog XML file are created or updated.
PortletDefinition Unique name or serialized ObjectID of an iWidget Wrapper portlet clone to refresh. If specified the task register-iwidgetdefinition performs a refresh of the referenced iWidget Wrapper portlet clone. This means that the iWidget definition referenced by the existing iWidget Wrapper portlet clone is parsed again to update the portlet.
PortletUniqueName If specified, a new iWidget Wrapper portlet will be created with a unique name as specified by this parameter. If specified, the task always creates a new iWidget Wrapper portlet clone independent of the given IWIdgetDefinition URL that is already being registered at portal.

If the given unique name is already assigned to some other resource, the task fails and no IWidget Wrapper portlet is created.

Examples: We can register the iWidget definition XML file located at...

...as follows: 

./ConfigEngine.sh register-iwidget-definition \
                 -DPortletUniqueName="someWidget" \
                 -DIWidgetDefinition=http://server:port/someWidget/someWidget/someWidget.xml   \
                 -DPortalAdminPwd=wpsadmin 
                 -DWasPassword=wpsadmin

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

./ConfigEngine.sh register-iwidget-definition 
                 -DPortletDefinition="someWidget"
                 -DPortalAdminPwd=wpsadmin 
                 -DWasPassword=wpsadmin

We can register the iWidget definition XML file located at...

...considering titles and descriptions from the Mashup Center catalog XML file located at... 

./ConfigEngine.sh register-iwidget-definition \
                 -DIWidgetDefinition=http://server:port_number/someWidget/someWidget/someWidget.xml \
                 -DIWidgetCatalog=http://server:port_number/someWidget/someWidget/catalog.xml   \
                 -DPortalAdminPwd=wpsadmin  \
                 -DWasPassword=wpsadmin

We 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... 

./ConfigEngine.sh register-iwidget-definition \
                 -DPortletDefinition="someWidget" \
                 -DIWidgetCatalog=http://server:port_number/someWidget/someWidget/catalog.xml \
                 -DPortalAdminPwd=wpsadmin  \
                 -DWasPassword=wpsadmin

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

./ConfigEngine.sh register-iwidget-definition \
                 -DIWidgetCatalog=http://server:port_number/catalog.xml \
                 -DPortalAdminPwd=wpsadmin  \
                 -DWasPassword=wpsadmin

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.

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. Onlthat 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.

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

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...

...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 register-iwidget-definition to update all IWidget definitions registered in WebSphere Portal. The task only considers iWidget definitions that comply with the iWidget specification and does not process IBM Mashup Center catalog XML files.

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 WebSphere Portal are prevented from getting lost during a refresh operation.


Registering 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: 

./ConfigEngine.sh register-iwidget-definition 
                 -DIWidgetDefinition=/someWidget/someWidget/someWidget.xml
                 -DPortalAdminPwd=wpsadmin 
                 -DWasPassword=wpsadmin

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


Registering an iWidget hosted on an external server

If we use an iWidget definition URL that points to a server different from the portal server, verify the 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 verify 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...

...to that policy by adding a custom property such as the following to the WP ConfigService Resource Environment Provider in the WAS administrative console:

  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 ( * ).


Registering 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: 

dav:fs-type1/path_to_your_IWidget_definition_XML_file
For example, we might have an archive or compressed file with a light weight iWidget containing 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 using a generic WebDAV client or using the configuration task webdav-deploy-zip-file as follows: 

./ConfigEngine.sh webdav-deploy-zip-file  \
                 -DZipFilePath=/tmp/SomeWidgetPackage.zip  \
                 -DTargetURI=dav:fs-type1/iwidgets/SomeWidget/ \
                 -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadmin

This extracts the 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: 

./ConfigEngine.sh register-iwidget-definition  \
                 -DIWidgetDefinition=dav:fs-type1/iwidgets/SomeWidget/someWidget.xml  \
                 -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadmin


Parent: Manage iWidgets in the portal