PAA file Creation Best Practices - IBM DeveloperWorks · PDF filePAA file Creation Best...

Page 1 of 50

PAA file Creation Best Practices Author: Dr. Esmond Walshe

Abstract

The WebSphere Portal Solution Installer (SI) is the recommended technology for installing add-ons to

your WebSphere Portal server application. To use this functionality, developers need to provide their

deployment resources in the Portal Application Archive (PAA) format that is consumed by the SI. The

decisions you make when you build the PAA file will determine how easy it will be to troubleshoot

any deployment issues and to maintain your application into the future. This document outlines best

practices that you should adhered to when you create your PAA file. Also highlighted are some of the

more common mistakes encountered when you build PAA files and the recommendations on how

these issues can be resolved.

1 Contents Introduction ............................................................................................................................................................... 4

Terminology ............................................................................................................................................................... 7

Building a PAA file ...................................................................................................................................................... 8

The Assembly Name ................................................................................................................................................... 9

Adding PAA file components.................................................................................................................................... 10

Component naming schemes ......................................................................................................................... 10

Separating your resources in to multiple components .................................................................................. 11

Using additional properties in a PAA file ................................................................................................................. 12

SDD file generation .................................................................................................................................................. 12

Assembly level sdd.xml file ............................................................................................................................. 12

Component level sdd.xml file ......................................................................................................................... 13

Component dependencies ............................................................................................................................. 14

Server dependencies ...................................................................................................................................... 17

PAA file dependencies .................................................................................................................................... 17

Adding custom code ................................................................................................................................................ 18

Adding unless="isSecondNode” attribute ...................................................................................................... 19

Installing non-portlet war files ....................................................................................................................... 20

Using ant properties in xmlaccess scripts ....................................................................................................... 21

Referencing locations inside of the PAA file ................................................................................................... 22

EAR file deployment ....................................................................................................................................... 22

Invoking Jython scripts from custom code ..................................................................................................... 23

Catching Errors ............................................................................................................................................... 25

Extension Points Best Practice ................................................................................................................................. 26

Page 3 of 50

Which extension points to use for a given scenario ....................................................................................... 27

Removing items during the deployment phase ............................................................................................. 27

The deploy-apps-applySIFeaturePack and remove-apps-removeSIFeaturePack extension points ............... 28

List of available extension points ................................................................................................................... 29

Including WCM libraries in a PAA file ....................................................................................................................... 36

Theme deployment .................................................................................................................................................. 38

Upload of content to the WebDav Store ........................................................................................................ 38

Deleting WebDav content .............................................................................................................................. 39

Registering a theme with WebSphere Portal ................................................................................................. 41

PAA file life cycle ...................................................................................................................................................... 44

Two step deployment process ....................................................................................................................... 44

Enabling PAA file for updates ......................................................................................................................... 45

Overwriting the existing PAA file .................................................................................................................... 45

Deploying PAA files to a clustered environment ..................................................................................................... 47

Advantages of running SI with Portal stopped. .............................................................................................. 47

Reducing deployment times on a cluster ....................................................................................................... 48

Acknowledgements .................................................................................................................................................. 50

2 Introduction

You created an application that you want to run on WebSphere Portal and now need a mechanism to

deploy it to the server. For example, you have an application that consists of a war file that contains

a portlet. You also created an xmlaccess script to configure the portlet and place it on a web page.

The war file has a dependency on a number of external jar files that need to be added to the server-

wide class-path. In addition, the portlet depends on an imported WCM library and extra

personalization rules to define what content the user is presented based on whether they are logged

in or viewing the portlet anonymously.

Before the development of the SI, the following steps were required to manage the installation of

such content:

1. Use the xmlaccess tool to run the script to install and configure the war file

2. Copy the jar files to a location where they can be picked up by the class-path

3. Run a ConfigEngine task to import the WCM library

4. Import the personalization rules through the user interface or the command line

Since the introduction of the SI, the deployment of all these resources can be automated without the

developer adding any deployment code. The resources must be packaged in the PAA format. The SI

also provides functionality to manage the installation of the resources in the correct order. It also

allows the developer to extend the functionality using additional configuration scripts when the

default functionality of the SI does not cover the required outcome.

Starting with WebSphere Portal 8.0, the SI using the PAA format is the recommended method for

packaging and deploying your content. The SI in WebSphere Portal version 8.0 and 8.0.0.1 is purely a

command line tool run through the configuration framework (ConfigEngine). However, in

WebSphere Portal 8.5 most of the functionality is now available through the Configuration Wizard,

which is the primary mechanism for performing WebSphere Portal configuration steps.

This paper will concentrate on best practices for creating the PAA file to deploy using the SI. It is

assumed that the reader has prior knowledge of the PAA file structure (See Figure 1). This paper is

intended as a complementary document to the PAA specification documentation found in the

product documentation and is not a replacement for the SI documentation. These best practices,

when followed, will ensure that the update procedure for your PAA content is simplified. Although

not strictly related to PAA creation, the final sections discuss the SI itself and best practices that

should be followed when using this functionality to install and deploy add-ons to WebSphere Portal.

Page 5 of 50

Not covered by this document is how the different resources are extracted from a running portal

server. Some of the resources such as war files and shared jar files will be produced by the chosen

build mechanism, however, others such as WCM libraries and xmlaccess scripts need to be extracted

from the running portal. Methods to do the extraction can be found in the WebSphere portal

documentation. Some additional editing of the resources may be required to ensure that the

resource can be applied to multiple systems, for example it is often necessary to edit xmlaccess

scripts to ensure that they are not server specific. As this paper describes best practices for using the

PAA file format, extracting/editing of individual resources was deemed to be out of scope, but may

be the subject of a separate document.

Because the SI has evolved over the last few years, there are some differences in how certain

resources are handled between versions. When these differences are encountered throughout this

paper, they will be highlighted. For example, with a PAA file created to be deployed on WebSphere

Portal 8.0/8.0.0.1, the developer must supply an assembly level sdd.xml file; however, in 8.5,

providing an sdd.xml file may not be necessary, as in certain circumstances, the sdd.xml file can

be automatically generated.

FIGURE 1: PAA FILE

Page 7 of 50

3 Terminology

Term Description

Component Smallest level of granularity for ConfigEngine install, can range from large

application to a number of resource types. For example, Unified Task List.

Assembly Group of components, for example the PortalServer ap or base

directories

Offering

A group of assemblies, for example PortalServer

Extension point Provides ConfigEngine with knowledge of type of functionality being

provided, e.g. create-ear-applySIFeaturePack informs

ConfigEngine that an ear file is being installed. Allows ConfigEngine to

group resources to install. (not to be confused with Eclipse extension

points)

sdd.xml Software Definition Descriptor, file containing information about the

application to install, found at all levels, e.g. component, assembly and

offering.

<SCU> elements Smallest configurable unit, added to component level sdd.xml files to

inform ConfigEngine of extension points available for the component.

PAA Portal Application Archive: structured zip file consumed by SI

Table 1 Terminology

4 Building a PAA file

A PAA file is a .zip file with a specific structure that denotes the types of resources it contains. SI uses

a combination of the directory structure and the resource file types to denote functionality when

generating code to do the deployment. SI expects PAA files to conform to the java.util.zip

format. If a different compression format is encountered it might throw an error. To be sure that

your PAA file conforms to this format you can either use a compression tool that specifically

generates this output or build the PAA file using ant or Java. An example of how to build using ant is

as follows:

<zip destfile=”sample1.PAA” basedir=”/tmp/sample1” />

You can also use the Java jar utility to build the .zip file. If using this tool, you need to ensure that no

manifest file is added to the output. Adding additional content to the top level of the PAA file is

problematic. The SI PAA validation code expects only one root directory at the top level of the PAA

file. If any additional files/directories exist at this level, an error will be thrown, as the PAA file is

deemed to be invalid. For this reason, the manifest file must be excluded.

When using the Java jar tool to build your PAA file you can use the ‘M’ option to ensure that no

manifest information is generated, leaving just the root directory at the top level of the PAA file. The

following is an example of how to build your PAA file using Java and Jar:

/opt/IBM/WebSphere/AppServer/java/bin/jar -Mcvf Sample1.PAA Sample1

Before Java 7, the java.util.zip classes were restricted to 32 bit encoding of .zip files.

Therefore, SI was unable to handle PAA files greater than 2GB in size. Because Portal 8.5 can run on

Java 7, this restriction should no longer be the case. However, if the server is running on Java 6 or

earlier, this restriction must be considered.

However, for the most part, a PAA file should never reach the size limits posed by the 32 bit

java.util.zip class. In general the only resource type that is typically large enough to cause a

PAA file to grow to this size would be a WCM library. For small libraries it makes sense to include

them in a PAA file. But for a large library, due to the time required to export the content and

subsequently import again on a new system, it is not recommended that the PAA file be used to

transfer this content. Instead, another means for transferring the content should be found. See the

section discussing the inclusion of WCM libraries in a PAA file for alternative methods of transferring

WCM content.

Page 9 of 50

5 The Assembly Name

The assembly name for your PAA file is an important consideration as it is for the most part what the

user will use when interacting with the PAA file after installation. The assembly name is also the root

directory name of the PAA file. That is, both the root directory name and the name of the assembly

in the assembly level sdd.xml file must be the same. ConfigEngine is also case sensitive, so ensure

that both the root directory name and the name references in the sdd.xml file match the correct

capitalization. A mismatch in capitalization between the assembly and root directory names is one of

the most common errors encountered with creating PAA files. When the case of the name and root

directory do not match, ConfigEngine is unable to resolve the correct path to the PAA content.

In Portal 8.5, SI can generate a basic assembly level sdd.xml file by using the root directory name,

and the list of available components. See the SI 8.5 documentation for further details.

