Portal Application Archive (PAA) file

Portal Application Archive (PAA) files

Specification
sdd.xml files
Component level sdd.xml file overview
Installation tasks
PAA file structure
Documentation directory
Components directory
PAA property files
PAA deployment
Order of installation of scripts and artifacts
Virtual portals in the PAA file
Portal Application Archive (PAA) file specification
Component level sdd.xml file overview
Example: Make environment-specific changes

Portal Application Archive (PAA) file specification

The directory structure for a PAA determines how to install a specific artifact. Deployment tasks can use a default configuration found in the Solution Installer. PAA sample files that demonstrate directory structure and usage are under...
PORTAL_HOME/doc/paa-samples

sdd.xml files

The sdd.xml file in a PAA file uses ConfigEngine extension points to...

Customize how an application is installed
Inform the ConfigEngine of the type of installation to be processed
Determine, in terms of the ConfigEngine, where the deployable files are stored after registration with the ConfigEngine

sdd.xml files are found at the following levels...

Offering level Large applications such as WebSphere Portal
Assembly level Group of applications that can be stand alone, or form the basis of a much larger application. An example of an assembly is the 'ap' or 'base' directories under WebSphere Portal.
Component level Finest level of granularity. Can be a complete application or can be one of many small applications that make up a much larger application.

An assembly is made up of one or more components and an offering is made up of one or more assemblies.
The directory structure for the Solution Installer, and any offering setup details applied to the ConfigEngine, are processed automatically.
A PAA containing an update has the same assembly name in its sdd.xml file. The Solution Installer checks that the assembly exists before adding each new component or update to the current assembly.
The assembly can be made up of one or more components, each requiring a separate component level sdd.xml file.

Component level sdd.xml file overview

The component level sdd.xml file contains the information on how to install the artifacts of the component. It lists the extension pointo that need to be processed. The extension points ensure that the constituent artifacts can be installed. ANT tasks perform the actual deployment and configuration work.

Sample sdd.xml file
<iudd:iudd xmlns:iudd="http://www.ibm.com/xmlns/prod/autonomic/solutioninstall/IUDD"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:OSRT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/OS/resourcetypes"
           xmlns:OSAT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/OS/artifacttypes"
           xmlns:J2EERT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/J2EE/resourcetypes"
           xsi:schemaLocation="http://www.ibm.com/xmlns/prod/autonomic/solutioninstall/IUDD../iudd/iudd.xsd"
           schemaVemycoon="2.0.0" 
           buildID="112220" 
           buildDate="2006-01-19T12:00:00">
 <packageIdentity contentType="Component">
      <name>components/componentN</name>
         <vemycoon>8.0.0.0</vemycoon>
      <displayName key="d0001" default="components/componentN" />
      <manufacturer>
         <displayName key="AC_01" default="IBM" />
      </manufacturer>
   </packageIdentity>
   <topology>
      <resource type="OSRT:OperatingSystem" id="OS" />
   </topology>
 <content xsi:type="iudd:RootIUContent">
    <rootIU id="components/componentN">
       <variables>
          <parameters>
             <parameter name="installLocation" 
                        defaultValue="/usr/dummy.offr.1" />
             <parameter name="FunctionalArea" 
                        defaultValue="featurepackSI" />
          </parameters>
       </variables>
    <SCU id="deploy-portlets-applySIFeaturePack" targetRef="OS">
     <identity>
          <name>Do Configuration Task</name>
          <vemycoon>8.0.0.0</vemycoon>
          <displayName key="keyInBundle"
           default="Executes Configuration for this component" />
     <description key="keyInBundle"
                  default="This section runs configuration for this component" />
      </identity>
    <unit>
     <configArtifact type="ConfigEngine">
      <parameters>
       <parameter name="targetName" 
                  value="deploy-portlets-applySIFeaturePack" />
      </parameters>
     </configArtifact>
    </unit>
   </SCU>
   <SCU id="remove-portlets-applySIFeaturePack" targetRef="OS">
    <identity>
     <name>Do Configuration Task</name>
     <vemycoon>1.0.0.0</vemycoon>
     <displayName key="keyInBundle"
      default="Executes Configuration for this component" />
     <description key="keyInBundle"
      default="This section runs configuration for this component" />
    </identity>
    <unit>
     <configArtifact type="ConfigEngine">
      <parameters>
       <parameter name="targetName" 
                  value="remove-portlets-applySIFeaturePack" />
      </parameters>
     </configArtifact>
    </unit>
   </SCU>
  </rootIU>
 </content>
See The component level sdd.xml file for information about editing the sdd.xml file.

Syntax information

