Portal Application Archive (PAA) file specification

When deploying large applications with many constituent components to IBM® WebSphere® Portal Express®, 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 your application.

A number of sample files that demonstrate the overall structure and usage of the PAA file format are included in the PortalServer_root/doc/paa-samples directory. These examples act as reference material for the discussion in the remainder of the file specification documentation.

sdd.xml files
The sdd.xml file performs a number of different roles in the PAA file structure. They allow the developer to control, using ConfigEngine extension points, how an application is installed. They also inform the ConfigEngine of the type of installation to be processed. They also determine, in terms of the ConfigEngine, where the deployable files are stored after registration with the ConfigEngine.
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 points 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.
Installation tasks
The Solution Installer uses two different scenarios to determine how an artifact in the PAA file is installed.
PAA file structure overview
You can find a sample top-level directory in the PortalServer_root/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.
Documentation directory
Place all documents and ID related artifacts for the application in the documentation directory.
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 you can include.
Property files
There are two distinct types of properties containable within a PAA distribution. They can be classified as being either user editable, that is requiring user input, for example a database URL, or as developer provided settings required for a component to function. However, separation between both types of properties is advised. Also the position within the distribution in which the different types of property are located will differ.
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.
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.
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.

Parent topic: Developing basic solution applications

Related concepts:

Portal Application Archive (PAA) file creation

Related tasks:

Checking server dependency