The ConfigEngine enforces a strict unique assembly name policy. That is, your assembly name cannot

conflict with an existing core Portal assembly so SI will first check if a conflict exists, before allowing

the PAA file to install. If the assembly name is already part of the PortalServer offering, SI will

not install the PAA file.

As all PAA files are installed to a separate PAA offering, as opposed to the PortalServer offering,

the existing assembly would not be overwritten. However, the situation could occur where two

assemblies of the same name appear in the registry, once in the PortalServer offering and again

in the paa offering. As assemblies are referenced directly by their name and not restricted by the

offering name, an issue would arise when invoking tasks for an assembly as ConfigEngine will be

unable to resolve which assembly is required. Therefore the PAA based version of the assembly

cannot be installed where an assembly of that name already exists in the PortalServer offering.

If the assembly has already been installed with another PAA file, then SI will register the components

inside of the existing assembly of that name in the registry, which might pose issues further down

the line. For example, when the user attempts to deploy the PAA file using the advanced scenario of

the install add-ons workflows of the config wizard, all components for this assembly will be

presented to the user. A worst case scenario would be in the typical case where no selection choices

will be provided to the user for the components they want to install. That is, all components

registered would be deployed. Therefore, adding the components to a current assembly can cause

adverse effects for existing PAA files. The reason for not blocking the assembly from being

overwritten is to be able to support the update scenario for PAA files.

For this reason when naming your assembly you should choose something that is unique. But as the

customer is going to need to remember it, the recommendation is to ensure it reflects the type of

functionality provided by the application in the PAA file.

6 Adding PAA file components

There are a number of things to consider when adding resources to your PAA file. Do you place all

resources in a single component? Or spread them out over multiple components? How to select a

name for your component, and how the SI and ConfigEngine use that name? What potential is there

for clashes in component names?

6.1 Component naming schemes

As with the assembly names discussed in the previous section, each PAA component must also have

a unique name. There is less of a chance of the component name clashing with a Portal component

as each PAA component has the word components/ in its name. However, to ensure that existing

PAA files that were initially released on the catalog, whose functionality has moved into the core

Portal offering, cannot be installed and overwrite the core component, SI will check to see whether

the component name minus the components/ already exists in the PortalServer offering. If it is

found, then the component will not be registered as part of the assembly.

There is potential though for component names to clash between PAA files. Observations have

shown a tendency for some PAA developers to name their components based on functionality, such

as, components/wcm for WCM content and components/theme for theme content. Following

such a naming scheme can cause problems for the install. If more than one PAA file containing

components with the same name are installed, then due to the ConfigEngine restriction for unique

component names, only one component will be registered. The SI default behaviour on installation is

not to register the new component, instead it will leave the existing one, and assume that the

existing version is a shared component. That is, the existing version of the component can be used by

both PAA files. The user can overwrite the default functionality by setting the property in the

wp_profile/PAA/<assemblyName>/components.properties for the component to true

and then run the update-PAA-components task. However, this task will remove the existing

component from the registry and then register the new component. In cases where it is intended

that components are shared across PAA files an issue should not arise. That is, if the component is a

later version of the previous one and is still compatible with the installed application. However, for

most situations, these components are intended to be unique to the application in the PAA file in

which they are included, so overwriting a previously installed component might break existing

applications.

It is therefore recommended that you choose a name specific to the PAA file for your component, for

example, include the assembly name in the component name e.g. an assembly name of

government could have a component name of components/government.wcm or

components/gov.wcm. Although potentially there could be two different government PAA files,

there is less likely to be a component name clash as there would otherwise be.

Page 11 of 50

6.2 Separating your resources in to multiple components

A PAA file must have at least one component, however there are no upper limits on the number of

components that can be included. So it is often a matter of choice how many components a PAA file

should have.

For smaller applications it makes sense to have only one component as the entire application must

be installed or deployed. Where there are optional pieces of an application, or if the developer wants

to offer alternative content; for example, different WCM libraries, or an alternative page structure, it

is advised that the separate optional pieces be placed in additional components. The user can then

select at deploy time the components they want to deploy. For example, you might have an

application with some additional demo content. If the user wants to evaluate the application they

might decide to deploy the demo content to the server. But when using the application on a

production system, deploying the demo content might not be appropriate.

Similarly many PAA file developers want to include content specifically to be run on a virtual Portal,

with the other pieces still running on the base server. SI can only deploy to a single target Portal at a

time, either the base or a virtual Portal, so it makes sense to move the virtual Portal content to its

own component. So the other components can be deployed to the base Portal, and on a subsequent

run of the SI deploy-PAA task, the virtual Portal content can be deployed separately.

Another reason for adding multiple components to your PAA file is to separate resources based on

functionality. For example, putting all theme related resources in a separate component. The

advantage of using multiple components is that it makes it easier to only update a specific piece of

the application. It also makes it easier to debug issues as you can limit the deployment to an

individual component.

For these reasons it is a best practice to split resources of large applications into multiple

components. These components would include separate components for demo content, virtual

Portal specific content or alternative page structures/WCM content. However, for maintainability

purposes it is often beneficial to separate out other resources into functional components. It is not

recommended to do the separation on a resource by resource basis, as the Extension point approach

will already achieve the same result. However, splitting your application into components based on

functionality makes more sense. As these components can be deployed/removed separately from

other components making it easier to test the content, or apply changes to the resources.

7 Using additional properties in a PAA file

The WebSphere Portal configuration framework through which the WebSphere Portal SI is run,

requires unique names for globally set properties. The unique names requirement for global

properties is a general feature with ant based projects. When the ConfigEngine is run (either through

the config wizard or from the command line) all ant tasks and properties in components registered

with the framework are loaded into the ConfigEngine project. Once loaded all ant properties are

immutable meaning once instantiated they cannot be changed, unless they go out of scope. If the

same property exists in multiple components registered with the configuration, then the first

instance of the property encountered by the framework will be instantiated and its value will be

used throughout the framework. Therefore, the use of non-unique property names can potentially

cause some unpredictable results. This restriction applies primarily to global properties declared

outside of an ant task.

As all ant tasks and properties that are registered with the framework through a PAA file install are

all loaded as part of the overall ConfigEngine project, this restriction will also apply to PAA files. For

this reason, it is recommended that global property names reflect either the PAA assembly name or

the name of the component where they are created. It will ensure that the property name will not

clash with existing properties. For example a component named components/sample1 could

have a property name of components/sample1.property1.

8 SDD file generation

8.1 Assembly level sdd.xml file

Since WebSphere Portal 8.5, SI can automatically generate a basic assembly level sdd.xml file. It uses

the PAA file root directory name as the assembly name and retrieves the list of components from the

components directory. If an order.properties file is found in the components directory, the

list of components set in this file will be used as the component list and any additional directories

will be ignored. Limiting the list of components to those listed in the order.properties file allows for

additional directories to be included in the PAA file but not to be part of the deployment. For

example a directory containing content that must be added to a different server than Portal, but is

packaged as part of the PAA file. As the order.properties file governs the order in which

components are deployed, all components that must be deployed should be included in this file,

otherwise they won’t be added to the sdd.xml file.

Page 13 of 50

Consider adding an assembly level sdd.xml file if you have additional components in your PAA file

such as those intended to be deployed on a virtual Portal, or containing demo content. If such a

component is added to the order.properties file, a dependency will be added between it and

other components. The dependency assignment results in dependent components being run during

the deployment of the virtual Portal component, which would have unpredictable results. If there is

no need for an order between the components you can leave out the order.properties file and

the assembly level sdd.xml file can be generated from the full list of the components. However, it

would prevent the inclusion of additional directories in the components directory.

Finally if you need to add either a dependency on a specific server version or on the presence of

another PAA assembly, then a developer provided assembly level sdd.xml file is necessary. You can

use the PAA files in the wp_profile/doc/PAA-samples directory for examples of how to add

the assembly level sdd.xml file.

8.2 Component level sdd.xml file

All versions of SI since WebSphere Portal 8.0 can generate the component level sdd.xml file. It

derives the component name by extracting the path from the root directory of the PAA file to the

component directory and will generate a basic sdd.xml file based on this value. It will only perform

this step if no component level sdd.xml file exists.

Whether the sdd.xml file is automatically generated or supplied as part of the component, the next

steps remain the same. SI will generate any default code necessary for the deployment of resources.

It will first check if an existing implementation task exists before generating code. Once this step is

complete, the full list of extension point implementation tasks is examined and <SCU> elements to

register the tasks are automatically generated and added to the sdd.xml file. Therefore, when you

add a custom implementation task, there is no need to add a <SCU> element to the sdd.xml file

because SI does it automatically. However, if an existing <SCU> element for a specific extension

point exists, then SI will not overwrite it because it might set dependencies on another component.

For Portal 8.0 and 8.0.0.1, the only time you need to manually add an <SCU> element is when you

add a dependency on another component. In this case a developer provided component level

sdd.xml file is necessary. However, if there are no dependencies between components, for

example, you do not need component ‘A’ installed before component ‘B’, then it is recommended

that you let SI automatically generate the component level sdd.xml file.

For Portal 8.5, you can still add component dependencies by manually adding <SCU> elements to

the component level sdd.xml file, however, as dependency generation can now be automated it is

no longer the recommended method for adding such dependencies. Therefore, it is best practice to

let SI create the component level sdd.xml file and allow SI to generate any component

dependencies. The method for setting component dependencies in 8.5 is discussed in the next

section.

8.3 Component dependencies

SI relies on the mechanism built into the config framework to set the order in which components are

deployed. It is achieved by setting a requirement from one implementation of an extension point

task to another implementation of that extension point included in another component. See the

section on ‘adding custom code’ for more details of how to implement an extension point. Although