The syntax for naming the component is important. There are dependencies within the PAA file that determine part of the component name registered in the sdd.xml file. You are free to name the components as we like, however when registering the names in the sdd.xml files, you should adhere to the following syntax: components/componentName.
An example of an application is the unified task list with a component name of UTL. The component name would appear in the sdd.xml file as follows: components/utl. That is the full path relative to the directory containing the assembly level sdd.xml file.
The Solution Installer follows the feature pack approach provided by the ConfigEngine to install the individual components. The advantage of this approach is that the ConfigEngine manages the installation order of the individual components. Using the feature pack approach ensures a distinction between portal core extension points and those used to install the PAA content. This approach reduces the risk of a user accidentally removing portal core components when executing a remove extension point.
The ConfigEngine runs the installation of the set of components by extension point and controls the order in which these are run. For example, all EAR files are installed together; all portlet deployments are done at the same time. If there is a need to have an artifact of a component installed before installing another, then create a dependency in the sdd.xml file. The dependency works on an extension point basis is that it allows us to specify that artifacts covered bthat extension point can have an order. For example, we can specify that the EAR file in component1 is installed before the EAR file in component2 etc.
The value of the FunctionalArea parameter is set to featurepackSI. This value is important so the Solution Installer can determine that the components are to be installed using the Solution Installer specific feature pack. See the sdd.xml file example at the beginning of this file for how to implement the feature pack approach.
If you examine the sdd.xml file sample at the beginning of this file, it contains a number of <SCU> elements. These are extremely important for the installation process to the ConfigEngine and to the deployment of the artifacts to WebSphere Portal and the appservers.
The <SCU> element in the component level sdd.xml file is what is used to inform the ConfigEngine which extension point it needs to extend to run the deployment. If you look in the example file, you see two <SCU> elements. The first shows how to deploy a portlet using an extension point and the second demonstrates how to remove the portlets again.
<SCU id="deploy-portlets-applySIFeaturePack" targetRef="OS">
 <identity>

   <name>Do Configuration Task</name>

   <vemycoon>1.0.0.0</vemycoon>

   <displayName key="keyInBundle" 
                default="Executes Configuration for this component" />

   <description key="keyInBundle" 
                default="This section runs configuration for this component" />

 </identity>

 <unit>
 <configArtifact type="ConfigEngine">

 <parameters>
  <parameter name="targetName" 
                  value="deploy-portlets-applySIFeaturePack" />
  </parameters>

  </configArtifact>

 </unit>

  <!-register a dependency on a previous component-->
  <requirements>

    <requirement name=" deploy-portlets-applySIFeaturePack">
     <alternative name="dependentComponent"/>
    </requirement>

  </requirements>

</SCU>
The <SCU> element example notifies the Solution Installer about the task to run. The extension point in this case is called deploy-portlets-applySIFeaturePack. This deviates from the core extension points for portal by adding ‘applySIFeaturePack' to the end of the extension point. In the case of an uninstall task, ‘removeSIFeaturePack' is appended instead. This allows the Solution Installer to distinguish between installation and uninstallation tasks. The reason to append these strings to the extension point names is so that there is a definite distinction between core extension points and those included for the Solution Installer to handle a PAA distribution. The Solution Installer expects and runs only extension points conforming to this format.
To use the default Solution Installer installation task for deploying portlets, no further action is required. If you require a custom installation task to deploy the portlets, create an ANT task and place it in the componentN/config/includes directory. Continuing with the previous example, a custom task for the UTL would be stored in the components/utl/config/includes directory.
The content of the task is at the discretion of the developer. The task name must follow a strict naming scheme. The task must be named as action- + extension_point_name + - + component_name. Using the UTL example, the component is called components/utl. The extension point is deploy-portlets-applySIFeaturePack. The resulting target name for the ANT task is: action-deploy-portlets-applySIFeaturePack-components/utl. The uninstallation task for the extension point is: remove-portlets-removeSIFeaturePack. The task name is: action-remove-portlets-removeSIFeaturePack-components/utl.

Installation tasks

The Solution Installer uses two different scenarios to determine how an artifact in the PAA file is installed.
The Solution Installer uses the following two scenarios to determine how an artifact in the PAA file is installed:

Scenario one

The first scenario includes developer supplied code and the Solution Installer automatically generated code. After the Solution Installer expands the PAA file and before the assembly and subsequent components are installed to ConfigEngine, the Solution Installer queries the sdd.xml file for the component. It checks whether a task exists in the config/includes directory for a specific extension point listed in the sdd.xml file. If the task exists, then the Solution Installer knowthat a task already exists for that extension point and the installer moves on to the next extension point. However, if no task is available, then a default task is generated for deployment. The auto generated tasks are added to the config/includes directory of the expanded component, and any dependent artifacts for the tasks, such as XMLAccess scripts, are placed in the config/templates directory. After this process has been completed for each component, the PAA distribution is then installed to the ConfigEngine. In this way both simple and complex configuration tasks are completed.
The default task should suffice for most cases. When additional configuration is required for an artifact, then use the custom code approach. The PAA file must contain a mixture of deployable artifacts, scripts such as XML access scripts to create pages and do some configuration, and ConfigEngine ANT tasks that supply custom deployment code.

Scenario two

The second scenario is when files are placed in the default directories and no extension point is provided in the sdd.xml file. In this scenario the Solution Installer generates both extension points and the implementation tasks. The Solution Installer examines the file types and adds an extension point to implement this task. If by examining the artifact type it is possible to determine the correct extension point, the ConfigEngine supplied extension point is implemented. For example, an EAR file requires the create-ear and remove-ear extension points. The applySIFeaturePack or removeSIFeaturePack extension points are appended to the name of the core extension point to ensure that the Solution Installer picks it up; for example, create-ear-applySIFeaturePack. However, it is not always possible to determine the correct extension point to use. For example, in the case of the scripts in the content/xmlaccess component directory, it might not be obvious which extension point should be implemented. Therefore, a generic Solution Installer extension point is applied. The code is generated and copied into the config/includes directory. This approach is done at the same stage of the deployment as the auto generation of code.

PAA file structure overview

We can find a sample top-level directory in the PORTAL_HOME/doc/paa-samples/sample1.paa file. This directory is the root directory of the PAA content. It contains the documentation and components directories and an sdd.xml file.
The sdd.xml file has the following roles:

It informs the ConfigEngine about the assembly of components.
Provides the ConfigEngine with the list of components and their locations within the directory structure.

It points to each component sdd.xml file so that the install functionality can process the installation of the individual components.

Documentation directory

Place all documents and ID related artifacts for the application in the documentation directory.
The PAA package developer should organize the documentation directory per the relationship between the documents and the flow of content information. The Solution Installer copies the content to the correct location in the expanded archive under the PAA offering directory; for example...
WP_PROFILE\paa\sample_paa\documentation\*.*

The documentation directory is the only recommended place for documentation related to the application. There is currently no provision within the PAA format to provide documentation at the component level.

Components directory

