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:
- UNIX Linux : ./ConfigEngine.sh register-iwidget-definition -DIWidgetDefinition=IWidget Definition URL -DIWidgetCatalog=dav:fs-type1/iwidgets/IWidget_name/catalog.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadmin
- IBM i:
- From the UserData directory: ConfigEngine.sh register-iwidget-definition -DIWidgetDefinition=IWidget Definition URL -DIWidgetCatalog=dav:fs-type1/iwidgets/IWidget_name/catalog.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadmin
- Windows : ConfigEngine.bat register-iwidget-definition -DIWidgetDefinition=iwidget_Definition_URL -DIWidgetCatalog=dav:fs-type1/iwidgets/IWidget_name/catalog.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadmin
Mandatory parameters that we can specify through the command line or in wkplc.properties:
Mandatory parameters specified only through the command line:
- WasUserid
- User ID for WebSphere Application Server
- WasPassword
- Password that corresponds to the user ID for WebSphere Application Server
- PortalAdminId
- Administrator ID for HCL WebSphere Portal
- PortalAdminPwd
- Password that corresponds to the administrator ID for HCL WebSphere Portal
- WPS_SOAP_PORT
- SOAP port that connects the portal server to remote connections
Optional parameters specified only through the command line:
- IWidgetDefinition
- URL of the iWidget definition XML file
Assumptions/Prerequisites: HCL WebSphere Portal is running. If HCL WebSphere Portal is not running, the task will start it.
- IWidgetCatalog
- URL of an IBM Mashup Center catalog XML file. If we specify this parameter, 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 that points to the same iWidget definition file as the parameter IWidgetDefinition or the IWidget Wrapper portlet clone that is 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 we run the task 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 we specify this parameter, 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 this parameter is specified, a new iWidget Wrapper portlet will be created with a unique name as specified by this parameter. If this parameter is specified, the task always creates a new iWidget Wrapper portlet clone independent of the given IWIdgetDefinition URL that is already being registered at portal.
Note: If the given unique name is already assigned to some other resource, the task fails and no IWidget Wrapper portlet is created.
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:
./ConfigEngine.sh register-iwidget-definition -DPortletUniqueName="someWidget" -DIWidgetDefinition=http://server_name:port_number/someWidget/someWidget/someWidget.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadminYou can refresh the IWidget Wrapper portlet clone with the unique name someWidget:./ConfigEngine.sh register-iwidget-definition -DPortletDefinition="someWidget" -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadminYou 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:./ConfigEngine.sh register-iwidget-definition -DIWidgetDefinition=http://server_name:port_number/someWidget/someWidget/someWidget.xml -DIWidgetCatalog=http://server_name:port_number/someWidget/someWidget/catalog.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadminYou 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:./ConfigEngine.sh register-iwidget-definition -DPortletDefinition="someWidget" -DIWidgetCatalog=http://server_name:port_number/someWidget/someWidget/catalog.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadminYou 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:./ConfigEngine.sh register-iwidget-definition -DIWidgetCatalog=http://server_name:port_number/catalog.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadminNotes:
- 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. 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.
- 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.
- 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.
- 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:./ConfigEngine.sh register-iwidget-definition -DIWidgetDefinition=/someWidget/someWidget/someWidget.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadminDo 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:wp.proxy.config.urlreplacement.default_policy.someID=http://some.server.com:10039/*Notes:
- 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.
- 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:dav:fs-type1/path_to_your_IWidget_definition_XML_fileFor 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:./ConfigEngine.sh webdav-deploy-zip-file -DZipFilePath=/tmp/SomeWidgetPackage.zip -DTargetURI=dav:fs-type1/iwidgets/SomeWidget/ -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadminThis 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:./ConfigEngine.sh register-iwidget-definition -DIWidgetDefinition=dav:fs-type1/iwidgets/SomeWidget/someWidget.xml -DPortalAdminPwd=wpsadmin -DWasPassword=wpsadmin
Parent topic: Manage iWidgets in the portal