it is possible that different extension points of a component will have dependencies on different

components, it is normally the case that either there are no dependency requirements or that only

one component is required.

The dependency is set by adding a <requirements> element to a <SCU> element as follows:

<SCU id="deploy-apps-applySIFeaturePack" targetRef="OS">

<Identity>

<name>Do Configuration Task</name>

<version>1.0.0.0</version>

<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-apps-

applySIFeaturePack" />

</parameters>

</configArtifact>

</unit>

Page 15 of 50

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

<requirements>

<requirement name=" deploy-apps-applySIFeaturePack">

<alternative name="components/component1"/>

</requirement>

</requirements>

</SCU>

The <requirements> element can contain one or more <requirement> elements, each one

representing a component on which the current component depends on being previously installed.

The name attribute of the <requirement> element can be set to whatever value the developer

chooses. The name attribute of the <alternative> element must equal the full name of the

component on which the current extension point depends. The dependency link is between

extension points. If you add the <requirements> element to the <SCU> element for the deploy-

apps-applySIFeaturePack, register an equivalent deploy-apps-applySIFeaturePack

extension point for the dependent component.

Prior to Portal 8.5, a developer was required to manually add these items to the component level

sdd.xml file where there was a dependency on having a component previously installed. See the

section of the official SI documentation concerning ‘The component level sdd.xml file’ for more

details on how to edit the <SCU> element and its sub elements.

Since 8.5, although the mechanism used for setting the requirements is the same, this step can now

be automated as part of the code generation phase.

To ensure that the dependencies can be automatically set between components on Portal 8.5, add

an order.properties file to the assemblyName/components directory. This file should

contain a comma separated list of components in the order in which they should be deployed. If

there is no need for a dependency on a specific component, there is no need to include it in the

order.properties file, unless it is required for generating the assembly level sdd.xml file, see

previous section for more details. The following is an example of the content of the

order.properties file:

Components/component1,components/component2,components/component3,…

The SI will then generate dependencies between the extension points shared between components.

If there is no shared extension points between two components in the order in which they appear in

the order.properties file, then the dependency is created on the next component in the list

that does have an instance of the extension point. Dependency generation occurs after all code

generation has taken place so all custom and auto generated extension point implementation tasks

are available.

For example, if the dependency is being created on the deploy-apps-applySIFeaturePack

extension point for components/component3, SI will check components/component2 to see if

this component has an implementation task for this extension point. If so, it will set the dependency

on the <SCU> element for the extension point in the component level sdd.xml file of

components/component3 to point to components/component2. If there is no implementation

of the extension point in components/component2, then it will check for such a task for

components/component1. If the extension point is implemented there, then the <SCU> element

for the extension point in components/component3 will have the dependency on

components/component1. If all three components implement the extension point, then a chain

of dependencies for the extension point will be set between the 3 components i.e.

components/component3 will depend on components/component2 and

components/component2 will depend on components/component1.

The order is set on a per extension point basis, so that the deploy-apps-applySIFeaturePack

of components/component3 might depend on components/component2, but the create-

ear-applySIFeaturePack of components/component3 could depend on

components/component1.

Not all extension points allow for dependencies to be set in this way. It is generally the case for

extension points that interact with the application server, such as, create-ear-

applySIFeaturePack or create-library-applySIFeaturePack, however, extension

points that are Portal server specific, do not have this flexibility. It is due to not being called directly

by the config framework, but from a task generated by SI. This task is the implementation of the

deploy-apps-applySIFeaturePack extension point. It will call any Portal related tasks such as

deploy-portlets-applySIFeaturePack and any SI specific extension points such as

import-wcm-applySIFeaturePack, install-content-xmlaccess-

applySIFeaturePack, etc. If you have a dependency on such tasks then the dependency should

be set on the deploy-apps-applySIFeaturePack extension point and not on the individual

extension points.

In the section discussing extension point best practices, a table showing the full list of supported

extension points in the order in which they are invoked by SI is included. Also included in the table is

information on whether a dependency is allowed for that extension point. If no dependency is

allowed, then the dependency must be assigned to the deploy-apps-applySIFeaturePack

extension point instead.

Page 17 of 50

8.4 Server dependencies

Since Portal 8.0 it has been possible to add a check to your PAA file to restrict the server versions to

which your PAA file deployment is compatible. It is done by adding a

<serverVersionDependency> tag to your assembly level sdd.xml file. You can find out more

information on how to set these dependencies in the topic ‘Checking server dependency’ in the SI

documentation.

Although it is not strictly necessary that this information be added to a PAA file, it will prevent SI

installing the PAA file and registering it with the ConfigEngine if the current WebSphere portal

version is not supported by the PAA based application. If you are deploying the PAA file regularly as

part of a maintenance cycle, with incremental changes then adding server dependencies may be

unnecessary. However, if you are producing a PAA file to be released to a third party, it is

recommended that you ensure that the PAA file cannot be installed on server versions with known

incompatibility issues. It will ensure that defects are not raised where problems have arisen due to

incompatibility issues between your PAA version and an unsupported WebSphere Portal version.

Since Portal 8.5, you can also add a restriction based on the cumulative fix level. That is if you have a

dependency on a specific fix level to be installed prior to the PAA install, you can ensure that the PAA

file will not be installed without this prerequisite.

8.5 PAA file dependencies

It is often the case that a PAA file might require that one or more additional PAA files be installed

prior to its deployment. When such files are not available, it can cause errors during the deployment

phase. It usually means that the application is unable to function correctly. In Portal 8.5, the ability to

set a dependency from one PAA file to another was introduced. The reason for introducing this

functionality is to allow for a PAA file to be able to verify if another PAA file on whose functionality it

depends has already been installed. Therefore, at install time SI can now check that the prerequisite

PAA file has already been installed before proceeding with the registration of the current file.

To set a dependency on another PAA file, a <PAADependencies> element must be included in the

sdd.xml file. For each PAA file on which there is a dependency, add a <PAADependency> sub

element. For example:

<PAADependencies>

<PAADependency name=”dependency1”/>

<PAADependency name=”dependency2”>

</PAADependencies>

As with the server version dependencies, PAA file dependencies also must be set in the assembly

level sdd.xml file. For more information on the element and its attributes see the topic ‘PAA

dependencies for deployment and removal’ in the SI documentation.

This setting serves a dual purpose. As well as preventing a PAA file from installing when its

prerequisites are unavailable, it can help in providing an order to the install of multiple PAA files. The

facility exists to install multiple PAA files at once, when installing/deploying your PAA content

through the config wizard. Providing a comma separated list of PAA files in the install location of the

install add-ons workflow will ensure that multiple PAA files are installed. When deciding what

order in which the PAA files are to be installed/deployed, The PaaDependency tags are taken into

account. If there are no such elements then the order of the install/deployment doesn’t matter,

however, if a dependency exists, then it is important that SI has a mechanism to be able to

determine the order for deployment.

9 Adding custom code

There are many situations where it might be necessary to add custom deployment code to your PAA

file. Although SI does generate code to deploy a number of resource types, there are others for

whom the deployment is not so easily automated. In these situations custom code provided by the

developer is required. Another scenario where custom code might be necessary is when SI auto

generated code does not cover the requirements for deploying your resources, so a custom

implementation task is necessary. However, it is recommended best practice where SI automatically

produces code to deploy a resource type, it should be used instead of adding custom code to handle

these resources. Unless limitations in the auto generated code prevent the configuration of the

resources being accurately completed. This will help with the maintainability of the PAA file, as

changes in the underlying configuration tasks will be reflected in the auto generated code.

No matter which extension point you want to implement, you can create an ant task meeting the

extension point task naming scheme and place it in an xml file in the config/includes directory

of the component. This task is then picked up by SI at installation time and registered with the

ConfigEngine. The following is an example of a task following the required naming scheme:

‘Action’+ extension point Name + componentName.

In the case of a PAA file with a component name components/component1 a task implementing

the create-ear-applySIFeaturePack extension point would look like:

<target Name=”action-create-ear-applySIFeaturePack-

components/component1”>

Page 19 of 50

…

</target>

The SI will search the config/includes directory of each component and retrieve the list of

extension point implementation tasks. It then does a look up against the resource types included in

the PAA file and determines if there is already an implementation task for the extension point

assigned to a specific resource. If so it will not try to generate code for that resource, instead, it will

move on to the next resource type. Therefore, if you are adding a custom task to handle the install of

a resource in a component, the same task should be used to deploy all resources of that type. For

example, if you are implementing the create-ear-applySIFeaturePack extension point, the

task will need to deploy all ear files in the installableApps/ear directory of the component. Ear

files in another component will not be affected and can still be deployed with auto generated code.

For a full list of SI supported extension points, see the section ‘Extension Points Best Practice’ below.

SI will automatically create <SCU> elements for any detected extension point implementation tasks

and add them to the sdd.xml file. Therefore, unless you need to apply a component dependency to

the <SCU> element, there is no need to manually add such content. It is best practice to allow SI

handle <SCU> element creation as part of the sdd.xml file generation. In 8.5, the dependencies

can be also generated, see previous section for further details.

NOTE: Any tasks included in the config/includes directory that do not adhere to the naming

scheme will be ignored by SI, unless they are called from other extension point implementation

tasks.

9.1 Adding unless="isSecondNode” attribute

As is discussed in the section on deploying PAA files to a Portal cluster environment, the PAA file

must be installed and deployed to each node of the cluster. It will ensure that all resources that

cannot be replicated across all the nodes can be installed on each node. An extension point

implementation task should only be run on additional nodes to the primary node if the resource

type, such as a shared jar file cannot be replicated by the deployment manager. Therefore, to

prevent your custom task from running on every node, the unless=”isSecondNode” attribute

must be set on the task definition. The following example shows how to set the attribute:

<target Name=”action-create-ear-applySIFeaturePack-

components/component1” unless=”isSecondNode”/>

…

</target>

9.2 Installing non-portlet war files

When installing non-portlet war files they can be included in the installableApps/war

directory. These files will then be copied across to the ${WasUserHome}/installableApps

directory, e.g. wp_profile/installableApps where they can be referenced by the custom

deployment code. There are a number of options for how the war file can be deployed.

You can use a Jython / jacl script to perform the deployment. It can be invoked through the use of

the <wsadmin> task. There is currently no extension point specifically set aside for this

functionality, however, you are free to include this functionality under one of the more general

extension points such as pre-apply-PTF-applySIFeaturePack

You can also use the wplc-create-ear task to do the deployment. This task will wrap the war file

in an ear before deploying it to the server. For example:

<wplc-create-ear

appname="SampleWar"

earfile="${WasUserHome}/installableApps/SampleWar.war"

wasuser="${WasUserid}"

waspassword="${WasPassword}"

cell="${CellName}"

node="${NodeName}"

server="${ServerName}"

startingweight="25"

conntype="${wsadminConnType}">

<option key="usedefaultbindings"/>

</wplc-create-ear>

IMPORTANT: The <option key="usedefaultbindings"/> nested element is necessary to

ensure that WebSphere application server uses the default bindings for items such as the

MapWebModToVH setting etc. Otherwise, they will need to be set separately as <option>

elements nested inside of the task.

Page 21 of 50

An alternative to adding custom code would be to wrap the war file inside of an ear file. The default

SI ear file deployment code can then be used to do the deployment. That is, once the ear file is

placed in the installableApps/ear directory of the component.

9.3 Using ant properties in xmlaccess scripts

You can reference ant build properties in your xmlaccess scripts by placing the property name in

between ‘@’ signs in the xmlaccess script. For example:

http://@WasRemoteHostName@:@WpsHostPort@/@WpsContextRoot@/Portal

These properties can be substituted by the ConfigEngine/SI when the script is run. Placing the script

containing properties in the content/xmlaccess/install or

content/xmlaccess/uninstall directories of the component will ensure that the SI will

replace the property place holders with the actual property values from the ant build. You can set

the properties in properties files inside of the PAA file or on the command line and SI will do the

substitution automatically.

To ensure that such properties can be substituted in the scripts when the script is invoked from

custom code, you need to add the following lines of code to your custom ant task:

<si-set-xmlaccess-url/>

<filtersetall />

<copy toDir="${work.dir}/componentName" file="${xmlaccesspath}"

filtering="true" overwrite="true" encoding="UTF-8"/>

<xmlaccess user="${PortalAdminId}"

password="${PortalAdminPwd}"

url="${si-XMLAccessUrl}"

srcfile="${work.dir}/componentName/${xmlaccessFileName}" />

The si-set-xmlaccess-url macro creates a property containing the correct URL that will

include any virtual Portal information if present for the call to xmlaccess. Include it only if you are

overwriting the deploy-apps-applySIFeaturePack task. If the deploy-portlets-

applySIFeaturePack or install-content-xmlaccess-applySIFeaturePack tasks are

being overwritten, then there is no need to include this macro call. The action-deploy-apps-

applySIFeaturePack-components/componentName task, that is auto generated to handle

calls to the other 2 extension points, will already include this line.

The substitution of the properties is performed during the copy task. It is recommended that the file

is copied over to a sub directory of the ConfigEngine work directory, ${work.dir}. The

<xmlaccess> task should load the script file from this location.

9.4 Referencing locations inside of the PAA file

When a PAA file is installed to the ConfigEngine a number of properties to denote the location on the

server of the expanded PAA file assembly and its components are auto generated. These properties

have a naming scheme that once followed, custom code can directly reference these locations during

the deployment without needing to extrapolate them from the ${WasUserHome} and

${wp.si.offeringName} properties.

In the case of the assembly, the property is derived by taking the assembly name, capitalising the

first letter and appending the word ‘Home’ to the end. For example an assembly name of sample1

would be referenced through the property ${Sample1Home}. This property will contain the path to

the expanded PAA file in the PAA directory under the profile.

Similarly for components, the property is generated using the componentName with the first letter

capitalised followed by the word ‘Home’. For example, a component called

components/Component1 would be referenced using ${Components/component1Home}.

9.5 EAR file deployment

When overwriting the SI auto generation of code for deploying ear files, take care that any code

changes are compatible with deploying applications to a Portal cluster environment. There are three

separate extension point implementation tasks generated by SI for ear file deployment. Overwriting

one of these tasks with a custom task will not prevent SI from generating code for the other two.

create-ear-applySIFeaturePack: This extension point handles the deployment of ear files

to the server. If you overwrite the default code for this task, make sure that you include all of the ear

files in the directory of your component. When SI detects the presence of an implementation task, it

will assume that the developer has already provided install code for all instances of the resource type

for that component and will move on to the next resource type.

modify-ear-applySIFeaturePack: This extension point task is used by SI to modify the server

mappings assigned to a web module. When the ear file is installed using the wplc-create-ear or

wplc-update-ear tasks, the default server mapping is assigned to the server to which the

deployment takes place. In the case of a Portal cluster environment, the mapping of the web module

is assigned to the deployment manager by default and not the WebSphere Portal servers. Similarly if

Page 23 of 50

there are multiple servers on a single node, then the mappings are only applied to the WebSphere

Portal server to which it was deployed and not replicated out to the other servers. To alleviate this

issue, SI applies the same mappings to the web modules that are assigned to the wps.ear web

modules. In this way the web modules are then correctly mapped to the same set of servers as the

Portal core applications.

If you want to assign different mappings to the web modules or require that no mappings are to be

assigned, then you need to overwrite this task. Once the implementation task is detected, even if it is

an empty task, SI will assume that the developer does not want to automatically create web module

mapping code.

start-ear-application: In this extension point implementation task, SI will attempt to start

the ear file applications. This task can fail to start the applications if there are dependencies on

external jar files that are not on the class-path of the running server. Therefore if you want SI not to

attempt to start the ear file, then you need to overwrite the task, for example:

<target name=”action-start-ear-application-applySIFeaturePack-

components/componentName”/>

If SI fails to start the application, the build will not terminate but will continue to process the rest of

the deployment. In most cases, it will have no adverse effect on the deployment process. Restarting

the server after the deployment has completed will ensure that the ear file applications are started,

as any jar files included in the PAA will be added to the class-path. Alternatively, if you start the

deployment phase when the Portal server is stopped, the jar files will be added to the class-path

before SI starts the server to perform the credential validation, so when the ear file is deployed, the

jar files in the shared/app directory of the components will already be available. See the section on

running SI with the Portal server stopped for more details.

Deploying the PAA file when the server is stopped will not help in the case where there are jar files in

the components/componentName/shared/common directory because the shared library will

not be created until after the Portal server has been started. Therefore, they will not be available on

the class-path until the next server restart.

It should also be remembered that portlets contained within an ear file are not automatically

registered with the Portal server during the ear file deployment, therefore an xmlaccess script is

necessary to perform the registration.

9.6 Invoking Jython scripts from custom code

A Jython wsadmin script can be invoked from custom code using the wsadmin task provided by the

WebSphere application server team. It can be run directly from the ConfigEngine, for example:

<wsadmin

script="${Sample1Home}/config/templates/test-sample.py"

conntype="SOAP"

host="${WasRemoteHostName}"

port="${WasSoapPort}"

user="${WasUserid}"

password="${WasPassword}"

failonerror="yes"

lang="jython">

</wsadmin>

If a wsadmin script encounters an error and does not throw an exception, the SI and ConfigEngine

will continue with the deployment. There is no mechanism for automatic feedback between the

process that runs the script and the ConfigEngine. However, if an exception is thrown by the

wsadmin script, it can be processed by the si-trycatch statement and a build failure can be

produced. Stopping the deployment at the point of failure will ensure that the deployment fails at

the stage where the error occurred and not at a later point when the resource is that failed to

configure is needed by the deployment process. It will ensure that the issue is easier to debug

because the termination of the deployment process will be at the point where the original issue

arose.

The following is an example of how to throw an exception in a Jython wsadmin script:

def isConnected():

try:

conntype = AdminControl.getType()

except:

#print "Not connected to server"

return 0

#print "conntype=%s" % conntype

return 1

isConnected()

Page 25 of 50

The error information from the exception thrown can be accessed by using the si-trycatch

statement. See further details on how to handle the exception in the next section.

It is important to remember that if you make a change to the application server master configuration

inside of a jython script, you will need to ensure that you save your changes. SI will not do this

automatically after the wsadmin task has completed.

9.7 Catching Errors

Since Portal 8.5, SI uses a different try-catch statement that provides better access to the actual

error message and stack trace from errors thrown by the application server during the deployment

of resources. It has resulted in improved logging of error information, making it easier to debug

issues. You can also include the new try catch statement in your custom code to ensure that you

receive more accurate information about the errors being thrown.

<si-trycatch>

<try>

…

</try>

<catch>

<echo>ExceptionMessage is: ${exceptionMessage}</echo>

<echo>StackTrace is: ${stackTrace}</echo>

</catch>

<finally>

</finally>

</si-trycatch>

10 Extension Points Best Practice

The first thing to note on the use of extension points is how the ConfigEngine and SI order the tasks

during the deployment. The deployment works on a per extension point basis, meaning that all

implementation tasks for a specific extension point are run consecutively before moving on to the

next extension point. All the create-ear-applySIFeaturePack tasks for the components in

the PAA file are run together before moving on to the next resource type. For more details on how to

implement an extension point, see the section on ‘adding custom code’. The grouping of extension

point tasks allows ConfigEngine to manage the interaction with the application server and save the