The components directory and its subdirectories are located in the PAA file archive where all deployable artifacts must be stored. If you examine the content of the components directory in the provided sample PAA file, you will see just one component listed, sample1. There is always at least one component contained in a PAA file; however, there is currently no limit on the number of components that we can include.
The number of available components depend on how to organize your deployable artifacts. Potentially all the deployable artifacts can be stored in a single component. However, if there are multiple stand-alone applications to be stored in the PAA file, a component for each application is recommended. Also to be able to reuse components across PAA file distributions, then it makes sense to separate artifacts into multiple components.
There is no limit on the type of artifacts that can be contained within a specific component. There is a limitation on where the artifacts can be placed within the component directory subtree structure. These restrictions are discussed in detail in the following subsections.
As previously mentioned component can include artifacts and configuration details for an entire application. It might also only contain artifacts specific to a certain part of the application. For example, we could include all the theme related artifacts in one component and your XML access scripts to create the pages in another component. The Solution Installer does not have a preference. For component reusability we might want to have some separation.
Use the PORTAL_HOME/doc/paa-samples/sample1.paa example, open the components/Sample1 directory. The following directories should be present as well as the component level sdd.xml file:
config

Contains includes and templates directories. Both directories are important if you plan to add custom tasks to aid the installation or configuration of the component enclosed artifacts.

config/includes

This directory is where the ConfigEngine looks for tasks that implement the extension pointo that are listed in the component level sdd.xml file. The name of the xml file containing the ANT tasks are not hard coded. The ConfigEngine looks in this directory for any .xml files. The ANT tasks do not have to be stored in a single file. They can be spread over multiple files which are picked up by the ConfigEngine.

config/templates

This directory is where additional non-ConfigEngine script files are stored for configuration tasks. For example, if you deploy a WAR file and want to perform portlet configuration tasks, we can place the XML scripts in this directory. We can reference the WAR file in the profile_dir/installableApps directory. You should copy it there automatically with the custom task implementation.
The Solution Installer does not automatically run the scripts stored in this location. Instead, the custom tasks are responsible for calling these scripts.

content

This directory is where we can store Web Content Manager libraries and other content related artifacts for import. The component/content directory contains the following subdirectories:

jcr: Contains JCR related artifacts. Contains a directory structure of nodes; each entry is either a file or a directory, with associated metadata (title, last modified, permissions, etc).

jsp: Place any JSP file to package as part of the application. Web Content Manager JSP files should be placed in this folder under the directory jsp/wcm. The Solution Installer copies all files and folders placed here to the relevant location on the server: ${WasUserHome}/installedApps/${NodeName}/WCM_EXTENSION.ear/wp.wcmextension.war/jsp/wcm/content.
The Solution Installer does not perform any default tasks to handle JSP content, excluding those located in jsp/wcm. A developer needs to provide a custom task to ensure this content is copied to the correct location.

wcm: Contains Web Content Manager libraries. Each subdirectory of the wcm directory represents a separate Web Content Manager library. These are a specialized form of JCR artifact. Web Content Manager libraries are separated into their own directory due to the process required to install them using the default functionality.

webdav: This directory and its sub tree structure contains artifacts that need to be uploaded to the WebDAV file store. There are four possible subdirectories. Each one is named to reflect the type of functionality provided in the files contained. The following options are:

iwidgets: Place compression files containing iWidgeto that need to be uploaded to the WebDAV file store and registered with WebSphere Portal. The Solution Installer automatically uploads any compression files found in this directory to the dav:fs-type1/iwidgets/ directory. Additional work is necessary to have the iWidget definitions registered with WebSphere Portal. The installer needs to have some knowledge of the widget definition files to register with WebSphere Portal. A properties file called iwidgets.properties needs to be included in the iwidgets directory in the PAA. The properties are generated using the compression file name containing the definition file as the name of the property, and supplying a comma-separated list of definition file contained in this file as the value.

layout-templates: Place compression files containing layout-templates in this directory. Once such files are detected by the installer, code is generated to automatically upload such content to the dav:fs-type1/layout-templates/ directory in the WebDAV file store.

Skins: Place any compression file containing skins not specific to a theme in this directory. The content is automatically uploaded to the dav:fs-type1/skins/ directory in the WebDAV file store.

Themes: Place compression file containing static theme content in this directory. They are automatically uploaded to the dav:fs-type1/themes/ directory in the WebDAV file store.
If the theme contains dynamic content, such as JSP files, include them in a WAR file that is deployed to the underlying application server available at runtime.

