Introduction
In Portal 6.0, themes and skins were typically deployed in the wps.ear application. This included any customized themes and skins for your Portal site. The wps.ear applications, for all intents and purposes, is the primary application for WebSphere Portal that runs on top of Websphere Application Server. Updating a customized theme or skin in Portal 6.0 often was an effort that had to be scheduled during maintenance windows due to the fact an update to the wps.ear file was required. Thankfully, newer versions of Portal no longer require you to include your customized themes and skins in the wps.ear application. Instead, you may deploy such themes and skins in your own application on the Portal server independent of the wps.ear application.
However, there are occasions in newer versions of Portal where updates to the wps.ear application may still be required. For this blog entry, we will focus on the following APAR:
http://www-01.ibm.com/support/docview.wss?uid=swg1PM23905
The APAR itself introduces new code into the WebSphere Portal product. The new code changes the default behavior of the WebSphere Portal if activated. The new code is NOT activated by the action of installation of the APAR itself. Instead, manual changes must be made to a file inside of the wps.ear application, and the wps.ear application must be redeployed with those changes for the new code to become active.
Steps to update wps.ear for APAR PM23905
0) If in a cluster, execute these steps from the Deployment Manager.
1) Navigate to the /AppServer/bin directory
2) Run the wsadmin command to export the wps.ear file to a temporary directory (I used /tmp)
./wsadmin.sh -user wpsadmin -password wpsadmin -c '$AdminApp export wps /tmp/wps.ear'
*Note, this does NOT impact your existing running Portal server. This is a copy we are updating, not the running version.
5) Open the /tmp/wps_expanded/wps.war/WEB-INF/web.xml file in a text editor
6) At the VERY top of the file, just under display name

Add the following:
<filter>
<filter-name>Home Substitution Filter</filter-name>
<filter-class>com.ibm.wps.engine.ServletSubstitutionFilter</filter-class>
</filter>
Resulting in:

7) After the very LAST </filter> and before the very first <filter-mapping>, i.e.

Add the following between these two lines:
<filter-mapping>
<filter-name>Home Substitution Filter</filter-name>
<url-pattern>/portal/*</url-pattern>
</filter-mapping>
resulting in:
8) Save changes.
9) Portal v8 only: Open the /tmp/wps_expanded/wps.war/WEB-INF/web_merged.xml file in a text editor. Repeat steps 6-8 in this file.
10) Backup the wps.ear file in the /tmp directory. Thereafter, delete the wps.ear file in the /tmp directory.
11) Run the EarExpander utility to collapse the files in /tmp/wps_expanded (including the web.xml just updated) into a new wps.ear file:
./EARExander.sh -ear /tmp/wps.ear -operationDir /tmp/wps_expanded/ -operation collapse

12) Run the wsadmin command to redeploy the updated wps.ear file
./wsadmin.sh -user wpsadmin -password wpsadmin -c '$AdminApp install /tmp/wps.ear {-update -appname wps -deployejb -deployejb.classpath /usr/IBM/WebSphere/PortalServer/base/wp.base/shared/app/wp.base.jar}'
*Note: This command will NOT impact the current running Portal Server loaded into in server memory. However, any files contained within the wps.ear file that are referenced by the Portal Server may be impacted. Thus, it is recommended to run this command during a maintenance window to minimize potential impact.
13) If in a cluster, sync nodes. Wait 5-30 minutes for the new wps.ear to be deployed across the cluster.
14a) Verify the web.xml under:
/usr/IBM/WebSphere/wp_profile/config/cells/<cellname>/applications/wps.ear/deployments/wps/wps.war/WEB-INF
includes the changes made in steps #6 and #7. This will verify the updated wps.ear file was deployed successfully.
14b) Portal v8 only: Verify the web_merged.xml also contains the changes.
15) Restart the Portal server(s). Changes should now be in effect.
Addendum to Original Posting
New bits of information will periodically be added to this entry.
1) Portal Infocenters
The official source of information should be the Portal Infocenters, with blog entries (such as this one) providing supplemental information to the Infocenters.
v61 Infocenter:
- Exporting the wps.ear file:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/index.jsp?topic=/com.ibm.wp.ent.doc_v615/admin/wsrpt_secltpa_expear1.html
- Redeploying the wps.ear file:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/index.jsp?topic=/com.ibm.wp.ent.doc_v615/admin/wsrpt_secltpa_redeploy.html
v70 Infocenter:
- Exporting the wps.ear file:
http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Exporting_the_portal_EAR_file_wp7
- Redeploying the wps.ear file:
http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Redeploying_the_portal_EAR_file_wp7
v80 Infocenter:
- Exporting the wps.ear file:
http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Exporting_the_portal_EAR_file_wp8
- Redeploying the wps.ear file:
http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Redeploying_the_portal_EAR_file_wp8
2) Portal v8 web_merged.xml file:
The original article was targeted towards WebSphere Portal 6.1 primarily. Additional actions are required for WebSphere Portal 8.0. In particular, both the web.xml and web_merged.xml file for wps.ear must be updated for changes to go into effect. (Thanks Thomas for the tip!)