configuration in a single step, saving on the time it would take to deploy and save after each task

separately.

It is strongly recommended that extension points are implemented to drive the deployment of

resources, and not to use a set of many custom targets called from a single extension point. The

latter removes the ability of the ConfigEngine to optimise the deployment procedure. Calling all tasks

from a single extension point would also mean that the tasks would need to save the configuration

themselves as the deployment is progressing. New tasks looking up the configuration will still be

reading from the master configuration. If the changes have not been committed and saved, then the

resources that prior tasks have configured might not be reachable by later tasks.

The SI specific extension points, for example import-wcm-applySIFeaturePack or install-

-content-xmlaccess-applySIFeaturePack as these are called by the deploy-apps-

applySIFeaturePack extension point and not managed directly by the framework. However, all

instances of the deploy-apps-applySIFeaturePack extension point will be grouped together.

These tasks tend to deal directly with the Portal server installation tools such as WCM import and the

xmlaccess tool. These tasks will not run into the same issues with saving to the application server

configuration because the tools on which they rely save the content automatically.

When implementing an extension point task, ensure that you cover all resources covered by that

extension point for that component. If you are overwriting an extension point for which SI can auto

generate code, make sure all resources in the component mapping to that extension point are

covered by your task. SI does not parse the tasks to ensure that all resources are handled.

It is also important to use extension points for their intended purposes and do not overwrite to

handle unrelated resource types. The temptation may occur to overwrite an unused extension point

by the PAA file when a resource type doesn’t map easily to one of the named extension points. This

is not recommended as the extensions are designed around individual resource types and adding

unrelated resources may cause issues during the saving of the configuration. Any save to the

configuration occurs after all the extension point tasks for a specific extension have completed.

Page 27 of 50

Where there are no direct mappings for a resource to an extension point, one of the following

general extension points can be used:

Pre-apply-PTF-applySIFeaturePack: Run at the start of the deployment process.

post-apply-PTF-applySIFeaturePack: Run at the end of the deployment process.

Pre-remove-PTF-removeSIFeaturePack: Run at the start of the remove-paa task.

post-remove-PTF-removeSIFeaturePack: Run at the end of the remove-paa task.

These extension points are intended to handle generic configuration tasks and should be used where

an equivalent resource specific extension point does not exist. Note that if you are invoking a jython

script that makes changes to the application server master configuration you will need to add a save

command to the script to ensure that your changes are stored.

10.1 Which extension points to use for a given scenario

There are 4 groupings of tasks for the SI whose invocation depends on the scenario being employed.

In general terms, extension points ending with applySIFeaturePack are called during the

deployment, whereas those ending in removeSIFeaturePack are called during the removal of

resources. Those ending with updateSIFeaturePack and rollbackSIFeaturePack are run

during an install or rollback of an update to your PAA file.

The set of tasks available for the updateSIFeaturePack extension is the same as for the

applySIFeaturePack, and the rollbackSIFeaturePack are the same as for the

removeSIFeaturePack tasks. The only difference is the suffix appended to the end of the

extension point.

NOTE: SI does not auto generate any updateSIFeaturePack or rollbackSIFeaturePack

tasks. They need to be added by a developer as custom code.

10.2 Removing items during the deployment phase

During the deployment phase, the SI will run any tasks that have the applySIFeaturePack

extension. In general, these tasks are for creating, modifying, updating, and deploying content.

However, you can also run remove tasks. These tasks differ from the tasks that have the

removeSIFeaturePack extension which are run during the remove-PAA task and will not be

invoked during the deployment. However, if one of the remove tasks has an extension of

applySIFeaturePack for example remove-ear-applySIFeaturePack then it will be

invoked prior to the tasks to deploy ear related resources. In this way individual resources can be

removed before new versions are deployed.

It is still recommended to use the removeSIFeaturePack extension for remove tasks. However, if

a PAA file is being run as a maintenance task for an existing PAA file then it might be necessary to

remove specific resources before deploying newer versions. You must have some mechanism in

place to determine what resources exist prior to removal. If the PAA file is being installed on a clean

server, the lack of a resource, when SI attempts to remove it, might throw errors. It might even

result in the PAA file failing to deploy. Because the task is an applySIFeaturePack, there is no

simple way to have the task skipped during the deployment phase.

Not all extension points have this facility built into the ConfigEngine. Those extension points that are

called by the deploy-apps task will not be called in this manner. Therefore, if it is necessary to

remove Portal specific items you will need to implement the remove-apps-

applySIFeaturePack extension point to remove these resources.

10.3 The deploy-apps-applySIFeaturePack and remove-apps-removeSIFeaturePack extension points

Both of these extension points have great significance for the SI deployment and PAA removal

processes. These are the 2 extension points used by SI to run WebSphere portal specific

configuration tasks such as for deploying/removing portlets and running xmlaccess scripts. The auto

generated tasks for the deploy-apps-applySIFeaturePack and remove-apps-

applySIFeaturePack extension points invoke any extension points that are included that do not

have a direct mapping to a ConfigEngine extension point, for example, deploy-portlets-

applySIFeaturePack and install-content-xmlaccess-applySIFeaturePack. Once

tasks for handling the deployment of these resources are found, calls to the extension point tasks are

added to the higher level deploy-apps-applySIFeaturePack and remove-apps-

applySIFeaturePack extension point implementation tasks. These higher level tasks are also

responsible for checking that the server is currently started before deploying portal resources, and

sets some additional configuration properties such as the xmlaccess url to use when invoking the

<xmlaccess> task. Therefore, it is not advisable to overwrite these tasks. Instead one of the other

generic extension points should be considered such as the pre-apply-PTF-

applySIFeaturePack for custom tasks.

If it is a case that you need to overwrite the deploy-apps-applySIFeaturePack or remove-

apps-applySIFeaturePack extension points, you should ensure that you add any calls to any

portal related extension point implementation tasks that are included in the PAA. This is the case for

both custom tasks and for those that are auto generated

Page 29 of 50

10.4 List of available extension points

The following table shows the list of extension points invoked during a deployment in the order in

which they are called:

Extension point name Description Mapping Component

Dependencies

Auto-

generated

pre-apply-PTF-

applySIFeaturePack

Extension point run at

start of deployment.

suitable for pre-

deployment setup

yes No

remove-application-library-

references-

applySIFeaturePack

Removes shared

library references

shared/common yes No

remove-ear-

applySIFeaturePack

Remove EAR file installableApps/ear yes No

remove-resource-

environment-entry-

applySIFeaturePack

remove resource

environment provider

entry

yes No

remove-resource-

environment-provider-

referenceable-

applySIFeaturePack

remove resource


reference

yes No

remove-resource-


custom-property-

applySIFeaturePack

remove resource


custom property

yes No

remove-resource-


applySIFeaturePack

remove resource


yes No

remove-dataSource-

applySIFeaturePack

Remove the

datasource

content/database yes No


Dependencies

Auto-

generated

remove-jdbc-provider-

applySIFeaturePack

Remove the JDBC

provider


remove-j2c-auth-

applySIFeaturePack

Remove J2C

authentication alias


remove-app-server-library-

references-

applySIFeaturePack

Removes shared

library to server

classpath


remove-library-

applySIFeaturePack

Removes shared

library


remove-app-server-

classloader-

applySIFeaturePack

Remove appserver

classloader

yes No

remove-host-alias-

applySIFeaturePack

remove host alias yes No

create-host-alias-

applySIFeaturePack

Create new host alias yes No

create-app-server-

classloader-

applySIFeaturePack

Create new appserver

classloader

yes No

create-library-

applySIFeaturePack

Creates shared library shared/common yes Yes

create-app-server-library-

references-

applySIFeaturePack

Adds shared library to

server classpath

shared/common yes Yes

Create J2C authentication

alias

content/database Yes yes

create-jdbc-provider-

applySIFeaturePack

Create the JDBC

provider in the

WebSphere

application server

content/database yes Yes

Page 31 of 50


Dependencies

Auto-

generated

configuration

create-dataSource-

applySIFeaturePack

Create a datasource content/database yes Yes

create-resource-


applySIFeaturePack

Create new resource


yes No

create-resource-


custom-property-

applySIFeaturePack

Create new resource


custom property

yes no

create-resource-


referenceable-

applySIFeaturePack

Create new resource


reference

yes No

create-resource-

environment-entry-

applySIFeaturePack

Create new resource


entry

yes No

update-ear-

applySIFeaturePack

update ear file installableApps/ear yes No

create-ear-

applySIFeaturePack

Deploy ear file installableApps/ear yes Yes

modify-ear-

applySIFeaturePack

modify deployed ear

file, Default code

resets mappings on

web modules

installableApps/ear yes Yes

edit-ear-applySIFeaturePack edit ear file installableApps/ear yes No

create-application-library-

references-

applySIFeaturePack

Creates shared library

references

shared/common yes Yes


Dependencies

Auto-

generated

remove-apps-

applySIFeaturePack

runs Portal specific

remove tasks

yes No

deploy-apps-

applySIFeaturePack

s Portal specific

deployment tasks

yes Yes

start-ear-application-

applySIFeaturePack

starts any ear based

applications deployed

in the component

installableApps/ear no Yes

Delete-wcm-

applySIFeaturePack

Delete wcm libraries,

used to remove

libraries found with

the -

Dwcmdetect=true

parameter, before

newer versions

imported

content/wcm no yes

import-wcm-

applySIFeaturePack

Imports WCM

Libraries

content/wcm no Yes

deploy-portlets-

applySIFeaturePack

Deploy portlets from

WAR file

installableApps/port

lets

no Yes

create-personalisation-rules-

applySIFeaturePack

Imports the

personalization rules.

content/pzn no Yes

start-portlet-application-