The Solution Installer only uploads WebDAV content using the ‘dav:fs-type1/*.* webdav entry point. The themes and skins are not automatically made available through the themelist or skinlist entry points. To ensure that this occurs, and the theme/skin is made available through the administration pages, an XMLAccess script needs to be created to register the resources with WebSphere Portal.
The context root, where the content of the individual compression files is installed, is set in the following manner.

If there is a root directory contained within the compression file; for example: all the content is enclosed within a directory, then this is appended to the TargetURI, for example, a compression file in the componentName/content/webdav/themes directory with a root directory of sample would result in a TargetURI ‘dav:fs-type1/themes/sample/'.

If there is no root directory contained in the compression file that is, all the items are located at the top level, then the name of the compression file minus the ‘.zip' suffix is used. For example, a compression file with the name sample1.zip would result in the TargetURI ‘dav:fs-type1/themes/sample1/'.

Although by default the upload task for the compression files to the WebDAV file system is set to replace the current directory with the new content, the Solution Installer alters this functionality to merge the content by default instead. When the UpdateMode parameter is set to replace, which is the default outside of Solution Installer, the upload replaces all content found at the given TargetURI. For example, if we are uploading a .zip file to dav:fs-type1/themes/, it does not just replace the equivalent content stored in the directory, it replaces everything in this directory. Therefore, it was decidethat when using Solution Installer to handle this functionality, it would be better to have the content set to merge with the existing content as the default behavior. If you do require that the UpdateMode is set to 'replace' instead, then you need to add a properties file to the directory for which the functionality is required. For example to replace all the themes, we would place the webdav.properties file in the componentName/content/webdav/themes directory. There is just one property available in this file: webdav.replace=list of compression files.
The value of the webdav.replace property is a comma-separated list of file that tells Solution Installer which files must be uploaded using the replace update mode.

xmlaccess: Stores any component level XML access scripts. This directory differs from the component/config/templates directory which stores scripts to be called by custom Ant tasks. Any scripts that need to be run by default, are placed in the content/xmlaccess directory. This directory has two sub directories to aid in the distinction between install and uninstall scripts. The scripts required for installation reside in the /content/xmlaccess/install directory and the uninstall scripts are placed in the /content/xmlaccess/uninstall directory.
The type of scripts to be placed in the component/content/xmlaccess directory sub tree can include scripts to deploy a theme to Portal, although the EAR file needs to be installed to the application server. Also, scripts to configure theme policies, create has a set of users and/or groups, or a credential slot in the WebSphere Portal credential vault are additional examples of scripts that could be placed in this directory. All the scripts that are found by Solution Installer in these directories are automatically run depending on the functionality being invoked.
database: Contains any database scripts for creating tables and pre-populating the tables with any relevant data. Solution Installer can generate Ant tasks to create the relevant configuration settings on the underlying WAS. For details of the required properties, see Database properties for the Solution Installer.

pzn: PZN related artifacts, such as JAR files containing business rules and personalization .nodes files reside in this directory.

installableApps
The installableApps directory is where any artifacts that need to be installed to WebSphere Portal or directly to the application server are to be stored. Solution Installer copies the relevant files across to the profile_dir/installableApps directory automatically when the default implementation tasks produced are used. The artifacts are stored in the PAA in subdirectories based on their resource to allow for default functionality to be easily employed to perform installation and deployment of artifacts. However, when the artifacts are copied to the profile_dir/installableApps directory, it is just the content of the subdirectory that is copied and not the directories themselves. The following is a list of currently supported resource sub directories:
ear: Contains any EAR file that need to be deployed to the application server. WAR file that do not contain any portlets and need to be installed directly to the application server should be wrapped in an EAR file. The reason for this is that the default scripts used to deploy artifacts require specific information to run the install. We need a mechanism to obtain installation information such as the display name and context root details which can be found in the application.xml file of an EAR file. The context root information would not be available with just a WAR file. An example of a WAR file that needs to be wrapped in this way is a theme.war file. If we are providing a custom Ant script to do the deployment, then this is unnecessary as we can provide the required information in the script, or a properties file read by the script.
Although EAR files are deployed automatically to the server by default when found in this directory, you should note that if a WAR file containing a portlet is wrapped inside of an EAR file, an additional script to register the portlets with WebSphere Portal must be supplied by the developers. There is currently no introspection performed on the EAR file and its contents to see if they contain portlets. Therefore, it is the responsibility of the developer to ensure that the portlets are registered in the correct manner.
portlets: The portlets directory is where any WAR files containing JSR portlets are to be placed. IBM legacy portlets are not handled automatically by the installer. They require custom code to perform the install and should not be placed in this directory. The reason for separating these WAR files from those containing servlets or other application types is due to the installation method required. Those containing JSR portlets are typically installed and deployed using an XML access script, whereas, those that need to be installed directly to the application server are deployed using a ConfigEngine Ant task or alternatively using a wsadmin script. Solution Installer can then read the portlets directory and install the WAR files automatically and does not need to worrthat it will encounter a non-portlet WAR. However, if there is additional configuration setup to be performed for a portlet, then the default installation task should be overwritten by supplying an Ant task with a custom XML access script to do the install. Add a <scu> element to the sdd.xml file for the deploy-portlets-applySIFeaturePack extension point and add an Ant task that implements this extension point in the config/includes directory. This ANT task needs to call the XMLAccess task to run any supplied XMLAccess script against the portal server.
The automatic install uses the unique ID from the <portlet-app> element found in the warfile/WEB-INF/portlet.xml file, and the location of the WAR file itself to enable the deployment. If the unique ID is not available, the name of the WAR file are used instead. The WAR file has already been copied over to the profile_dir/installableApps directory. The following is a sample XMLAccess script that shows how the information is used to drive the install:
<?xml vemycoon="1.0" encoding="UTF-8"?>
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd" 
         type="update"
         create-oids="true">

  <portal action="locate">

   <web-app action="update" active="true"
    uid="portletXmlUniqueId.webmod">
    <url>file:///$profile_dir$/installableApps/warfile.war</url>

   </web-app>

  </portal>
</request>
WAR files placed at this location will also have unique names automatically generated for the individual portlets during installation. The generation of unique name values is based upon the scheme componentName.portletName. The following is a sample XMLAccess script showing how the unique name values are specified:
<?xml vemycoon="1.0" encoding="UTF-8"?>
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd" 
         type="update" 
         create-oids="true">

   <portal action="locate">

      <web-app action="locate" 
              domain="rel" objectid="WebAppID.webmod"
              uid="WebAppId.webmod">

      <portlet-app action="update" 
                  domain="rel" 
                  name="PortletAppId"
                  uid="PortletAppId">

   <portlet action="update" 
            domain="rel" 
            name="PortletName"
            uniquename="componentName.PortletName"/>
   </portlet-app>
  </web-app>
 </portal>
</request>
IBM recommends the WAR file name should have the component name prepended, following the scheme "componentName.WARname.war". Although not essential, it allows the user to more easily track which WAR files have been installed using the Solution Installer via their respective component name.
war: Contains any WAR file that the developer does not want to install automatically and has extended the extension point with a custom Ant task to install the artifacts. An example is if the WAR file contains legacy IBM portlets. Alternatively, the WAR file does not contain any portlets and the developer does not want to wrap it in an EAR. Also there may be additional customization steps required for the configuration of the deployed artifacts that is not performed by the default install, so a custom script is required. The installer generally ignores this directory apart from copying the files to the profile/installableApps directory and then invoking any custom code provided to handle these artifacts.

zip: Contains any compression file content that you need to ship for a component. For example, we might have some artifacts that need to be copied and installed to a server that currently is not supported by Solution Installer. Solution Installer does not automatically process the content of this directory. The individual files remain in their compressed state after the PAA file is extracted. Instead, any processing of these files is completed by either custom Ant tasks provided by the developer or through manual steps.
shared
When deploying an application to WebSphere Portal, it is often the case that additional shared libraries are required for the application to function correctly. These libraries can reside at different levels of scope for the application. If stored in the WAR file itself, then only classes withis that WAR file are able to access the library files. The second situation is when has a set of libraries are solution specific. That is, the classes in the shared library are available only to the overall solution. The WAR file option is not appropriate as it could mean a number of separate applications working together as a larger solution, all requiring access to the library. The third level of scope is global, meaning that many applications running on the server can access these classes. The first situation where the library JAR files are stored in the WAR file is out of scope for this document. However, the ability to facilitate the other two situations is provided by Solution Installer.
For globally available JAR files, place the JAR files into either the component/shared/app or component/shared/ext directories. These files are not copied to the equivalent directories under the PORTAL_HOME directory. Instead, a task is run to register all the JAR files found in the shared/app and shared/ext directories of the components. When objects are found in these directories, they are registered directly with a Solution Installer specific set of shared libraries that reside inside the profile. This action makes the libraries profile specific thus different vemycoons of the same files could be installed to different profiles. Many of the industry templates use different vemycoons of the same components and this action allows multiple templates to reside on the same server under different profiles.
JAR files registered in the component/shared/app directory will be registered in the Solution Installer specific shared.app.jar file. Similarly for the jars in componentName/shared/ext directory, these are registered with a profile specific shared.ext.jar file. These files can be found under the profile_name/PortalServer/solutionInstaller directory sub tree. The specific library ‘SiSharedLib' is registered at the cell/node level of the profile and a reference is then added to the classpath of the application server to ensure that the files are available at runtime. Only the shared.app.jar file is loaded automatically by the SiSharedLib library. Once the registration of these files has completed, a server restart is required to reload the libraries and make the classes available on the class path. After this is done, the library specific classes are now available globally to that server for an application to access.
To allow a library scope limited to a specific solution, place the relevant JAR files in the component/shared/common directory. Files in this directory will not be copied to a location inside of the profile directory. Instead, a shared library for this component pointing to this directory are added to the WAS. This shared library then needs to be associated with either the application or made available on the server wide classpath so it is available to all applications. To achieve this, a properties file called shared-library.properties will reside in the component/shared/common directory. This file will contain information on the scope to which the shared library needs to be registered. It will also provide information on any required class loader properties, such as, class loading precedence etc. The properties available in the shared-library.properties are as follows:
# set whether the library should be at the server scope or application scope 
# Can have the following values:
# cell, cluster, node, server library-scope=server
# specify whether the library should be added to the server class path 
# or associated with a specific application.
Library-ref=application
# Set the name of the application(s) to which the library is to be associated.
# name of application(s) found in the integrated administration 
# console/applications/enterprise applications.
applicationName=
# the application name 
# Set class loading preference, options are either 
# 'PARENT_FIRST' or 'PARENT_LAST'.
classLoadingMode=PARENT_FIRST
If multiple applications are to be associated with the library, a comma separated list of application names should be specified as follows: applicationName=AppName1,AppName2,AppName3, where Appname1/2/3 represent the applications to which the library is to be associated.
template

The template directory is where a developer can place files to create a web site template based on one or more of the components supplied in the PAA distribution. If you examine the sample PAA file included with Solution Installer, there are three sub directories included. However, many more directories might be contained within, one for each additional template to provide. The directory names used in the sample PAA file are reserved by Solution Installer to inform it of the nature of the content. For example the newsitewizard directory contains template artifacts that can be imported using the new site wizard portlet.
The default directory and any subsequent template directories have their content split into two further subdirectories to aid in the distinction between install and uninstall scripts. The install scripts reside in the /component/template/template_Name/install directory and the uninstall scripts are placed in the /component/template/template_Name/uninstall directory. The scripts contained in the default directory will always be run. If we are offering multiple templates and do not want one to be installed by default, then leave this directory structure empty. In general the content of the default, or template specific directories, will include XMLAccess scripts to create pages, put portlets on the pages and create users. That is, any task that is site related and not covered by the other directories or components. For example, an XMLAccess script to install a WAR file should not be placed here, instead this file if required should be placed in the component/config/templates directory if a custom Ant task is required, or in the component/content/xmlaccess directory otherwise. Site template artifacts that will be imported using the new site wizard will reside in the component/template/newsitewizard directory. There is no further directory substructure beneath this directory, instead all new site wizard related JAR files shall reside at the top level of this directory. Solution Installer first ensures that the new site wizard has been deployed to WebSphere Portal. Once this is verified, the running new site wizard WAR file is retrieved from WebSphere Portal and copied to a temporary directory. The new template JAR content is extracted and copied over to the relevant locations inside of the new site wizard. After which the new site wizard is repackaged and deployed to the server. The new template artifacts are then available to the user through the new site wizard portlet.
The new site wizard artifacts do not need to be limited to just containing functionality for an overall site template, they can be specific to a component. A component specific new site wizard template should be stored local to that component to aid reuse.
IBM recommends that any site wide template related artifacts should be stored in a single component separate from the components on which they depend. This will allow the overall site presentation to be separate from the underlying technologies they surface and it makes it easier for the installer to handle updates in the future. It also makes it much easier to manage the provision of multiple site templates in a single PAA distribution. Sample or demo pages for a single component should still be stored local to that component.

vemycoon

The component/vemycoon directory will contain a component_name.component file. This file is what tells the ConfigEngine the vemycoon of the application being installed. Knowledge of the vemycoon already installed is necessary to facilitate updates to an application.
PAA property files

There are two distinct types of properties containable within a PAA distribution:

Requiring user input, for example a database URL
Developer provided settings required for a component to function

Separation between both types of properties is advised.
The Solution Installer generally does not need to know the values of these properties, as in general it is custom Ant tasks provided by the developer that handle such properties. There are cases where properties required by the installer may also need to be set. In this case, these need to be included along side user editable properties.
Users need to edit such content before running the install; so it makes sense to consolidate such properties in the one place; instead of requiring the user to edit multiple files in different locations throughout the PAA. However, there is a trade off with keeping all the properties required by a component together to allow for component reuse. User editable properties are defined in the properties file specific to a component...
component_name.properties

...which can be found in the top level directory of a component. The naming scheme of this file is important as it will be picked up by Solution Installer. Once the PAA file has been expanded, users are free to edit these as needed and can then re-run any ConfigEngine functionality associated with the component to take account of these new values. The values in this file will be the defaults for the properties and may be overwritten by parent properties files.
There are two ways in which the properties in the component level properties files can be overwritten by parent properties.

The properties files containing user editable properties for the components of the PAA assembly can be consolidated into one properties file and placed in the top level directory of the PAA file...
assembly_name.properties

The user can edit this file to set any values required for the install to ConfigEngine and WebSphere Portal to run smoothly. When the install process for the ConfigEngine is initiated, these properties are read first, leaving values in the default properties files redundant as Ant properties cannot be overwritten once set, unless they have gone out of scope.

The user editable properties file could live outside of the distribution altogether. The approach taken by the installer is to check the command line to establish if a properties file has been passed when the command to install was invoked. If they are, the installer loads the properties and the values are set in this file. This file is then used during the deployment to the WebSphere Portal server. Similarly, if a properties file is not received on the command line, then it looks in the highest level directory of the PAA distribution for such files. Once found these values are loaded as the values for the properties.
If there are additional properties in the assembly level file to those passed in from the command line, then these are read as well. If no properties file is found, values from the component level property files are used. Otherwise, it is assumes that no user editable properties are required and the install will proceed.
The reason for this approach is so that Solution Installer can be invoked in multiple ways. The first iterations of Solution Installer are command line based, and invoked through direct calls to the ConfigEngine.
If the properties file resides with in the PAA distribution itself, users need to break open this file and edit the relevant properties before installation. Providing the user properties files outside of the PAA file alleviates this step.
Property files containing developer provided settings should reside at the component level. To aid reuse of components across multiple PAA files, required settings should be kept local to a component.

With Ant, once a property has been created in a run of the scripts, it cannot be overwritten. Therefore if we are installing multiple components that have a setting with the same name but different values, the first one to be created is used throughout the install, which can cause unexpected results. IBM recommends that a pattern for naming the properties should be employed to ensure that property names across components do not clash. For example, a property name could have the name of the component to which it relates, prepended to the name to ensure uniqueness.

PAA deployment

A component can use a mixture of custom and default tasks to perform the deployment and configuration of artifacts. For example, a custom task may be used to create a datasource, or in some cases deploy a WAR file to the Portal server.
However, one restriction in the approach of Solution Installer to the use of custom tasks is that if an extension point is extended to use a custom task; all artifacts covered by this extension point in this component also must be covered by this task. For the example of the WAR file, if the extension point...
deploy-portlets-applySIFeaturePack

...has been extended with a custom task for that component, then all the resource files in the portlets directory must be deployed by this task, even though there may be multiple WAR files. In this way, the installer does not need to worry about trying to manage which files are covered by the custom task. Thus, either a custom task, or the default task must be used for an artifact type inside a component. There is no facility to have a hybrid of the two approaches to cover multiple files.

Order of installation of scripts and artifacts

There are many cases where the order in which scripts are run and artifacts to be deployed is important for the success of the installation. For the most part, the order in which components are installed is governed by the dependencies set in the sdd.xml file for the extension points.
The Solution Installer dictates the order in which the different extension points are called. However, if there are multiple scripts or resources of a given type to be handled by a specific extension point, there is no way to determine the correct order. If a custom task is provided, then there is no problem as the task governs the order. An issue arises when the default tasks are used to initiate the install.
To solve this issue, a properties file called order.properties can be added to any of the directories within the component hierarchy containing artifacts that must be run or installed. For example, such a file could be added to the componentN/content/xmlaccess/install directory. This file contains a comma separated list of the file names in the correct order that they are to be deployed. If no order.properties file exists, the Solution Installer works on the assumption that the order of installation is not important.

Virtual portals in the PAA file

There are many situations where a user might want to install the applications contained in a Portal Application Archive (PAA) file directly to a virtual portal. The PAA specification does not handle it directly.
There are no additional configuration steps taken when using the PAA format. However, the Solution Installer takes advantage of the virtual portal related properties available in wkplc.properties when creating the URL for the XMLAccess task to connect to the portal configuration. Solution Installer checks the value of the VirtualPortalHostName and VirtualPortalContext properties. If one or more of these properties are set, then their values are included in the XMLAccess URL. However, if neither of these properties is set, it is assumes that the PAA file content is to be installed to the main WebSphere Portal so the default XMLAccess connection URL will be used instead. These properties can be set in wkplc.properties, or by including them on the command line with a prefix of ‘-D' when running the deployment. For example, ‘-DVirtualPortalContext=testVP'. In addition, when removing resources from a virtual portal, these properties must also be set.
As the properties/parameters must be set prior to running the installer to deploy the PAA application, there is no facility to install individual components of the PAA file to different virtual portals. That is unless the install is being done manually on a component by component basis. Instead the full PAA content is deployed to the one virtual portal.

Portal Application Archive (PAA) file specification

When deploying large applications with many constituent components to IBM WebSphere Portal, there can be a large number of steps required to install each component and configure required resources. The Solution Installer automates many of these deployment tasks. The Solution Installer requires a Portal Application Archive (PAA) file to describe how to install the application and to provide the installable artifacts.
The PAA file format is used to handle deployments ranging from applications with a small number of configuration steps to large scale enterprise portal solutions. The directory structure of the PAA file is important to the Solution Installer when determining how to install a specific artifact, for example, how to handle shared library files. In addition, the software definition descriptor (sdd.xml) files also play a significant role in determining the installation steps as any extension points required for installation must be specified in an sdd.xml file local to the component.
The PAA file format offers a mechanism to allow for a reduction in the amount of work required for a developer to create a deployable solution. Many of the deployment tasks can use a default configuration found in the Solution Installer. For complex applications some additional work is required to provide custom install features. In general using the PAA file format in conjunction with the Solution Installer should reduce the production time for creating a deployable solution for the application.
A number of sample file that demonstrate the overall structure and usage of the PAA file format are included in the PORTAL_HOME/doc/paa-samples directory. These examples act as reference material for the discussion in the remainder of the file specification documentation.

Component level sdd.xml file overview

The component level sdd.xml file contains the information on how to install the artifacts of the component. It lists the extension pointo that need to be processed. The extension points ensure that the constituent artifacts can be installed. ANT tasks perform the actual deployment and configuration work.

Sample sdd.xml file
<iudd:iudd xmlns:iudd="http://www.ibm.com/xmlns/prod/autonomic/solutioninstall/IUDD"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:OSRT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/OS/resourcetypes"
           xmlns:OSAT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/OS/artifacttypes"
           xmlns:J2EERT="http://www.ibm.com/xmlns/prod/autonomic/resourcemodel/J2EE/resourcetypes"
           xsi:schemaLocation="http://www.ibm.com/xmlns/prod/autonomic/solutioninstall/IUDD../iudd/iudd.xsd"
          schemaVemycoon="2.0.0" buildID="112220" buildDate="2006-01-19T12:00:00">
 
 <packageIdentity contentType="Component">
  <name>components/componentN</name>
  <vemycoon>8.0.0.0</vemycoon>
  <displayName key="d0001" default="components/componentN" />
  <manufacturer>
   <displayName key="AC_01" default="IBM" />
  </manufacturer>
 </packageIdentity>
 <topology>
  <resource type="OSRT:OperatingSystem" id="OS" />
 </topology>
 <content xsi:type="iudd:RootIUContent">
  <rootIU id="components/componentN">
   <variables>
        <parameters>
         <parameter name="installLocation" 
                    defaultValue="/usr/dummy.offr.1" />
       <parameter name="FunctionalArea" defaultValue="featurepackSI" />
    </parameters>
   </variables>
   <SCU id="deploy-portlets-applySIFeaturePack" 
        targetRef="OS">
    <identity>
     <name>Do Configuration Task</name>
     <vemycoon>8.0.0.0</vemycoon>
     <displayName key="keyInBundle"
      default="Executes Configuration for this component" />
     <description key="keyInBundle"
      default="This section runs configuration for this component" />
    </identity>
    <unit>
     <configArtifact type="ConfigEngine">
      <parameters>
       <parameter name="targetName" value="deploy-portlets-applySIFeaturePack" />
      </parameters>
     </configArtifact>
    </unit>
   </SCU>
   <SCU id="remove-portlets-applySIFeaturePack" targetRef="OS">
    <identity>
     <name>Do Configuration Task</name>
     <vemycoon>1.0.0.0</vemycoon>
     <displayName key="keyInBundle"
      default="Executes Configuration for this component" />
     <description key="keyInBundle"
      default="This section runs configuration for this component" />
    </identity>
    <unit>
     <configArtifact type="ConfigEngine">
      <parameters>
       <parameter name="targetName" value="remove-portlets-applySIFeaturePack" />
      </parameters>
     </configArtifact>
    </unit>
   </SCU>
  </rootIU>
 </content>
</iudd:iudd>
See The component level sdd.xml file for information about editing the sdd.xml file.

Syntax information

The syntax for naming the component is important. There are dependencies within the PAA file that determine part of the component name registered in the sdd.xml file. You are free to name the components as we like, however when registering the names in the sdd.xml files, you should adhere to the following syntax: components/componentName.
An example of an application is the unified task list with a component name of UTL. The component name would appear in the sdd.xml file as follows: components/utl. That is the full path relative to the directory containing the assembly level sdd.xml file.
The Solution Installer follows the feature pack approach provided by the ConfigEngine to install the individual components. The advantage of this approach is that the ConfigEngine manages the installation order of the individual components. Using the feature pack approach ensures a distinction between portal core extension points and those used to install the PAA content. This approach reduces the risk of a user accidentally removing portal core components when executing a remove extension point.
The ConfigEngine runs the installation of the set of components by extension point and controls the order in which these are run. For example, all EAR files are installed together; all portlet deployments are done at the same time. If there is a need to have an artifact of a component installed before installing another, then create a dependency in the sdd.xml file. The dependency works on an extension point basis is that it allows us to specify that artifacts covered bthat extension point can have an order. For example, we can specify that the EAR file in component1 is installed before the EAR file in component2 etc.
The value of the FunctionalArea parameter is set to featurepackSI. This value is important so the Solution Installer can determine that the components are to be installed using the Solution Installer specific feature pack. See the sdd.xml file example at the beginning of this file for how to implement the feature pack approach.
If you examine the sdd.xml file sample at the beginning of this file, it contains a number of <SCU> elements. These are extremely important for the installation process to the ConfigEngine and to the deployment of the artifacts to WebSphere Portal and the appservers.
The <SCU> element in the component level sdd.xml file is what is used to inform the ConfigEngine which extension point it needs to extend to run the deployment. If you look in the example file, you see two <SCU> elements. The first shows how to deploy a portlet using an extension point and the second demonstrates how to remove the portlets again.
<SCU id="deploy-portlets-applySIFeaturePack" targetRef="OS">

 <identity>
 <name>Do Configuration Task</name>
 <vemycoon>1.0.0.0</vemycoon>
  <displayName key="keyInBundle" default="Executes Configuration for this component" />
  <description key="keyInBundle" default="This section runs configuration for this   component" />
 </identity>

 <unit>
    <configArtifact type="ConfigEngine">
    <parameters>
     <parameter name="targetName" value="deploy-portlets-applySIFeaturePack" />
     </parameters>
     </configArtifact>
 </unit>

  <!-register a dependency on a previous component-->
  <requirements>
   <requirement name=" deploy-portlets-applySIFeaturePack">
   <alternative name="dependentComponent"/>
  </requirement>
  </requirements>
</SCU>
The <SCU> element example notifies the Solution Installer about the task to run. The extension point in this case is called deploy-portlets-applySIFeaturePack. This deviates from the core extension points for portal by adding ‘applySIFeaturePack' to the end of the extension point. In the case of an uninstall task, ‘removeSIFeaturePack' is appended instead. This allows the Solution Installer to distinguish between installation and uninstallation tasks. The reason to append these strings to the extension point names is so that there is a definite distinction between core extension points and those included for the Solution Installer to handle a PAA distribution. The Solution Installer expects and runs only extension points conforming to this format.
To use the default Solution Installer installation task for deploying portlets, no further action is required. If you require a custom installation task to deploy the portlets, create an ANT task and place it in the componentN/config/includes directory. Continuing with the previous example, a custom task for the UTL would be stored in the components/utl/config/includes directory.
The content of the task is at the discretion of the developer. The task name must follow a strict naming scheme. The task must be named as...
action- + extension_point_name + - + component_name

Using the UTL example, the component is called...
components/utl

The extension point is...
deploy-portlets-applySIFeaturePack

The resulting target name for the ANT task is...
action-deploy-portlets-applySIFeaturePack-components/utl

The uninstallation task for the extension point is:
remove-portlets-removeSIFeaturePack

The task name is:
action-remove-portlets-removeSIFeaturePack-components/utl

Example: Make environment-specific changes

To reconfigure a PAA file for a specific target environment.
This procedure uses cygwin. Download, install, then set path...
PATH="$PATH:/cygdrive/c/Program Files/Java/jdk1.8.0_65/bin:c:/cygwin64/bin"
export PATH

Modify myapp

Extract contents of PAA file...
jar xvf myapp.paa

This will create a "myapp" directory.

cd myapp\content\xmlaccess\install
For each XML file, change owner to your owner. For example, if you are using File-based user registry, change...
cn=wpsadmin,cn=users,dc=myapp,dc=myco
CN=wpsadmin,CN=Users,dc=myapp,dc=myco

...to...
uid=wpsadmin,o=defaultWIMFileBasedRealm

If you have cygwin installed, we can run...
rp_xml.sh cn=wpsadmin,cn=users,dc=myapp,dc=myco : uid=wpsadmin,o=defaultWIMFileBasedRealm

For each XML file, for users that are in the LDAP, change change base DN to your LDAP. For example, change...
dc=myapp,dc=myco

...to...
dc=me,dc=myco
For example..
rp_xml.sh dc=myapp,dc=myco : dc=me,dc=myco

If the portal is not installed on C:/ drive, update myapp/components/my/my.properties to reflect correct drive. Otherwise, this step can be skipped.
Re-package myapp...
jar -cvMf myapp.paa myapp
Modify myapp.predeploy.paa
Extract contents of MY PAA file...
jar xvf myapp.predeploy.paa

This will create directory "myapp.predeploy"
cd myapp.predeploy\components\myapp.predeploy\content\database\install
Remove *.sql and *.properties files
mv *.sql *.properties c:/scratch/bak
Edit myapp.predeploy/components/myapp.predeploy/sdd.xml and comment out...

Edit...
myapp.predeploy/components/myapp.predeploy/config/includes/myapp.predeploy_cfg

...and comment out...


...also comment ANT calls for the following...
action-setup-database-applySIFeaturePack-components/myapp.predeploy
action-set-db-driver-path-variable
action-create-jdbc-provider-applySIFeaturePack-components
action-set-db-driver-path-variable
action-create-j2c-auth-applySIFeaturePack-components

Here is a modified copy: myapp.predeploy.paa
Edit...
myapp.predeploy\components\myapp.predeploy\content\database\default.properties

...and set...
dbName=MYAppDBNXT
dbPort=49962
dbHostname=mydb
dbType=SQL Server
dbProviderName=myAppDB_JDBC_sqlserver
dbDriverType=Connection pool data source
dbUsername=sa
dbPassword=foo
dbDriverPath=C:/IBM/drivers
dbClasspath=C:/IBM/drivers/sqljdbc41.jar
dbUrl=jdbc:sqlserver://mydb:49962;SelectMethod=cursor;DatabaseName=MYAppDBNXT
dbJndiName=jdbc/myapp
dataSourceName=myapp
dbAuthDataAlias=MYAppUser
Re-package myapp.predeploy.paa
jar -cvMf myapp.predeploy.paa myapp.predeploy
Parent: Develop basic solution applications
Related: PAA file specification
PAA file creation
Checking server dependency
The assembly level sdd.xml file

Offering level	Large applications such as WebSphere Portal
Assembly level	Group of applications that can be stand alone, or form the basis of a much larger application. An example of an assembly is the 'ap' or 'base' directories under WebSphere Portal.
Component level	Finest level of granularity. Can be a complete application or can be one of many small applications that make up a much larger application.