This document describes the functionality provided by the IBM WebSphere Portal (WP) plugin.
The Websphere Portal plugin is an XL Deploy plugin that extends the capabilities of the XLD Websphere plugin for managing deployments and resources on an existing WebSphere Portal server. It offers out of the box support for deploying, updating and undeploying portlets developed using the IBM-API or JSR-268. Also the capability to run user supplied xmlaccess scripts.
- Deploy, update and undeploys Portlets packaged in Web applications archives (WAR).
- Manage Access Permissions
- Manage Preferences
- IBM-API type portlets
- JSR-268 type portlets
- XML access script execution
- Template support
- Placeholder support
- XLD Server 5+
- XLD Websphere Plugin 5+
- IBM WebSphere Portal 6.1, 7.0 and 8.0
Plugin can be downloaded directly from the plugin's repository on Github.
Place the plugin XLDP file into <xld-home>/plugins directory. Make sure you have the Websphere plugin mentioned in the requirements section also installed.
This plugin adds configuration settings under the Portal tab of the was.DeploymentManager and was.Cluster for managed environments and in was.UnmanagedServer for unmanaged environments. If there are two or more different portal clusters defined in your environment, please specify the values in was.Cluster. If you do not have different portal clusters, than specifying it in was.DeploymentManager should be sufficient.
All properties are required.
| Property | Description |
|---|---|
| portalHost | The host xml access is on |
| wpHome | Location of WebSphere Portal on the primary node. e.g C:\IBM\WebSphere\PortalServer |
| wpProfileLocation | The location of the portal profile |
| wpConfigUrl | The URL of the WebSphere Portal configuration API. e.g http://localhost:10039/wps/config |
| wpAdminUsername | Username of the administrative user |
| wpAdminPassword | Password of the administrative user |
The Portlet War (wp.War) configuration item can be defined in a deployment package. wp.War extends the default behaviour of the was.War with additional settings under the Portal tab to describe the Portal application.
| Property | Description |
|---|---|
| portalAppName | Name for the portal application |
| portalAppUid | Unique identifier for the portal application as defined in the portal.xml |
| portalAppConcreteUid | Concrete Unique identifier for the portal application as defined in the portlet.xml. Only required for IBM-API type portlets |
| disableDeregisterOnUninstall | Disables deregistration of portlets on uninstall of application. |
The portlets that are contained in the War are described using the wp.PortletSpec type. This type is a child of the wp.War
| Property | Description |
|---|---|
| portletName | Name of the portlet as described in the portlet.xml |
| uniqueName | Unique name for portlet. e.g. com.xebialabs.WelcomePortlet. Optional |
| preferences | Preferences for the portlet described as a key value map. Optional. |
| clones | See Defining portlet clones below. Optional. |
| authLevel | The String representation of the associated auth level. Only used when step-up authentication is enabled. Optional. |
| userAclMapping | See access permissions below. Optional. |
| groupAclMapping | See access permissions below. Optional. |
Portlet access permissions can be defined under the Security tab. The permission can be captured for a user or user_group as a key value map. The key being the desired security level. The value should container the desired subject ids delimited by a pipe (|). Valid security levels are,
- user
- privileged user
- contributor
- editor
- manager
- delegator
- security administrator
- administrator
Portlets which need to be cloned can be specified using the wp.PortletCloneSpec type. This type is a child of wp.PortletSpec. A clone of a portlet is an instance of a portlet with it's own name and specifications like preferences. Therefore it needs some propterties of which some are like a normal portlet.
| Property | Description |
|---|---|
| cloneName | A clone name needs $cloned in the name. If you fully specify the clone name here e.g. welcomePortlet.$cloned.clone1 then it will be used. If only a simple name is used then a full name is generate with portletName and this name, e.g. portletName=welcome-portlet and cloneName = clone1 makes name welcome-portlet.$cloned.clone1. |
| uniqueName | Unique name for portlet. e.g. com.xebialabs.WelcomePortlet. Optional |
| preferences | Preferences for the portlet described as a key value map. Optional. |
| defaultLocale | A default locale which describes the portlet. Needs to be in the localedata list |
| localedata | See Locale data below |
| authLevel | The String representation of the associated auth level. Only used when step-up authentication is enabled. Optional. |
| userAclMapping | See access permissions above. Optional. |
| groupAclMapping | See access permissions above. Optional. |
A portlet Clone needs like name and description, this can be specified using the wp.PortletCloneLocaleDataSpec type. This type is a child of wp.PortletCloneSpec. For portlets this is normally stated in the portlet.xml, but for clones this needs to be added, as it is probably different then the original portlet. One locale needs to be setup, and be referred as default locale for the clone. All other locales are optional.
| Property | Description |
|---|---|
| locale | The locale. e.g. en |
| title | Portlet title in specified locale. |
| description | Portlet descriptions in specified locale. Optional. |
| keywords | Portlet keywords in specified locale. Optional. |
<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="1.0" application="IBMPortletApp">
<deployables>
<wp.War name="WelcomePortlet.war" file="WelcomePortlet.war/WelcomePortlet.war">
<contextRoot>/wps/PA_WPS_XLD_Welcome</contextRoot>
<portalAppName>Welcome</portalAppName>
<portalAppUid>com.ibm.wps.portlets.welcome</portalAppUid>
<portalAppConcreteUid>com.ibm.wps.portlets.welcome.1</portalAppConcreteUid>
<portlets>
<wp.PortletSpec name="WelcomePortlet.war/WelcomePortlet">
<portletName>Welcome Portlet</portletName>
<uniqueName>com.xebialabs.welcomeportlet</uniqueName>
<preferences>
<entry key="apref">apref_value</entry>
</preferences>
<userAclMapping>
<entry key="user">anonymous portal user</entry>
</userAclMapping>
<groupAclMapping>
<entry key="user">all authenticated portal users</entry>
</groupAclMapping>
<clones>
<wp.PortletCloneSpec name="WelcomePortlet.war/WelcomePortlet/clonespec1">
<cloneName>clone1</cloneName>
<preferences>
<entry key="apref">apref_value_for_clone</entry>
</preferences>
<defaultlocale>en</defaultlocale>
<localedata>
<wp.PortletCloneLocaleDataSpec name="WelcomePortlet.war/WelcomePortlet/clonespec1/en">
<locale>en</locale>
<title>Welcome Portlet Clone</title>
</wp.PortletCloneLocaleDataSpec>
</localedata>
<userAclMapping>
<entry key="user">anonymous portal user</entry>
</userAclMapping>
<groupAclMapping>
<entry key="user">all authenticated portal users</entry>
</groupAclMapping>
</wp.PortletCloneSpec>
</clones>
</wp.PortletSpec>
</portlets>
</wp.War>
</deployables>
</udm.DeploymentPackage>The plugin offers configuration item types wp.XmlAccessScriptPair and wp.XmlAccessInlineScriptPair that can be defined in a deployment package. The user should provide the xmlaccess script to execute on the target portal server. The xmlaccess script can contain Freemarker templating logic that will be resolved by the plugin before execution. Freemarker variable deployed is available to the template to resolve properties.
The types also allow the user to supply an optional rollback xmlaccess script that would undo the main xmlaccess script.
Both types have the same functionality except for the location of the xmlaccess script to execute. wp.XmlAccessInlineScriptPair defines the script as a property on the configuration item, whereas wp.XmlAccessScriptPair is an artifact folder containing the files to execute.
A resource containing inline XmlAccess scripts that are used for deployment and rollback.
| Property | Description |
|---|---|
| applyScript | XmlAccess to execute on deployment |
| unapplyScript | XmlAccess to execute on rollback. Should undo what the apply script did. |
| configUri | Uri to be appended to the wpConfigUrl defined on the container. Used when applying xmlaccess to a virtual portal. Example if the wpConfigUrl is http://localhost:10039/wps/config and this property is set to sp, then final config url will be http://localhost:10039/wps/config/sp |
A folder containing 2 XmlAccess files that are used for deployment and rollback.
| Property | Description |
|---|---|
| applyScript | Name of XmlAccess file in folder to execute on deployment |
| unapplyScript | Name of XmlAccess file in folder to execute on rollback. Should undo what the apply file did. |
| configUri | Uri to be appended to the wpConfigUrl defined on the container. Used when applying xmlaccess to a virtual portal. Example if the wpConfigUrl is http://localhost:10039/wps/config and this property is set to sp, then final config url will be http://localhost:10039/wps/config/sp |
<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="3.0" application="IBMPortletApp">
<deployables>
<wp.XmlAccessScriptPair name="XebiaLabsPortalPage" file="XebiaLabsPortalPage/Archive.zip">
<applyScript>createPage.xml</applyScript>
<unapplyScript>destroyPage.xml</unapplyScript>
</wp.XmlAccessScriptPair>
</deployables>
</udm.DeploymentPackage>Sample dars are available to show XLD deployment packaging. The dars use the WelcomePortlet.war and Blurb2.war that come with Websphere Portal Server. They also contain sample xmlaccess scripts to defined pages. The dars can be executed in order of their version to demonstrate deploy, upgrade and undeploy logic as performed by the plugin.