applySIFeaturePack

starts any deployed

portlets found in the

component

installableApps/port

lets

no Yes

install-content-xmlaccess-

applySIFeaturePack

Runs XML install

scripts

content/xmlaccess/i

nstall

no Yes

Copy-war-files-

applySIFeaturePack

Copy war files to the

Profile_dir/installable

Apps directory

installableApps/war no Yes

Import-WebDav –

applySIFeaturePack

Uploads WebDav

artefacts to the IBM®

WebSphere® Portal

content/WebDav no Yes

Page 33 of 50


Dependencies

Auto-

generated

WebDav file store

add-templates-

applySIFeaturePack

Installs template templates no Yes

deploy-pages-

applySIFeaturePack

Deploys pages yes No

post-apply-PTF-

applySIFeaturePack

Extension point run at

end of deployment.

suitable for post-

deployment config

yes No

Table 2 List of available extension points

The following table shows the extension points SI invokes during the uninstall. The set of extension

points is the same as for the deployment, the primary difference is the removeSIFeaturePack

suffix. Therefore the create extensions listed above can also be called during the removal,

however, SI does not generate any implementation tasks for these extension points automatically.

The following table only shows the list of extensions specific for removing your PAA file from the

Portal server.

Extension point

name

Description Mapping Component

Dependencies

Auto-

generated

pre-remove-PTF-

removeSIFeaturePack

Extension point run

at start of removal.

suitable for pre-

removal setup

yes no

remove-application-

library-references-

removeSIFeaturePack

Removes shared

library references

shared/common yes yes

remove-ear-

removeSIFeaturePack

Remove EAR file installableApps/ear yes yes

remove-resource-

environment-entry-

remove resource

environment

yes no

Extension point

name


Dependencies

Auto-

generated

removeSIFeaturePack provider entry

remove-resource-

environment-

provider-

referenceable-

removeSIFeaturePack

remove resource

environment

provider reference

yes no

remove-resource-

environment-

provider-custom-

property-

removeSIFeaturePack

remove resource

environment

provider custom

property

yes no

remove-resource-

environment-

provider-

removeSIFeaturePack

remove resource

environment

provider

yes no

remove-dataSource-

removeSIFeaturePack

Remove the

datasource

content/database yes yes

remove-jdbc-

provider-

removeSIFeaturePack

Remove the JDBC

provider


remove-j2c-auth-

removeSIFeaturePack

Remove J2C

authentication alias


remove-app-server-

library-references-

removeSIFeaturePack

Removes shared

library to server

classpath


remove-library-

removeSIFeaturePack

Removes shared

library


remove-app-server-

classloader-

removeSIFeaturePack

Remove appserver

classloader

yes no

remove-host-alias- remove host alias yes no

Page 35 of 50

Extension point

name


Dependencies

Auto-

generated

removeSIFeaturePack

remove-apps-

removeSIFeaturePack

runs Portal specific

remove tasks

yes no

remove-wcm-

removeSIFeaturePack

removes WCM

Libraries

content/wcm no yes

remove-portlets-

removeSIFeaturePack

remove portlets installableApps/por

tlets

no yes

uninstall-content-

xmlaccess-

removeSIFeaturePack

Runs XML uninstall

scripts

content/xmlaccess/

uninstall

no yes

delete-war-files-

removeSIFeaturePack

delete war files from

the

Profile_dir/installabl

eApps directory

installableApps/war no yes

delete-templates-

removeSIFeaturePack

Installs template Templates no yes

remove-pages-

removeSIFeaturePack

remove pages yes no

post-remove-PTF-

removeSIFeaturePack

Extension point run

at end of PAA

removal. suitable for

post-removal config

Yes no

Table 3 List of tasks specific for removing your PAA file

11 Including WCM libraries in a PAA file

There are a number of considerations to be taken into account when adding WCM libraries to a PAA

file. One such consideration is the size of the library. It is expected that some WCM content will be

transferred using PAA files, especially if the libraries in question are related to an application

included in the PAA file. However, PAA files should not be used to transfer large WCM libraries from

one server to another as in the case of staging to production, or if populating the server with large

quantities of test content. The reasons are two-fold. The first is the time it will take to export the

libraries and then import to the new server. For large libraries the import is quite time consuming, so

alternative methods such as syndicating the content between the servers, or performing a database

transfer would be much quicker alternatives. The second is related to a size limitation on a PAA file.

Prior to Java 7, the java.util.Zip class on which SI has a dependency, has a size limit of 32 bits.

The limitation means that a PAA file of close to 2GB in size will pose issues for the installer because it

will not be able to do verification checking on the PAA file, and ant might have issues extracting the

content to the files system.

For these reasons, it is recommended that if you want to distribute an application with an associated

WCM library, you should enclose the library along side the application in the PAA file. However, if

you are maintaining your systems, for example, transferring content from one server to another,

alternative methods for transferring the WCM data should be found.

Although SI provides the capability to delete and import newer versions of WCM libraries, the way

you organise your WCM content inside of the PAA file will determine how useful this functionality

will be for your deployment scenario. The PAA file format requires that a WCM library be enclosed in

a sub directory of the /rootdir/components/componentName/content/wcm directory.

For example /sample1/components/compSample1/content/wcm/lib1/554ee7f5.

However, for the WCM import, there can be multiple libraries included in this directory, depending

whether multiple libraries are exported at the same time.

The WCM detect functionality of SI retrieves the list of libraries included in a PAA file and does a

look-up on the Portal server to establish if the libraries already exist. If so, Boolean properties based

on the library names are generated in the rootdir/assemblyName.properties file in the

expanded PAA. If the properties file already exists, the properties are appended to the current

content, otherwise a new properties file is generated with the WCM properties included. The

properties are all set to ‘false’ by default, so that no libraries are replaced unless the user specifically

decides to do so. Setting the property for a library to true will ensure that the current library on the

server is deleted, and the new version of the library is imported in its place.

Page 37 of 50

The problem arises where there are multiple libraries included in the same sub directory of the

content/wcm directory. The import task for the WCM content takes as input the path to the

directory containing the files. For example,

/sample1/components/compSample1/content/wcm/lib1. It will then import all libraries

included in this directory sub tree. If you select to replace one of the libraries, all libraries in the

associated directory will be imported. Therefore, to replace any of the libraries on the system with a

newer version of one of the libraries, you will need to ensure that you replace all of the libraries

included in that directory sub tree. The WCM import functionality will try to overwrite the libraries

on the server with the ones found in the PAA file. If the libraries have different node structures, it

can pose inconsistency issues for the import causing it to fail.

If you would like to take advantage of the detect/delete functionality for WCM libraries included in

SI, the scenario outlined above could pose issues. However, if it makes sense to have all the libraries

removed and replaced with newer versions, for example, if the library you are replacing has

dependencies placed on it by other libraries, then this solution will suffice. Although it is important

to notify the user in the documentation for your PAA file that all libraries found by the WCM detect

functionality should be selected to be replaced, otherwise the import could fail.

If you want your libraries to be removed and replaced individually, then it is recommended that they

are placed in separate subdirectories in the content/wcm directory. For example,

/sample1/components/compSample1/content/wcm/lib1 or

/sample1/components/compSample1/content/wcm/lib2 etc.

This way there is a direct correlation between the properties in the assemblyName.properties

file and the individual libraries to be imported. If there is a requirement for a specific order to be

imposed on the import, then add a comma separated list of the library sub directories in an

order.properties file in the content/wcm directory. SI uses the presence of the

order.properties file to determine the order in which resources are to be deployed throughout

the PAA file.

NOTE: lib1 and lib2 are just sample directory names. SI imposes no restrictions on the names of

these directories.

12 Theme deployment

In terms of SI, a theme can have three different resource types associated with it. They include an

ear file containing the web module for the theme, WebDav content where skins, page layouts and

theme resources are stored, and finally an xmlaccess script to register the theme resources with

WebSphere Portal. The creation of theme artefacts is out of scope for this document, however,

developers of PAA content will require some knowledge of how SI handles these resources.

Therefore their deployment is discussed in some detail.

There is nothing special about the deployment of a theme ear file in terms of SI. That is, the ear file is

treated exactly like any other ear file. If placed in the installableApps/ear directory it will be

deployed to the server with any other ear files in the PAA file. However, uploading WebDav content

and registering the theme require a little more work.

12.1 Upload of content to the WebDav Store

Although WebSphere Portal supports multiple types of content to be uploaded to the WebDav store,

SI support for uploading such content is primarily targeted at deploying theme related content. Thus

this discussion will primarily centre on uploading theme related artefacts.

SI allows for content to be automatically uploaded to the WebDav store. The code automatically

generated during the install-PAA task is limited to the handling of theme related resources,

however, custom code can be added to a PAA file to handle additional resource types. The reason for

limiting the auto generated code to only handle theme related artefacts is due to the complexity of

other types and the ability to update/remove the content.

SI, when it installs WebDav content, writes directly to the WebDav file store. The content will not be

automatically registered with the Portal server, so an xmlaccess script to register the theme content

must be included in the PAA file to ensure that all files are accurately registered with the server.

After which a server restart is required to ensure that the Portal can load all the resources. An

example script illustrating how to register a theme that references items in the WebDav store is

included below.

According to the SI documentation, the content to be uploaded to the WebDav store will be

uploaded directly to the directory mapped to the type of functionality assigned to the resources in

the PAA file i.e. files in the content/WebDav/theme directory will be uploaded to dav:fs-

type1/themes/, if there is a root directory contained in the .zip file for the content. If no root

directory exists, then the name of the .zip file without the .zip suffix will be used as the context root.

Page 39 of 50

For example a theme with a context root of myTheme will have a targetURI of dav:fs-

type1/themes/myTheme. Therefore, be careful if adding custom code to upload a file. The upload

task places the content of the zip file in the directory set in the targetURI which might be

problematic if there is no root directory in the .zip file, especially when you want to have the content

deleted.

The structure that you apply to your WebDav content will determine how difficult it will be to update

the deployed files in the WebDav store in the future through the SI. The reason is primarily due to

the webdav-deploy-zip-file task and how it handles the content. This task is the method used

by SI to interact with the WebDav store.

To ensure that the content can be easily updated or deleted in the future, separate your WebDav

content out into its own directory. That is, upload to a subdirectory of the directory to which you are

deploying the content, and not add it to the top level directory in the WebDav store. For example, a

theme that should be uploaded to the Portal WebDav file store. You should ensure that when the

theme is uploaded to the fs1/types/themes/ directory that all content is enclosed in a

subdirectory relating to that theme.

For the same reason it would be better to create your own theme artifacts rather than modifying

existing files. SI sets the UpdateMode parameter of the webdav-deploy-zip-file task to

merge. It means that the content of the zip file will be copied to the target directory. Existing files of

the same name will be overwritten but any additional files in the directory will not be modified.

However, there are no facilities to back up the existing content, so replacing with a newer version

means that if the PAA file is uninstalled with the WebDav content deleted, the files that are

contained in the zip will be removed, and there will be no way to restore the previous version of the

file. The default setting of the UpdateMode property is replace which will replace the current

WebDav directory set in the targetURI parameter with what is in the .zip file. All other content of

that directory will be deleted. Therefore, this setting is not recommended.

12.2 Deleting WebDav content

It is now possible to remove the content from the WebDav store programmatically, however, SI does

not generate code to remove any WebDav content. This functionality can be added using custom

code, see examples of how it can be achieved below.

In the task below, the first example has a parameter named TargetURI with a value of dav:fs-

type1/themes/. And the second example contains a TargetURI of dav:fs-type1/layout-

templates/milestone/. The difference between the two zip files specified in both is that the

first example has a root directory, and the second does not. Therefore, you should take care when

deleting that the full path can be made up out of the TargetURI and the paths in the zip file.

The following example task illustrates how to remove content from the WebDav store:

<?xml version="1.0" encoding="UTF-8"?>

<target name="action-post-remove-PTF-removeSIFeaturePack-

components/testTheme" unless="isSecondNode">

<antcall target="WebDav -deploy-zip-file">

<param name="TargetURI" value="dav:fs-type1/themes/"/>

<param name="ZipFilePath"

value="${Components/testThemeHome}/content/WebDav /themes/newzip.zip"/>

<param name="UpdateMode" value="delete"/>

<param name="VirtualPortalContext" value="${VirtualPortalContext}"/>

<param name="VirtualPortalHostName" value="${VirtualPortalHostName}"/>

<param name="WasPassword" value="${WasPassword}"/>

<param name="WasUserid" value="${WasUserid}"/>

<param name="PortalAdminId" value="${PortalAdminIdShort}"/>

<param name="PortalAdminPwd" value="${PortalAdminPwd}"/>

</antcall>

<antcall target="WebDav -deploy-zip-file">

<param name="TargetURI" value="dav:fs-type1/layout-

templates/milestone/"/>

<param name="ZipFilePath"

value="${Components/testThemeHome}/content/WebDav /layout-

templates/milestone.zip"/>

<param name="UpdateMode" value="delete"/>

<param name="VirtualPortalContext" value="${VirtualPortalContext}"/>

<param name="VirtualPortalHostName" value="${VirtualPortalHostName}"/>

<param name="WasPassword" value="${WasPassword}"/>

<param name="WasUserid" value="${WasUserid}"/>

<param name="PortalAdminId" value="${PortalAdminIdShort}"/>

Page 41 of 50

<param name="PortalAdminPwd" value="${PortalAdminPwd}"/>

</antcall>

</target>

Parameters:

TargetURI: target location in WebDav store for content

ZipFilePath: Path to zip file containing the content to be uploaded

UpdateMode: values can be delete, merge or replace

VirtualPortalContext: points to the context for a virtual Portal, can be left blank

VirtualPortalHostName: points to the hostname for a virtual Portal, can be left blank

WasPassword: WAS password

WasUserid: WAS userId

PortalAdminId: administrator id for Portal user

PortalAdminPwd: Portal administrator password

NOTE: The ZipFilePath parameter is still necessary when deleting content from the WebDav

store. The task will remove any files found in the zip file from the store, rather than delete

directories/files pointed to by the TargetURI.

12.3 Registering a theme with WebSphere Portal

After a theme web module has been deployed to WebSphere Portal, and the theme WebDav content

uploaded to the WebDav store, there is one final step required to enable the theme in WebSphere

Portal. An xmlaccess script must be invoked to configure any theme resources on the server. The SI

does not automatically generate an xmlaccess script to configure theme resources so a custom script

must be supplied by the developer. However, if the script is placed in the

components/compName/content/xmlaccess/install directory, it will be run automatically

during the deploy-PAA command.

The following is a script taken from the government industry template for WebSphere Portal sample

application which illustrates how a theme, referencing WebDav content, can be registered with

WebSphere Portal:

<?xml version="1.0" encoding="UTF-8"?>

<request build="wp8001_194_01" type="update" version="8.0.0.1"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="PortalConfig_8.0.0.xsd">

<Portal action="locate">

<skin action="update" active="true" context-root="/Government_Theme"

default="false" domain="rel" objectid="ZK_J9HCH080JOU8D0I7JR46EU0JF3"

resourceroot="Hidden" type="default" uniquename="GovSkin">

<localedata locale="en">

<title>Government Skin</title>

<description/>

</localedata>

<parameter name="com.ibm.Portal.skintype" type="string"

update="set"><![CDATA[template]]></parameter>

<parameter name="com.ibm.Portal.friendly.name" type="string"

update="set"><![CDATA[GovSkin]]></parameter>

<parameter name="com.ibm.Portal.skin.template.ref" type="string"

update="set"><![CDATA[dav:fs-type1/skins/GovSkin/]]></parameter>

</skin>

<theme action="update" active="true" context-root="/Government_Theme"

default="false" domain="rel" objectid="ZJ_J9HCH080JOU8D0I7JR46EU0D22"

resourceroot="dynamicSpots" uniquename="GovernmentTheme">

<localedata locale="en">

<title>Government Theme</title>

</localedata>

<allowed-skin skin="ZK_J9HCH080JOU8D0I7JR46EU0JF3" update="set"/>

<parameter name="com.ibm.Portal.friendly.name" type="string"

update="set"><![CDATA[GovernmentTheme]]></parameter>

<parameter name="com.ibm.Portal.theme.dnd.sources" type="string"

update="set"><![CDATA[ibmDndColumn:com.ibm.pb.dnd.layout.LayoutColumnSo

Page 43 of 50

urce:vertical,ibmDndRow:com.ibm.pb.dnd.layout.LayoutRowSource:horizonta

l]]></parameter>

<parameter name="com.ibm.Portal.layout.template.href" type="string"

update="set"><![CDATA[dav:fs-type1/themes/government.theme/layout-

templates/2ColumnEqual/]]></parameter>

<parameter name="com.ibm.Portal.themetype" type="string"

update="set"><![CDATA[CSA2]]></parameter>

<parameter name="com.ibm.Portal.theme.aggregationmodes" type="string"

update="set"><![CDATA[ssa]]></parameter>

<parameter name="com.ibm.Portal.theme.template.ref" type="string"

update="set"><![CDATA[dav:fs-

type1/themes/government.theme/]]></parameter>

<parameter name="resourceaggregation.profile" type="string"

update="set"><![CDATA[profiles/profile_gov_deferred.json]]></parameter>

</theme>

</Portal>

<status element="all" result="ok"/>

</request>

13 PAA file life cycle

One of the most common discussions that the SI development team has with new PAA developers

and customers, centres on the expected lifecycle of a PAA file; for example, how to maintain their

applications deployed using PAA files into the future. The answer is not a simple one because it

depends on what functionality is required and how often changes are made to the PAA content.

If you are constantly updating your PAA content or releasing a PAA-based application to a third party

on a periodic basis, the strategy might be different. For the first scenario, the changes are usually

incremental and require the full deployment. Whereas for the second scenario, the changes often

require an upgrade step for a new feature or a patch to fix a defect.

13.1 Two step deployment process

When you deploy a PAA file, there are two steps to the deployment. The first is the installation step

that expands the PAA file under the PAA offering directory, for example

/opt/IBM/WebSphere/wp_profile/PAA, and registers the assembly with its components to

the ConfigEngine. Any code generation is also performed at this stage. The second step is to run the

deployment tasks registered with the ConfigEngine as part of the installation, which deploys the

resources found in the PAA file.

Similarly in terms of the uninstall, there are also two distinct steps. The first is to remove the

resources from the Portal server and the second is to uninstall them from the ConfigEngine.

Throughout this document when install and uninstall are mentioned, it refers to the registration of

PAA files with the ConfigEngine. Where the terms deploy and remove are used, they refer to the

deployment and removal of resources from the Portal server.

Whether you use the command line or the Configuration Wizard to install or deploy your PAA file,

there are 2 steps involved. However, when you use the Configuration Wizard, an additional ‘typical’

install or uninstall scenario is included that wraps both tasks. This scenario was added to handle the

deployment of simple PAA files for which there is no optional content. For more control over which

resources are installed, select the ‘advanced’ option.

NOTE: For Portal 8.5 both the command line and config wizard deployment methods are available.

Page 45 of 50

13.2 Enabling PAA file for updates

Since the release of WebSphere Portal 8.5, it is possible to enable a PAA file to update a previously

installed version. The expected use case scenario for this functionality is where there are a number

of updates required to upgrade a version of an application. The Update task allows you to update

the existing application rather than to replace the entire application. The PAA file itself would also

function as a regular PAA file that if deployed on a clean server would deploy as normal. However, if

an existing version exists on the server, then the update scenario would be called into play.

The install-PAA-update task will back-up the existing version of the PAA file to the

wp_profile/PAA/backup directory. It will then uninstall the existing PAA file from the

ConfigEngine and all resources from the older version are deleted. After this step is complete the

newer version will be installed. The deployment can then proceed as normal; however, the PAA file

will be marked in the registry as an update so only the extension points with the

updateSIFeaturePack suffix will be invoked during the deployment.

The SI does not auto generate code in this situation. Leaving any updates up to the developer to

generate using custom code. The tasks from the previous version of the PAA file are still present and

can be invoked by the custom tasks.

Rolling back the changes in this scenario is also possible. The resources from the backup PAA file can

be restored and the changes undone from the server by redeploying the resources. In this scenario,

the tasks with the rollbackSIFeaturePack suffix are invoked. It is completely up to the

developer to script the removal and redeployment of artefacts. However, the existing set of tasks for

the PAA deployment will be available to be invoked by the custom code.

13.3 Overwriting the existing PAA file

There are some situations where the install-PAA-update approach will not work for the type of

scenario that a developer is trying to implement. For example, new resources were added and the

code generation is not available. These new resources are not covered by existing tasks and must be

handled by custom code.

At times it might be necessary to replace the existing PAA file and redeploy the full application. In

this scenario, the PAA resources will not be removed from the Portal server using the remove-PAA

task because they might break the configuration of other applications. Therefore, if deploying a new

PAA file over a previously deployed version, the following steps are recommended:

1. Uninstall the PAA file either through the uninstall-PAA task or through the uninstall

add-ons workflow of the configuration wizard.

NOTE: If you use the Configuration Wizard, uninstall but do not remove the content. Therefore,

select the advanced setting. Otherwise the resources will also be removed from Portal. The

uninstall step is necessary to ensure that existing registered tasks are removed from the

registry.

2. Delete the PAA file content from the PAA offering directory; for example,

wp_profile/PAA/sample1. Delete the PAA file content either through the delete-PAA

task or through the file explorer functionality of your operating system.

NOTE: Deleting the content is necessary because there might be a mismatch between the

resources of both PAA files. Deleting the content ensures that all auto generated code has been

removed. If the SI detects an extension point implementation task, it will move on to the next

resource type. Therefore, the tasks from the previous PAA file could pose issues because they

might not cover all of the resources for the new version.

3. Install and deploy the new PAA file.

At times there will be situations where certain resources must be removed during the deployment of

the new version of the PAA file because they cannot be easily overwritten or updated. In this

situation, add a custom task to the PAA file that can be called outside of the SI. For example, this task

could be called after the new version is installed, but before the deployment.

NOTE: Any task installed with a PAA file can be called directly through the ConfigEngine. If the task

does not match the extension point naming scheme, the task will not run during the deployment or

removal of content.

An alternative option would be to implement one or more of the remove applySIFeaturePack

extension points that will be invoked during the deployment phase. Read the section on extension

point best practices for more information.

Page 47 of 50

14 Deploying PAA files to a clustered environment

When you install a PAA file to a Portal cluster environment, there are a few important things to be

aware of. Many of the resources included in a PAA file will replicate across the nodes. However,

there are certain resource types that cannot be replicated; therefore, it is necessary to install and

deploy the PAA file on each node in the cluster. These resources include shared jar files that must be

added to the class-path, custom classes required to support personalisation rules, and help plugins

that are found in IBM released PAA files for Portal 8.5. In these cases, it is necessary to have these

files local to each server so that they can be picked up by the class-path.

If a PAA file does not contain one or more of the named types, it might not be necessary to deploy

the PAA file on each node. However, it is recommended to do so unless you are sure that this will not

have any adverse effects on the deployed application.

Deploying a PAA file to a secondary node will take less time than for the primary node. The SI only

deploys resources that cannot replicate during synchronisation. Any extension point implementation

ant task, whether it is a SI generated task or a custom task provided in the PAA file, will only run on a

secondary node if it does not have an unless=”isSecondNode” attribute on the target element.

Therefore, any custom tasks that a developer wants not to be run on a secondary node should also

include this attribute. See the section on custom code for more details of how to add custom tasks.

Currently, it is not possible to remotely deploy a PAA file to a secondary node. The ConfigEngine on

each node is a separate instance. There is no mechanism to remotely activate the ConfigEngine to

install or deploy a PAA file on each secondary node.

14.1 Advantages of running SI with Portal stopped.

When the SI detects that the server is stopped during the deploy-PAA task, it will automatically start

it because it is necessary to verify the Portal administrative credentials. However, before you start

the server, it will run the tasks for building the SI shared library. Therefore if there are any shared jar

files included in the shared/app directory of a component in the PAA file, they will be automatically

loaded on the class-path when the server starts. This process ensures that any applications that

depend on these jar files can be started automatically by SI.

This process also resolves an issue where a secondary node server fails to start when an application

has replicated from a primary node but the jar files are missing from the server class-path. In this

case, the server might fail to start due to class not found errors. Allowing SI to deploy to a stopped

Portal server alleviates this issue because the shared.app.jar file is already generated.

You might still be required to restart the server after the deployment has completed on the primary

node because some of the resources will not be activated until the server reloads the configuration.

For example, custom code is used to generate resource environment provider custom properties.

These custom properties might not be picked up by the server configuration until the server has

been restarted.

14.2 Reducing deployment times on a cluster

Since CF08 for 8.0.0.1 and 8.5 Gold, SI can deploy to a cluster with auto synchronisation turned off.

The SI will check the auto sync settings before attempting to wait for the applications to sync across

the nodes. If the value of the setting is set to off, SI will proceed with the deployment as if it was on a

standalone server. In other words, it will not wait for synchronisation to complete before proceeding

with the deployment.

Running a PAA deployment with the auto sync functionality turned off is similar to deploying a

cumulative fix to a node in a Portal cluster. The administrator of the cluster will have to manually

synchronise the nodes after the deployment has completed because SI does not do this

automatically. In addition, the deployment of the PAA file will also need to be separately applied to

each node in the cluster, to ensure that all dependent resources exist on the secondary nodes.

One issue that sometimes arises when you perform a PAA deployment on a cluster with auto sync

enabled, is an application that has failed to fully synchronise across nodes will not be started if you

set active=”true” on the web-app element for the web module of the deployment xmlaccess

script. The xmlaccess tool does not wait for the sync to complete after it has finished the deployment

of the web module and directly attempts to start the application. If the sync has not completed,

possibly due to a slow network or a large war file has not fully replicated, the application will not be

started.

To avoid this situation, activate the application separately from the deployment script. SI now adds a

separate extension point to start the portlet web modules. The extension point start-portlet-

application-applySIFeaturePack was added to start the applications that were deployed

with the deploy-portlet-applySIFeaturePack extension point. On a clustered environment,

it checks the auto synchronization status before it activates the applications. In this way, the

applications are started by the deploy-PAA task.

Page 49 of 50

If you are regularly deploying to a cluster with auto synchronization turned off and the deployment

times are a concern, then it is recommended that the xmlaccess scripts do not activate the portlets

automatically. Where auto sync is turned off, the xmlaccess tool attempts to start the application,

but times out after a certain length of time, because it cannot start an application that has not fully

synchronized. To prevent SI from trying to activate the portlets for war files in the

rootDir/components/componentName/installableApps/portlets directory, you can

overwrite the action-start-portlet-applications-components/componentName

target for your component. Add an empty ant target to ensure that no code is generated during the

install-PAA task to start the portlets. For example:

<target name=”action-start-portlet-applications-

components/componentName”/>

Adding this task to a file in the config/includes directory of the component will ensure that SI will not

start the portlets for that component.

If you are using a custom xmlaccess script to deploy the portlets and placed your portlet war files in

the components/componentName/installableApps/war directory to ensure default scripts

are not generated during the deployment, you must add active=”false” to the web-app and

portlet elements for the deployment in the xmlaccess script. It ensures that the portlets are

deployed and referenceable by the script, but the applications will not attempt to start. As the

timeout for xmlaccess tool in starting the application can be quite large, it can save time during a

deployment with many war files.

Once the deployment has completed, the web modules in the PAA file can be activated separately.

Use the WebSphere application server administration console or, since Portal 8.0.0.1 CF14 and 8.5

CF03, the following SI command can be used to activate the web modules:

./ConfigEngine.sh activate-PAA-portlets -

DassemblyList=assemblyName1,assemblyName2, …

The assemblyList parameter is a comma separated list of PAA assemblies containing portlet web

modules that you want to start.

Starting the applications outside of the PAA deployment process can be useful if you are deploying a

large application with multiple PAA files, and only want to turn on synchronization when the

deployment work has completed.

The activate-PAA-portlets task starts portlet war files found in both the

installableApps/portlets and installableApps/war directories of a component. Any

portlet web modules found in these directories are added to an activate-webmodules.xml

script generated at install time. These scripts are then invoked by the activate-PAA-portlets

task to start the portlets.

For this task to be effective, the manual synchronization of the nodes must be completed and the

auto synchronization turned on, before you run this task.

15 Acknowledgements

I would like to thank the following people for agreeing to review the document and for providing

helpful feedback and suggestions on how the content could be improved:

Una Phillips, Jerh O’Connor, Stefan Koch and Megan Crouch.

Date post:	13-Mar-2018
Category:	Documents
Upload:	vanbao
View:	236 times
Download:	4 times

PAA file Creation Best Practices - IBM DeveloperWorks · PDF filePAA file Creation Best...

Documents