Installing Solution Installer To Websphere Portal

Transcript

IBM WebSphere Portal Solution Installer Developer Guide 1.2 Version 1 Release 3 1. INTRODUCTION..................................................................................................................4 1.1 INTRODUCING SOLUTION INSTALLER...........................................................................................4 1.2 ABOUT THIS DOCUMENT............................................................................................................4 1.3 WHO SHOULD USE THIS DOCUMENT.............................................................................................5 2. TERMINOLOGY..................................................................................................................6 3. THE PORTAL APPLICATION ARCHIVE (PAA) ..................................................................7 3.1. SDD.XML FILES …................................................................................................................8 3.2. PAA FILE STRUCTURE …...................................................................................................... 9 3.2.1. ROOT DIRECTORY .............................................................................................................9 3.2.2 DOCUMENTATION….............................................................................................................9 3.2.3 COMPONENTS …..............................................................................................................10 3.2.3.1 CONFIG.......................................................................................................................11 3.2.3.2 CONTENT......................................................................................................................11 3.2.3.3 INSTALLABLEAPPS..........................................................................................................14 3.2.3.4 SHARED.......................................................................................................................16 3.2.3.5 TEMPLATE....................................................................................................................17 3.2.3.6 VERSION.....................................................................................................................18 3.3 UNIQUE NAME GENERATION FOR PORTLETS.................................................................................19 3.4 PROPERTY FILES.................................................................................................................20 3.4.1 PROPERTIES PROVIDED BY DEVELOPERS..................................................................................20 3.4.2 PROPERTIES ADDED TO THE PAA BY SOLUTION INSTALLER.........................................................22 3.5 ORDER OF INSTALLATION OF SCRIPTS AND ARTIFACTS.....................................................................22 4. ADDING CUSTOM CODE TO A PAA FILE.........................................................................24 4.1 WHAT IS CUSTOM CODE.........................................................................................................24 4.2 WHERE TO PLACE CUSTOM CODE IN THE PAA FILE......................................................................25 4.3 NAMING CUSTOM CODE FILES..................................................................................................25 4.4 COMPONENT LEVEL SDD.XML FILE........................................................................................26 5. SOLUTION INSTALLER SAMPLE BOOTSTRAP FILES...................................................28 5.1 CONTENT OF THE SOLUTIONINSTALLER/ DOCUMENTATION/BOOTSTRAP DIRECTORY.................................28 5.2 CONFIGURING AND CUSTOMIZING THE BOOTSTRAP FILES FOR AN APPLICATION BY DEVELOPERS.................29 5.3 RUNNING THE BOOTSTRAP FILES BY USERS.................................................................................30 5.4 EXAMPLE...........................................................................................................................30 6 TROUBLESHOOTING FOR DEVELOPERS.......................................................................32 6.1 NAMING OF COMPONENTS.......................................................................................................32 6.2 DATABASES.........................................................................................................................32 6.3 TEMPLATES.........................................................................................................................32 6.4 ERROR ENCOUNTERED WHEN RUNNING XMLACCESS SCRIPTS FOR CREATING USER ACCOUNT CONFIGURATIONS. …..........................................................................................................................................32 APPENDIX A: DATABASE PROPERTIES............................................................................34 APPENDIX B. CONFIGENGINE EXTENSION POINTS FOR SOLUTION INSTALLER........38 APPENDIX C: THE ASSEMBLY LEVEL SDD.XML FILE.......................................................40 APPENDIX D: THE COMPONENT LEVEL SDD.XML FILE...................................................43 1. Introduction 1.1 Introducing Solution Installer The IBM® WebSphere® Portal Solution installer is a utility for installing, uninstalling and updating solutions or applications to a WebSphere Portal instance. The basis of the Solution Installer is a standard format for application distribution, the Portal Application Archive (PAA) format. This format is described in detail in Chapter 3. Developers, who want to install their applications with the Solution Installer, should refer to this section. The Solution Installer is currently a command line application that allows users to install and deploy complex applications to WebSphere Portal. It is an ANT based application that is invoked through the ConfigEngine. Read the user guide for full details on how to install the Solution Installer. The PAA file is a formatted zip file. It contains a mixture of deployment ANT tasks and resources that need to be deployed to portal. By placing resources in certain locations within this PAA directory structure, the Solution Installer can create default code to complete the installation. It is also possible for developers to supply their own code to both overwrite the default code or to install resources where Solution Installer is unable to create the required code. In addition to the ANT tasks and the resources, there is another important required piece. This piece ensures that the PAA files can be first registered with the ConfigEngine and then deployed to WebSphere Portal. This piece is the sdd.xml files. These files contain information about the application, including: - Information about the main application - Any components included in your PAA file - Any tasks to overwrite the Solution Installer generated code - Any additional resource types the Solution Installer does not directly cover 1.2 About this document This document provides instructions for the following items: • Basic troubleshooting • Preparing solutions to be installed to WebSphere Portal using the Solution Installer Knowledge of IBM WebSphere Portal and Portal Applications is assumed in this document. 1.3 Who should use this document This document is intended for Portal Solution Developers who want to prepare their solutions using the Solution Installer. 2. Terminology ConfigEngine: WebSphere Portal configuration framework Component: A ConfigEngine term relating to a grouping of resources for installation Assembly: ConfigEngine grouping of components Offering: A ConfigEngine term for a grouping of assemblies, highest level grouping under the ConfigEngine framework. PAA: Portal Application Archive Extension point: Provides the ConfigEngine with knowledge of the type of functionality being installed. For example, using the create-ear extension point informs ConfigEngine that an ear file is being installed. The ConfigEngine groups resources to be deployed. Sdd.xml: Software Definition Descriptor file. These files contain information about the application to install. They are found at all levels, including the component, assembly and offering levels. elements: Smallest configurable unit, added to component level sdd.xml files to inform ConfigEngine of available extension points that are registered for the component. 3. The Portal Application Archive (PAA) When deploying large applications with many resource types, there can be many required steps to install and configure each resource. IBM® WebSphere® Portal Solution Installer (referred to as the Solution Installer throughout) automates many of these deployment tasks. The Solution Installer requires a Portal Application Archive (PAA) file. The PAA file describes how to install the application and provides the installable artifacts. This chapter provides an overview for solution developers who want to install their solutions with the Solution Installer. The PAA format can handle deployments ranging from applications with a small number of configuration steps to large scale enterprise solutions. The directory structure of the PAA file is very important to the Solution Installer when determining how to install a specific artifact. For example, how to handle shared library files. In addition, the software definition descriptor (sdd.xml) files also play a significant role in determining the installation steps. All required extension points must be specified in an sdd.xml file that is local to the component. The PAA format can reduce the work required to create a deployable solution. Many deployment tasks can use a default configuration found in the Solution Installer. For complex applications, additional work is required to provide custom installation features. Using the PAA format in conjunction with the Solution Installer can reduce the production time for creating a deployable solution for your application. A sample PAA file that demonstrates the overall structure is included with the Solution Installer. This sample PAA file is discussed in detail throughout the document. When the sample file does not demonstrate functionality, further descriptions are provided. 3.1. Sdd.xml Files The sdd.xml files perform a number of different roles in the PAA file structure. They allow the developer to control, using ConfigEngine extension points, how an application is installed. They also inform the ConfigEngine of the type of installation to be processed. The installation type also determines, in terms of the ConfigEngine, where the deployable files are stored after registration with the ConfigEngine. The ConfigEngine takes a granular approach to the installation and deployment of an application. The sdd.xml file controls the granularity to the ConfigEngine. There are three different levels of installation. 1. The first is the offering level. Large applications such as WebSphere Portal are offering level deployments. 2. The next installation level is the assembly. An assembly is usually a group of applications that can stand alone or form the basis of a much larger application. An example of an assembly is the 'ap' or 'base' directories under WebSphere Portal. 3. The finest level of granularity is the component. A component can be a complete application or can be one of many small applications that make up a larger application. An assembly is made up of one or more components and an offering is made up of one or more assemblies. The Solution Installer includes all the PAA files in a high-level PAA offering. When the Solution Installer is first installed, this directory structure is created. Any offering setup details are automatically processed. This approach makes it easier to manage the installation of the different components. The one hierarchy is especially effective when components are shared across a number of PAA distributions. Each PAA file is treated as a separate assembly. The top level sdd.xml contains installation information for the ConfigEngine. This information relates to the assembly and its components. Each PAA file requires an assembly level sdd.xml file. Otherwise, the Solution Installer lacks the information to register the PAA file with the ConfigEngine. A PAA file containing an update has the same assembly name in its sdd.xml file. The Solution Installer checks that the assembly exists before adding each new component or update to the current assembly. Refer to Appendix C for information on how to create and edit an assembly level sdd.xml file. The assembly can be made up of one or more components. Each component requires a component level sdd.xml file. The number of components depends on how the developer structures the application. Every artifact can potentially be included in a single component. However, this approach is not the most practical. You might want to separate larger applications into multiple components containing related artifacts to facilitate reuse. A component can be required by multiple PAA distributions. This approach allows it to be reused with little additional work for the developer. In terms of creating a PAA file, the inclusion of the component level sdd.xml file is optional. Solution Installer is able to generate the sdd.xml file automatically. However, if the developer needs to add additional code to perform configuration tasks, the sdd.xml file should be created for the component. Refer to appendix D for information on how to create and edit a component level sdd.xml file. 3.2. PAA file structure The PAA file is a customized zip file. It contains an application that is installed on WebSphere Portal. The following is an outline of the structure of a basic PAA file. 3.2.1. Root directory The root directory consists of a single directory. It is recommended that the directory have the same name as the PAA file. If the PAA file is named samplePaa.paa, the root directory contains a single directory called samplePaa. The name of the top level directory must match the name of the assembly as specified in the assembly level sdd.xml file. The top-level directory must contain the components and documentation subdirectories and an assembly level sdd.xml file. sample_paa.paa file, there is a top-level sample_paa directory. It is the root directory of the PAA content and it contains two directories, documentation and components and an sdd.xml file. The sdd.xml file has a number of roles: If you open the • It informs the ConfigEngine that it is an assembly of components. • It provides the ConfigEngine the list of components and their locations within the directory structure. • It points to the sdd.xml files for each component so that the installation functionality can process each individual components. 3.2.2 Documentation The developers should place all documentation and related artifacts for the entire application in the documentation directory. The PAA package developer can organize the documentation directory structure in a way that works for their application. The Solution Installer is not concerned with how the content is structured. The only action is to copy the content to the correct place in the expanded archive under the PAA offering directory. For example, c:\ibm\websphere\paa\sample_paa\documentation\*.*. Note: This directory is the only recommended place for any documentation related to the application. There is currently no provision within the PAA format to provide documentation at the component level. 3.2.3 Components The components directory and its sub directories are where all deployable artifacts must be stored. If you examine the content of the components directory in the sample PAA file, there is just one component listed, componentN. There is always at least one component contained in a PAA file. However, there is currently no upper limit on the number of components that you can include. The number of components available depend on how you want to organize your deployable artifacts. Potentially all the deployable artifacts can be stored in a single component. However, if there are multiple stand-alone applications in the PAA file, a component is recommended for each application. If you want to reuse components across PAA file distributions, then separate the artifacts into multiple components. There is no limit on the type of artifacts that can be contained within a specific component. However, there is a limitation on where the artifact can be placed within the component directory sub tree structure. These restrictions are discussed in the subsections. A component can include artifacts and configuration details for an entire application. It can also contain only artifacts to a certain part of the application. For example, you could include all your theme related artifacts in one component. Then you can include your XML access scripts to create the pages for your site in another. The Solution Installer is not concerned with your approach. It processes each component based on the dependencies listed in the sdd.xml file. Using the sample_paa example, open the ComponentN directory, which is a sub directory of components. The component level sdd.xml file and the following directories are present: 1. config 2. content 3. installableApps 4. shared 5. template 6. version The intended content of each of these directories is discussed in the following subsections. 3.2.3.1 config The config directory contains two subdirectories: includes and templates. Both subdirectories are important if you add custom tasks to aid the installation or configuration of the component enclosed artifacts. The config/includes directory is where the ConfigEngine looks for tasks that implement the extension points that are listed in the component level sdd.xml file. The name of the xml file containing ANT tasks is not hard coded into the system. The ConfigEngine looks in this directory for any .xml files. The ANT tasks do not have to be stored in a single file. They can be spread out over multiple files that the ConfigEngine picks up. The config/templates directory is used for storing any additional non-ConfigEngine script files. The ANT tasks might rely on these files to perform configuration tasks. If you are deploying a WAR file and want to perform portlet configuration tasks, place the XML scripts in this directory. You can reference the WAR file in the profile_dir/installableApps directory. You can copy it there automatically with your custom task implementation. The Solution Installer does not automatically run the scripts stored in this directory. Instead, the developer must add custom tasks to call these scripts. 3.2.3.2 content Store IBM Lotus® Web Content Management libraries and other content related artifacts in the content directory. The component/content directory contains the following sub directories: jcr: contains JCR related artifacts. It contains a directory structure of nodes. Each entry is either a file or a directory, with associated metadata (title, last modified, permissions). jsp: contains any JSP files that you want to package as part of your application. Place Web Content Manger JSP files in the jsp/wcm directory. The Solution Installer copies all files and folders to the relevant location on the server: ${WasUserHome}/installedApps/$ {NodeName}/WCM_EXTENSION.ear/wp.wcmextension.war/jsp/wcm/content Note: The Solution Installer does not perform any default tasks to handle JSP content, excluding those located in the jsp/wcm directory. A developer needs to provide a custom task to ensure this content is copied to the correct location. wcm: contains web content libraries. Each wcm subdirectory represents a separate web content library. Web content libraries are separated into their own directory due to the process required to install them using the default functionality. webdav: This directory and its subdirectory contain artifacts that need to be uploaded to the WebDAV file store. There are 4 possible subdirectories. Each one is named to reflect the type of functionality provided in the files. The options are the following subdirectories: • iwidgets: Place zip files containing iWidgets that need to be uploaded to the WebDAV file store and registered with WebSphere Portal. The Solution nstaller automatically uploads any files found in this directory to the ‘dav:fs-type1/iwidgets/’ directory. However, additional work is necessary to have the iWidget definitions registered with WebSphere Portal. To register the definition files with WebSphere Portal, you must include a properties file called iwidgets.properties in the iwidgets directory. This file will contain a property representing each zip archive containing iwidgets found in the directory. The name of the property is same as the name of the zip file. The value will contain a ',' separated list of file names of definition files that are contained in the named file. • layout-templates: Place layout-templates zip files in this directory. When the Solution Installer detects these files, code is generated to automatically upload the content to the ‘dav:fs-type1/layout-templates/’ directory. • Skins: Place any zip files that contain skins that are not specific to a theme in this directory. The content is automatically uploaded to the 'dav:fs-type1/skins/' directory. • Themes: Place zip files containing static theme content in this directory. They are automatically uploaded to the ‘dav:fs-type1/themes/’ directory. Note: If your theme contains dynamic content, these should be included in a WAR file that is deployed to the underlying application server. They should be available at runtime. An example of dynamic content is JSP files. The Solution Installer uploads only WebDAV content using the ‘dav:fs-type1/*.* webdav entry point. The themes and skins are not automatically available through the themelist or skinlist entry points. An XMLAccess script needs to be created to register the resources with WebSphere Portal. An example script is included in the SolutionInstaller/documentation/sample/scripts directory. The context root, where the content is installed, is set in one of the following ways: • If there is a root directory within the compress file, then it is appended to the TargetURI. For example, a compress file in the componentName/content/webdav/themes directory with a root directory of sample would result in a TargetURI ‘dav:fs-type1/themes/sample/’. • If there is no root directory contained in the compress file, then the name of the compress file minus the ‘.zip’ suffix is used. For example, a compress file with the name sample1.zip would result in the TargetURI ‘dav:fs-type1/themes/sample1/’. The upload task to the WebDAV file system is set to replace the current directory with the new content. However, the Solution Installer alters this functionality to merge the content instead. The reason is that when the UpdateMode parameter is set to ‘replace’, the upload replaces all content found at the given TargetURI. For example, if you are uploading a .zip file to dav:fstype1/themes/, it does not just replace the equivalent content that is stored in the directory. It replaces everything in this directory. Therefore, it was decided that when using Solution Installer to handle this functionality, it would be better to have the content set to merge with the existing content. If you do require that the UpdateMode is set to 'replace', then you need to add a properties file to the directory where the functionality is required. For example if you want to replace all the themes, you would place the file webdav.properties in the componentName/content/webdav/themes directory. There is just one property available in this file: webdav.replace=list_of_.zip_file_names The value of the 'webdav.replace' property is a comma separated list of files. This list tells the Solution Installer which files must be uploaded using the replace update mode. xmlaccess: This directory contains any component level XML access scripts. This directory differs from the component/config/templates directory called by the custom ANT tasks. These are any scripts that need to be run by default. This directory has two subdirectories to aid in the distinction between install and uninstall scripts. The scripts required for installation reside in the /content/xmlaccess/install directory. The uninstall scripts are placed in the /content/xmlaccess/uninstall directory. The type of scripts in the component/content/xmlaccess directory subtree can include scripts to deploy a theme to Portal. The EAR file needs to already be installed to the application server. Scripts to configure theme policies, create a set of users and/or groups, or a credential slot in the credential vault are additional examples of scripts that could be placed in this directory. The Solution Installer automatically runs the scripts in this directory depending on the functionality invoked. database: This directory contains any database scripts for creating tables and prepopulating the tables with any relevant data. Solution Installer can generate ANT tasks to create the relevant configuration settings on the underlying WebSphere Application Server. Database properties are configured as per appendix A. The PAA developer should include default properties in a file called default.properties in the content/database directory to make things easier for the user. There are two directories: install and uninstall in the database directory in the PAA file. The PAA file developer should place the following scripts in these directories • .ddl and .sql scripts for creating and populating tables in the install directory • .ddl and .sql scripts for dropping tables in the uninstall directory • Where multiple scripts are required an order.properties file should be included in the appropriate directory to specify the correct order for installation pzn: This directory contains Personalization (PZN) related artifacts, such as JAR files containing business rules and personalization .nodes files. composite: This directory contains any composite applications that need to be shipped within the PAA application. Each subsequent subdirectory represents a composite application. 3.2.3.3 installableApps The installableApps directory contains any artifacts that need to be installed to WebSphere Portal or the application server. The Solution Installer copies the relevant files to the profile_dir/installableApps directory automatically. The artifacts are stored in subdirectories based on their resource to allow for default functionality. However, when the artifacts are copied to the profile_dir/installableApps directory, it is just the content of the subdirectories that are copied. The following is a list of currently supported resource subdirectories: ear: This directory contains any EAR files that need to be deployed to the application server. WAR files that do not contain any portlets and need to be installed directly to the application server should be wrapped in an EAR file. The reason is that the default scripts used to deploy artifacts require specific information to run the installation. We need a mechanism to obtain installation information such as the display name and context root details which can be found in the application.xml file of an EAR file. The context root information would not be available with just a WAR file. An example of a WAR file that needs to be wrapped this way is a theme.war file. If you are providing a custom ANT script to do the deployment, then it is unnecessary because you can provide the required information in the script or a properties file read by the script. EAR files are deployed automatically to the server when found in this directory. If a WAR file containing a portlet is wrapped in an EAR file, the developer must provide an additional script to register the portlets with Portal. There is currently no introspection performed on the EAR file and its contents to see if they contain portlets. Therefore, it is the responsibility of the developer to ensure that the portlets are registered in the correct manner. portlets: The portlets directory is where any WAR files containing JSR portlets are to be placed. The Solution Installer does not automatically handle IBM legacy portlets. They require custom code to perform the install and should not be placed in this directory. The reason for separating these WAR files from those that contain servlets or other application types is due to the required installation method . Those containing JSR portlets are typically installed and deployed using an XML access script. Those that need to be installed directly to the application server are deployed using a ConfigEngine ANT task or using a wsadmin script. Solution Installer can then read the portlets directory and install the WAR files automatically. However, if there is additional configuration setup for a portlet, then the default installation task should be overwritten by supplying an ANT task with a custom XML access script to do the install. Add an element to the sdd.xml file for the deploy-portletsapplySIFeaturePack extension point and add an ANT task that implements this extension point in the config/includes directory. This ANT task needs to call the XMLAccess task to run any supplied XMLAccess script against the portal server. The automatic installation uses the unique ID from the element found in the warfile/WEB-INF/portlet.xml file, and the location of the WAR file to enable the deployment. If the unique ID is not available, the name of the WAR file is used instead. The WAR file is automatically copied to the profile_dir/installableApps directory. The following is a sample XMLAccess script that shows how the information is used to drive the install: file:///$profile_dir$/installableApps/warfile.war 3.2.3.4 shared When deploying an application, additional shared libraries are often required for the application to function correctly. These libraries can reside at different scope levels for the application. If stored in the WAR file, then only classes within that WAR file can access the library files. The second situation is when a set of libraries are solution specific. The classes in the shared library are available only to the overall solution. The WAR file option is not appropriate. It could mean a number of separate applications working together as a larger solution, all requiring access to the library. The scope level is global, meaning that many applications running on the server can access these classes. The first situation where the library JAR files are stored in the WAR file is out of scope for this document. However, the Solution Installer can handle the other two situations. For globally available JAR files, place the JAR files into either the component/shared/app or component/shared/ext directory. These files are not copied to the equivalent directories under the PortalServer root directory. Instead, a task runs to register all the JAR files found in the shared/app and shared/ext directories of the components. When objects are found in these directories, they are registered directly with a Solution Installer specific set of shared libraries that reside inside the profile. This action makes the libraries profile specific thus different versions of the same files could be installed to different profiles. It is important because many of the industry templates are using different versions of the same components. It allows multiple templates to reside on the same server under different profiles. JAR files in the component/shared/app directory are registered in the Solution Installer specific shared.app.jar file. Similarly for the jar files in the componentName/shared/ext directory, they are registered with a profile specific shared.ext.jar file. These files can be found under the profile_name/PortalServer/solutionInstaller directory subtree. The specific library ‘SiSharedLib’ is registered at the cell/node level of the profile. A reference is then added to the classpath of the application server to ensure that the files are available at runtime. Only the shared.app.jar file is loaded automatically by the SiSharedLib library. Once the registration of these files is complete, a server restart is required to reload the libraries and make the classes available on the class path. When it is complete, the library specific classes are now available globally to that server for an application to access. To allow a library scope limited to a specific solution, place the relevant JAR files in the component/shared/common directory. Files in this directory are not copied to a location inside of the profile directory. Instead, a shared library for this component pointing to this directory is added to the WebSphere Application Server. This shared library then needs to be associated with either the application or made available on the server wide class-path so it is available to all applications. To achieve this, a properties file called shared-library.properties resides in the component/shared/common directory. This file contains information on the scope to which the shared library needs to be registered. It also provides information on any required class loader properties, such as, class loading precedence. The following properties are available in the shared-library.properties file: # set whether the library should be at the server scope or application scope # Can have the following values: # cell, cluster, node, server library-scope=server # specify whether the library should be added to the server class path or associated with a specific application. Library-ref=application # Set the name of the application(s) to which the library is to be associated. # Name of application(s) found in the integrated administration # console/applications/enterprise applications. applicationName= # Set class loading preference, options are either # 'PARENT_FIRST' or 'PARENT_LAST'. classLoadingMode=PARENT_FIRST If multiple applications are to be associated with the library, a comma separated list of application names can be specified as follows: applicationName= AppName1, AppName2, AppName3 where Appname1/2/3 represent the applications to which the library is to be associated. 3.2.3.5 template The template directory is where a developer can place files to create a website template based on one or more of the components supplied in the PAA distribution. If you examine the sample PAA file included with Solution Installer, there are three subdirectories included. However, many more directories can be contained within, one for each additional template you want to provide. The Solution Installer reserves the directory names used in the sample PAA file to inform it of the nature of the content. For example the newsitewizard directory contains template artifacts that can be imported using the new site wizard portlet. The composite directory contains any composite application template compress files. Each compress file represents a composite application template. However, there are no other restrictions on template directory names. The default directory and any subsequent template directories have their content split into two further subdirectories to aid in the distinction between install and uninstall scripts. The install scripts reside in the /component/template/template_Name/install directory. The uninstall scripts are placed in the /component/template/template_Name/uninstall directory. The scripts contained in the default directory are always run. Therefore, if you are offering multiple templates and do not want one to be installed by default, then leave this directory structure empty. In general the content of the default, or template specific directories, include XMLAccess scripts to create pages, put portlets on the pages, and create users. That is, any task that is site related and not covered by the other directories or components. For example, an XMLAccess script to install a WAR file should not be placed here. Instead this file, if required, can be placed in the component/config/templates directory if a custom Ant task is required, or in the component/content/xmlaccess directory otherwise. To use a different template, set the ‘templateName’ property in the componentName.properties file. Enter the name of the template; for example: templateName=template2 Site template artifacts that are imported using the new site wizard reside in the component/template/newsitewizard directory. There is no further directory substructure, instead all new site wizard related JAR files reside at the top-level of this directory. Solution Installer ensures that the new site wizard has been deployed to WebSphere Portal. Once this is verified, the running new site wizard WAR file is retrieved from WebSphere Portal and copied to a temporary directory. The new template JAR content is extracted and copied over to the relevant locations inside of the new site wizard. After which, the new site wizard is repackaged and deployed to the server. The new template artifacts is available to the user through the new site wizard portlet. The new site wizard artifacts do not need to be limited to just containing functionality for an overall site template, they can be specific to a component. A component specific new site wizard template should be stored local to that component to aid reuse. Note: It is recommended that any site wide template related artifacts are stored in a single component separate from the components on which they depend. It allows the overall site presentation to be separate from the underlying technologies they surface and it makes it easier for the installer to handle updates in the future. It also makes it much easier to manage the provision of multiple site templates in a single PAA distribution. Sample or demo pages for a single component are stored local to that component. 3.2.3.6 version The component/version directory contains a component_name.component file. This file tells Portal and the ConfigEngine, the version of the application being installed. Knowledge of the installed version is necessary to facilitate updates to an application. 3.3 Unique name generation for portlets Solution Installer allows any WAR-based portlets being deployed from the 'installableApps/portlets' directory to make use of unique name generation. This action allows scripts to be written referencing the unique name values of portlets, as opposed to the use of object IDs. All portlets have unique name generation based upon the following naming scheme: uniquename=. This naming scheme is deterministic and it allows ease of reference for the portlets named. After installing the PAA file, additional files are generated containing the unique name values and how to apply these to the portlets being installed. The directory 'componentName/config/templates' contains files generated by the naming scheme -portletDataGen.xml, which contains the generated unique name values for that particular WAR file. The user can edit the unique name values of the portlets in this file prior to deployment to the Portal server. The following is a sample XMLAccess script showing how the unique name values are specified: Although not essential in all instances, it is recommended to pre-pend the component name to the WAR file name as componentName.warName.war. This action allows the Solution Installer to successfully generate ID's in the absence of a unique identifier for the portlet application and allow the user to manage the portlets with reference to a particular component. Using the WAR file 'MyWar.war' as an example, and assuming the WAR file is within component 'MyComponent', the WAR should be renamed 'MyComponent.MyWar.war'. WAR: This directory contains any WAR files that the developer does not want to install automatically. This directory has extended the extension point with a custom Ant task to install the artifacts. Alternatively, the WAR file does not contain any portlets and the developer does not want to wrap it in an EAR. Also, there might be additional customization steps required for the configuration of the deployed artifacts that is not performed by the default install. A custom script is required. The installer generally ignores this directory apart from copying the files to the profile/installableApps directory and then invoking any custom code provided to handle these artifacts. ZIP: This directory contains any compress file content that you need to ship for a component. For example, you might have some artifacts that need to be copied and installed to a server that currently is not supported by Solution Installer. One such case would be if you were providing business processes that need to be installed to IBM WebSphere Process Server. These could be included in a zip file in this directory. Solution Installer does not automatically process the content of this directory. That is, apart from the initial expansion of the PAA where the files are copied into the correct location in the expanded PAA. The individual files remain in their zip state after the PAA file is un-packaged. Instead, any processing of these files is left to either custom Ant tasks provided by the developer or through manual steps performed by the user. 3.4 Property Files 3.4.1 Properties provided by developers There are two different types of properties contained within a PAA distribution. They can be classified as being either user editable, that is requiring user input, for example a database URL, or as developer provided settings required for a component to function. However, for user convenience, a separation between user properties from those settings supplied by the developer is advised. In general it is custom Ant tasks that are provided by the developer that handle such properties. The case where this differs is when properties for connecting to an external database are included or a selection property for cases when the user wants to install a template other than the default template in the PAA templates directory is required. However, there are cases where properties required by the installer might also need to be set. In this case, these need to be included along side user editable properties. Users might need to edit such content before running the installation. It makes sense to consolidate such properties in the one place; instead of requiring the user to edit multiple files in different locations throughout the PAA file. However, there is a trade off with keeping all the properties required by a component together to allow for component reuse. Therefore, a number of approaches to storing properties in the PAA file is allowed. User editable properties can be defined in the properties file specific to a component, component_name.properties, which can be found in the top level directory of a component. The naming scheme of this file is important because the Solution Installer automatically loads it. Once the PAA file has been expanded, users are free to edit these as needed and can then re-run any ConfigEngine functionality associated with the component to take account of these new values. The values in this file are the defaults for the properties and might be overwritten by parent properties files. There are two ways in which the properties in the component level properties files can be overwritten by parent properties. The properties files containing user editable properties for the components of the PAA assembly can be consolidated into one properties file and placed in the top level directory of the PAA file. It is called assembly_name.properties. This file is editable to set any values required for the installation to ConfigEngine and WebSphere Portal to run smoothly. When the installation process for the ConfigEngine is started, these properties are read first, leaving values in the default properties files redundant as Ant properties cannot be overwritten once set, unless they have gone out of scope. Alternatively, the user editable properties can be passed in on the command line as parameters to the Solution Installer tasks. Individual property name=value pairs can be typed on the command line with a -D prefix to inform Solution Installer and the ConfigEngine that they are to be treated as ant properties. Alternatively a properties file containing all of the user editable properties can be passed in on the command line using the ant -propertyfile parameter. The approach taken by the installer is to check the command line to establish if properties have been passed in when the task was invoked. If this is the case, the properties are loaded and the values of the properties are set. Similarly, if a properties file is not received on the command line, then it looks in the highest level directory of the PAA distribution for such files. Once found, these values are loaded as the values for the properties. If there are additional properties in the assembly level file to those passed in from the command line, then these are read as well. If no properties file is found, values from the component level property files are used. Otherwise, it is assumed that no user editable properties are required and the installation proceed. Property files containing developer provided settings should reside at the component level. To aid reuse of components across multiple PAA files, required settings should be kept local to a component. When deciding on property names, great care should be taken. A limitation of Ant means that once a property has been created in a run of the scripts, it cannot be overwritten. Therefore if you are installing multiple components that have a setting with the same name but different values, the first one to be created is used throughout the installation. It can cause unexpected results. It is recommended that a pattern for naming the properties should be employed to ensure that property names across components do not clash. For example, a property name could have the name of the component to which it relates, pre-pended to the name to ensure uniqueness. 3.4.2 Properties added to the PAA by Solution Installer There are a number of occasions where properties are added to the PAA by the Solution Installer during the install-paa task. The components.properties file is added after the installpaa task has completed to allow users to check if components are already existing on the node, and to select whether to install the component or not. Each entry in this file are a Boolean property representing a component included in the PAA file. By changing settings in this file, users can decide which components are acted upon. They also serve as the mechanism where users can handle different versions of the component. See the user manual for more details on updating existing components. A second situation where Solution Installer adds properties is when the –Dwcmdetect property is set on the command line for the install-paa task. If this parameter is set to true, the Solution Installer adds properties in the assembly level properties file to allow users to control whether a WCM library is overwritten. Each library has a Boolean property associated with it in the properties file. They are set to false by default. Setting them to true means that the library is removed from the server and replaced with the one in the PAA file during the deploy-paa step. The third occasion where Solution Installer adds properties to the PAA file is when database scripts are found in a component. In this case, properties are added to the componentName.properties file that allow users to configure the database connection. A developer can add a default.properties file that contains default values for the individual properties, otherwise, Solution Installer adds the relevant properties to the componentName.properties file. When default properties are included, they are added to the componentName.properties file. Where a required property is not set, a default value is added. See Appendix A: Database properties for more details on the list of properties that can be used. For a description on how to add the default.properties file see Appendix A. 3.5 Order of installation of scripts and artifacts There are many cases where the order in which scripts are run and artifacts to be deployed is important for the success of the installation. For the most part, it is controlled by the dependencies set in the sdd.xml file for the extension points. The dependency links between extension points and higher level components control the order in which the different resource types are run. However, if there are multiple scripts or resources of a given type, there is no way to determine the correct order of installation. If a custom task is provided, then it does not pose a problem as the order is governed by the task. However an issue arises when the default tasks are to be used to initiate the installation. To solve this issue, a properties file called order.properties can be added to any of the directories within the component hierarchy that contain required artifacts. For example, such a file could be added to the componentN/templates/default/install directory. This file contains a list of the file names in the correct order that they are to be run/deployed. If no order.properties file exists, Solution Installer woks on the assumption that the order of installation is not important. 4. Adding Custom Code to a PAA File This chapter provides details for application developers who want to install resource types for which install details are not automatically generated by Solution Installer. Developers might also want to overwrite the default functionality of the Solution Installer. Additional information might be required to configure a specific resource on the server. 4.1 What is custom code Although many of the resource types that you want to install can be handled automatically, there are a number of resource types for which there is no mechanism to determine an accurate installation procedure. In addition, there are installation tasks for which the default install code are not enough to perform the installation because additional configuration settings are necessary. For those tasks, a custom implementation of the installation tasks is required. In this section we show how to include such additional content in the PAA distribution file and detail how it is handled. How Solution Installer resolves installation tasks When adding custom code to your PAA file, it is useful to know how Solution Installer determines how a resource should be deployed to WebSphere Portal. There are two scenarios for Solution Installer when determining how an artifact included in the PAA file should be installed. The first scenario is when files are placed in the default directories and no extension point is provided in the sdd.xml file. In this scenario, Solution Installer generates both extension points and the implementation tasks. Solution Installer examines the file types and add an extension point to implement this task. If, by examining the artifact type, it is possible to determine the correct extension point to be applied, the ConfigEngine supplied extension point are implemented. For example, an EAR file requires the create-ear and applySIFeaturePack or remove-ear extension points. removeSIFeaturePack is appended to the name of the core extension point to ensure that it is picked up; for example, create-ear-applySIFeaturePack. However, it might not always be possible to determine the correct extension point to use. For example, in the case of the scripts in the content/xmlaccess directory of the component, it might not be obvious what extension point should be implemented. Therefore, a generic Solution Installer extension point might be applied. The code is also generated and copied into the config/includes directory. The second scenario is the inclusion of developer supplied code in addition to Solution Installer automatically generated code. After the PAA file is expanded by Solution Installer and before the assembly and subsequent components are installed to ConfigEngine, Solution Installer queries the sdd.xml file for the component to determine if any extension points have been already registered. It then checks whether an implementation task exists in the config/includes directory for any extension point listed in the sdd.xml file. If the task exists, then Solution Installer knows that a task has already been created for that extension point and the installer moves on to the next extension point. However, if no task is available, then a default task is generated to do the deployment. The auto generated tasks is also added to the config/includes directory of the expanded component. Any dependent artifacts for the tasks; for example, XMLAccess scripts; are placed in the config/templates directory. After this process has been completed for each component, the PAA distribution is then installed to the ConfigEngine. In this way both simple and complex configuration tasks can be easily performed. A default task should suffice for most cases, however when additional configuration is required for an artifact that isn't easy to generalize then the custom code approach should be used. This means that the PAA file contains a mixture of deployable artifacts, scripts such as XML access scripts to create pages and do some configuration and ConfigEngine Ant tasks that supply custom deployment code. 4.2 Where to place custom code in the PAA file An example PAA file can be found in the SolutionInstaller/documentation/sample directory and this contains a sample component 'componentN', i.e. sample_paa/components/componentN. If you open the sample component ‘componentN’, there are the 'config/includes' and 'config/templates' directories. These are the directories where custom code and all Solution Installer generated code is placed. The 'config/templates' directory should contain any additional scripts that are required to perform the installation for custom code, for example. a script to configure a war file on Portal. The includes directory is the placeholder for any custom ANT tasks that are to be provided. Any script in this directory are picked up at runtime by the ConfigEngine. 4.3 Naming custom code files For the most part, there are no restrictions governing file names for custom code, but you should be aware that Solution Installer adds automatically generated code to the file named in the following manner. It uses the portion of the component name following the '/' combined with the string '_cfg.xml. Using the ‘componentN’ sample, the component name is components/componentN, (the component name needs to contain the full path from the top level sdd.xml file), therefore the file is called 'componentN_cfg.xml. For installation of WAR files via the installableApps/portlets directory, filenames is generated based upon the name of the WAR to be installed. The WAR filename is combined with the strings '-portlets-install.xml', '-portlets-uninstall.xml' and '-portletDataGen.xml'. Assuming a WAR filename of 'MyWar.war', the files 'MyWar.war-portlets-install.xml', 'MyWar.war-portletsuninstall.xml' and 'MyWar.war-portletDataGen.xml' are generated. It is advisable that you name your files containing custom ANT tasks differently to avoid any situations where custom code might get overwritten by installer generated code. 4.4 Component level SDD.XML file With the sample PAA file provided, the component level sdd.xml is located in the componentN directory. If there is no custom code required, a component level sdd.xml file is unnecessary as it is generated. However, if custom installation code is required, then the inclusion of the component level sdd.xml file by the developer is imperative. The first step in adding custom installation code to your PAA file is to register the code with the ConfigEngine so it can be picked up by Solution Installer. To do this you must add a element to your component level sdd.xml file. For a description on how to create or edit a component level sdd.xml file, see Appendix D: The component level sdd.xml file. The following is a sample element for the extension point create-ear. It tells the Solution Installer that you want to overwrite this functionality. The full name of the extension is 'create-ear-applySIFeaturePack'. The create-ear part is to tell the ConfigEngine what type of install functionality is being used so it can group the tasks to be run. The 'applySIFeaturePack' portion of the extension point allows Solution Installer only to invoke functionality of the ConfigEngine for components that conform to this naming scheme. Hence it reduces the likelihood of other components, for example, core Portal components, being accidentally removed during uninstall. create-ear-applySIFeaturePack 1.0.0 After registering the extension point with the sdd.xml file, an implementation task must be created to overwrite the default functionality, or indeed in many cases provide functionality for the installer to act on a specific resource type. To do this a task needs to be created and placed in a file residing in the config/includes directory of the component. There is a specific naming scheme required for this task so that it can be directly associated with the element in the sdd.xml file. The naming scheme is as follows: 'action-' + + '-' + For example: action-create-ear-applySIFeaturePack-components/componentN. Example for uninstall: action-remove-ear-removeSIFeaturePack-components/componentN. Note again that the full path of the component relative to the assembly level sdd.xml file needs to be used as the component name. If creating custom code to be run in a clustered environment, for those resource types that replicate across servers during a Portal synchronize command, the task does not need to be run on nodes other than the primary node. Instead, a synchronization of the nodes should be performed. To ensure that the task is only run on the primary node, you need to add an unless="isSecondNode" attribute to the task designated to run the deployment. For example: The list of extension points used by the Solution Installer and the resource types they cover are listed in Appendix B. ConfigEngine Extension Points for Solution Installer. However, once you add the '-applySIFeaturePack' string to the extension point name, it can be picked up by Solution Installer; therefore you are not limited to this list of extension points. The documented extension points are just those that have a direct relevance to the Solution Installer installation code generation. Any ConfigEngine extension can potentially be used once they conform to this naming scheme. 5. Solution Installer Sample Bootstrap Files The sample bootstrap scripts allow developers to quickly create their own batch/shell scripts to install a PAA based application to WebSphere Portal. Often developers spend a lot of time writing and testing such files for their applications. A developer can use sample bootstrap files as a default template in creating scripts to manage the installation of their application. It reduces the amount of work required for creating such files. Developers can edit the Solution Installer supplied sample scripts to create their own bootstrap files. For complex applications, some additional tasks might be required and these should be added by a developer when necessary. The sample files are just examples and should be edited by developers to reflect their requirements. 5.1 Content of the SolutionInstaller/ documentation/bootstrap directory • install.bat This template batch file contains scripts that can deploy a PAA file into a Windows WebSphere Portal server environment. The batch file tuns the install-paa and deploy-paa commands against a PAA file. • install.sh The install.sh shell script file is a Linux version of install.bat. • uninstall.bat This template batch file contains scripts that can remove a PAA file from a Windows WebSphere Portal environment. The batch file run the remove-paa and uninstall-paa commands against a PAA file. • uninstall.sh This uninstall.sh shell script file is a Linux version of uninstall.bat. • settings.properties The properties in the settings.properties file should be set correctly before running the bootstrap script files. Some of them are PAA specific properties. These properties should be set by PAA developers before releasing. The other properties are user specific properties. These properties should be set according to the WebSphere Portal environment by users. Developers might need to add more properties according to their requirements. The general format of a property is keyword=value. The following is the full set of mandatory properties in settings.properties User specific properties: PROFILE_DIR The value specifies where the profile directory is located on the WebSphere Portal server. For example, PROFILE_DIR=/opt/IBM/WebSphere/wp_profile. OFFLINE_MODE The value tells the installer to install the application with or without trying to access external DTD files. Set this to false if the environment has direct access to the internet. Default to true. PAA specific properties: PAA_NAME The value is the name of the PAA file which are installed. APP_NAME The value is the name of the application. The value is actually the assembly name which is specified in assembly level sdd.xml file. PAA_RELATIVE_PATH The value tells the relative path to the PAA file. This is the value where developers want to place the PAA file. For example, PAA_RELATIVE_PATH=paa/Sample2.paa. 6 PAA directory This folder contains a Sample2.paa file which is a sample PAA file released with bootstrap files. 5.2 Configuring and customizing the Bootstrap files for an application by developers 1. Copy all the bootstrap files to a workspace 2. Edit the correct paa related properties in settings.properties You should at least specify values to PAA_NAME, APP_NAME and PAA_RELATIVE_PATH in settings.properties. You could add any more properties to the property file according to your requirements. 3. Edit the install/uninstall scripts according to your requirements By default, the bootstrap install files run the install-paa and deploy-paa commands against a PAA file. The bootstrap uninstall files run the remove-paa and uninstall-paa commands. Developers could customize the install/uninstall scripts by adding additional tasks in these script files. 5.3 Running the bootstrap files by users 1. Set user environment properties Before running the bootstrap script files, users should set the user specific properties in settings.properties correctly. Users must at least set a correct value to PROFILE_DIR. 2. Running the bootstrap files Windows: To run install/uninstall batch scripts on a windows machine, open a command line prompt, then go to the directory containing the batch file, then type and run “install.bat” or “uninstall.bat”. i.e. If your install.bat and uninstall.bat are in workspace/sample, then go to this directory and run install.bat from command line. Linux: To run install/uninstall shell scripts on a Linux machine, open a terminal console, then go to the directory containing the shell script file, then type and run “./install.sh” or “./uninstall.sh”. i.e. If your install.sh and uninstall.sh are in workspace/sample, then go to this directory and run install.sh from terminal console. Notes: 1. If you do not have run permissions on these files, run the chmod command against the shell script files. i.e. chmod 755 install.sh 2. If you get an EOL error when you run the shell script files, run the dos2unix command to ensure the shell script files contain the correct UNIX end-of-line characters. i.e. dos2unix install.sh. 5.4 Example The following example shows how you would edit and create bootstrap files for Sample2.paa, and run the bootstrap files on a Windows machine. The bootstrap files are under WebSphere/PortalServer/SolutionInstaller/documentation directory. You need to manually copy the bootstrap directory to your workspace, for example. C:\temp\workspace. You should avoid making changes in PortalServer directory directly. Then do the following steps in your workspace: 1. Edit paa property in settings.properties Set PAA_NAME, APP_NAME and PAA_RELATIVE_PATH as the following in settings.properties. This step should be done by a developer. PAA_NAME=Sample2.paa APP_NAME=Sample2 PAA_RELATIVE_PATH=paa/Sample2.paa 2. Edit WebSphere Portal environment property in settings.properties. Set PROFILE_DIR to path to profile directory. This step should be done by the user. For example, PROFILE_DIR=C:\IBM\WebSphere\wp_profile 3. Run the install.bat and uninstall.bat Open a command line prompt, go to the bootstrap directory, type and run: install.bat. It deploys Sample2.paa into Portal. If you want to uninstall the PAA file, you should type and run: uninstall.bat. Sample2.paa is removed from Portal. 6 Troubleshooting for Developers This chapter provides details for application developers who encounter problems generating and installing PAA files for their applications. 6.1 Naming of components Components should be placed in a directory called components and follow a naming scheme of “components/componentname” with componentname being the name of the directory within the components directory. The full “components/componentname” name should be used in the assembly level sdd.xml file and also appended to any custom code extension points, for example. action-custom-task-components/sample-applySIFeature. 6.2 Databases Only one component in the PAA assembly can have database artifacts. Ant tasks do not support duplicate property names and the database properties overlap between components. 6.3 Templates Templates are affected by the unique property name restriction. Within the templates directory you can have multiple templates, which the user can select at deploy time through the component properties file and the templateName parameter. However, if multiple components have multiple templates, then a property naming clash can result. Workaround: Only have one component with templates, or only have a template named “default” within each component. 6.4 Error encountered when running xmlaccess scripts for creating user account configurations The definition of a user account for WebSphere Portal 7 now requires that the name and lastname attributes be set. This was not the case in earlier Portal Versions. • If you want to export the user configuration you should ensure that these values are set on the LDAP server or in the WebSphere User Registry before exporting. • If you are using the Download Configuration Portlet to export the user configuration of a virtual portal you should ensure that these values are set before executing the portlet. Appendix A: Database properties The following database properties are used by Solution Installer: dbName= The name of the database created to store tables needed by the PAA. Ideally, it should be specified in the default.properties file, especially if the name of the database is explicitly included in the included table population scripts. DbPort= Specify the database port number. The following are default port numbers for each database, but your server port number might be changed: Default: IBM Derby: 1527 Default: IBM DB2 Database: 50000 Default: Oracle Database: 1521 Default: 1433 DbHostname= The host name or IP address of the server hosting the database. dbType= The type of database. Use the following valid database types: Value: IBM Derby: derby Value: IBM DB2 Database: db2 Value: Oracle Database: oracle Value: Microsoft SQL Server: SQL Server dbProviderName= The name of jdbc provider to be used. Use the following example jdbc provider names: Example: IBM Derby: wpdbJDBC_derby Example: IBM DB2 Database: wpdbJDBC_db2 Example: Oracle Database: wpdbJDBC_oracle Example: Microsoft SQL Server: wpdbJDBC_sqlserver dbDriverType=Connection pool data source dbUsername= The username for connecting to the database. dbPassword= The password for connecting to the database. dbDriverName= © Copyright IBM Corporation 2011. All rights reserved. 33 The name of database driver. Use the following valid driver names: Value: IBM Derby: org.apache.derby.jdbc.EmbeddedDriver Value: IBM DB2 Database: com.ibm.db2.cc.DB2Driver. Value: Oracle Database: oracle.jdbc.driver.OracleDriver Value: Microsoft SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver dbDriverPath= The path to the database driver. Use one of the following examples with values specific to your database. Value: IBM Derby: ${WasHome}/derby/lib Value: IBM DB2 Database: ${WasHome}/deploytool/itp/plugins/${dbPlugin}/driver (For DB2, in the case of Websphere Portal 6.1.5, the ${dbPlugin} directory is generally com.ibm.datatools.db2_1.0.4.v200807241724, however the version number might vary) Value: Oracle Database: {$ORACLE_HOME}/jdbc/lib/ Example: Microsoft SQL Server: installation_directory/sqljdbc_2.0/enu Note: ORACLE_HOME environment variable specified during installation of Oracle database dbClasspath= The database class path value. Use one of the following examples with values specific to your database. Value: IBM Derby: ${dbDriverPath}/derby.jar:${dbDriverPath}/derbyclient.jar:$ {dbDriverPath}/derbytools.jar:${dbDriverPath}/derbynet.jar Value: IBM DB2 Database: ${dbDriverPath}/db2jcc.jar:$ {dbDriverPath}/db2jcc_license_cisuz.jar:${dbDriverPath}/db2jcc_license_cu.jar Value: Oracle Database: ${dbDriverPath}/ojdbc6.jar Example: Microsoft SQL Server: /sqljdbc_2.0/enu/sqljdbc4.jar Note: For Oracle and WebSphere Portal, the driver JAR file is automatically set to `ojdbc14.jar' by WebSphere Application Server. To use this driver file with Oracle 11g and above this file must be manually downloaded, as this file is included with Oracle 10g only. Otherwise, the user might choose to use the driver file `ojdbc5.jar'. However this file must be specified manually within the Administration Console for the JDBC driver path. Driver file `ojdbc6.jar' is not compatible with WebSphere Portal. dbUrl= The database URL value. Use one of the following examples with values specific to your database. Value: IBM Derby: jdbc:${dbType}:${dbName} Value: IBM DB2 Database: jdbc:${dbType}://${dbHostname}:${dbPort}/${dbName} Value: Oracle Database: jdbc:${dbType}:thin:@${dbHostname}:${dbPort}:${dbName} Value: Microsoft SQL Server: jdbc:sqlserver://:$ © Copyright IBM Corporation 2011. All rights reserved. 34 {DbPort};SelectMethod=cursor;DatabaseName=tbmesg dbJndiName= Specify the JNDI name that is used for a component. dsTemplateName= The data source template name. Use one of the following examples with values specific to your database. Value: IBM Derby: Derby JDBC Driver DataSource Value: IBM DB2 Database: DB2 Universal JDBC Driver DataSource Value: Oracle Database: Oracle JDBC Driver DataSource Value: Microsoft SQL Server: Microsoft SQL Server JDBC Driver - XA DataSource jpTemplateName= Use one of the following examples with values specific to your database. Value: IBM Derby: Derby JDBC Provider Value: IBM DB2 Database: DB2 Universal JDBC Driver Provider Value: Oracle Database: Oracle JDBC Driver Provider Value: Microsoft SQL Server: Microsoft SQL Server JDBC Driver dsDbDriverType=4 The type of the database driver the data source connects to. Valid values are "2" and "4". For z/OS, the recommended value is "4" unless the Monitor database resides on the same z/OS LPAR as the CEI server, in which case "2" is recommended. dataSourceName= Specifies the Data Source name that are used for the component. dbAuthDataAlias= Specifies the Authentication Alias. db.connectionTimeout=180 The interval, in seconds, after which a connection request times out and a ConnectionWaitTimeoutException is thrown. Default value is 180. db.maxConnections=30 The maximum number of physical connections that you can create in this pool. Default value is 30. db.reapTime=120 The interval, in seconds, between runs of the pool maintenance thread. Default value is 120. db.agedTimeout=1800 © Copyright IBM Corporation 2011. All rights reserved. 35 The interval in seconds before a physical connection is discarded. Default value is 1800. If providing setup scripts for different database types in a single PAA file, there is an additional step that must be performed during the PAA creation phase. For each database type a properties file must be added to the components/componentName/content/database/install directory. For DB2 database scripts the file are called ‘scripts.db2.properties’. For Derby database scripts, the file is called ‘scripts.derby.properties’. For Oracle database scripts, the file is called ‘scripts.oracle.properties’. For Microsoft SQL database scripts, the file is called ‘scripts.sql.properties’. The properties file should contain a comma separated list of scripts in the order in which they should run for a specific database type. Solution Installer determine what set of scripts to run for the requested database type. © Copyright IBM Corporation 2011. All rights reserved. 36 Appendix B. ConfigEngine Extension Points for Solution Installer The following table lists and describes IBM WebSphere Portal ConfigEngine Extension Points required to install an application from a PAA file: Table 1. ConfigEngine extension points PAA Directory Extension Point Name Config Description No extension points needed. Content Composite Database No extension points available as this is custom code create-jdbc-provider-applySIFeaturePack Create the JDBC provider for Solution Installer remove-jdbc-provider-removeSIFeaturePack Remove the JDBC provider for Solution Installer create-j2c-auth-applySIFeaturePack Create J2C authentication alias remove-j2c-auth-removeSIFeaturePack Remove J2C authentication alias create-dataSource-applySIFeaturePack Create the datasource for Solution Installer remove-dataSource-removeSIFeaturePack Remove the datasource for Solution Installer create-database-applySIFeaturePack Runs script to create the database structures, for example. db schema, tables buffers etc. setup-database-applySIFeaturePack Runs script to populate the database with sample data © Copyright IBM Corporation 2011. All rights reserved. 37 Table 2. ConfigEngine extension points, continued PAA Directory Extension Point Name remove-database-removeSIFeaturePack create-cmp-connection-factory-applySIFeaturePack Description Runs scripts to remove the database structures from the db, for example. drops all tables. Creates cmp connection factory for container management. Not current extension point so needs to be created in SI Removes cmp connection factory for container management. remove-cmp-connection-factory-removeSIFeaturePack Not current extension point so needs to be created in SI No extension point as this is custom code JCR JSP Personalization create-personalisation-rules-applySIFeaturePack No extension point as this is custom code Create the personalization rules for the library remove-personalisation-rules-removeSIFeaturePack Not currently available WCM import-wcm-applySIFeaturePack Import WCM Library XMLAccess install-content-xmlaccess-applySIFeaturePack Run XML install scripts in install/configure application remove-content-xmlaccess-removeSIFeaturePack webdav Import-webdav-applySIFeaturePack © Copyright IBM Corporation 2011. All rights reserved. Run XML scripts to remove application Uploads webdav artefacts to WebSphere portal webdav file system 38 Appendix C: The assembly level sdd.xml file When creating a Portal Application Archive (PAA) file, you must add an assembly level sdd.xml file. This file registers the PAA content with the ConfigEngine. The information in the sdd.xml file informs the Solution Installer about the name and type of the application to install. It also includes information about the versions of IBM® WebSphere® Portal to which installation of the PAA content is compatible. In addition, the sdd.xml tells Solution Installer the names and locations of the components to be installed. The different elements of the assembly level sdd.xml file are described in terms of how they are required for the Solution Installer. You can edit a sample sdd.xml file with the required information to ensure that the sdd.xml file is complete and accurate. Note: In the SolutionInstaller_root/documentation/samples/sample_paa directory, there is a sample to illustrate the PAA directory structure. You can use the assembly level sdd.xml file at sample_paa/sdd.xml file as an example. This file can be used as a starting point for developers to create their own working sdd.xml files. This sample PAA file is an installable application. It can be registered with the ConfigEngine. However, it is not a working PAA file because there are no installable resources. The structure is provided so that a developer can use it to create their own PAA files. The following is an example of an assembly level sdd.xml file: sample_paa 7.0.0.0 © Copyright IBM Corporation 2011. All rights reserved. 39 sample_paa Inside the root element, the following three subelements are required for installation with the Solution Installer: 1. The first element is the packageIdentity element; for example: sample_paa 7.0.0.0 The element informs the Solution Installer and the ConfigEngine of the type of application to be installed. In this case, the contentType attribute equals "Assembly". An assembly is a grouping of one or more components. The Solution Installer considers each PAA file as an assembly, even though it might contain only one component. Do not edit this attribute. The element contains a number of sub-elements that provide information about the content. The name and version elements need to be altered to suit the application being installed. The displayName element can also be edited to include the assembly name, but is not required. Important: The name element provided for an assembly must match the name of the PAA file root directory. For example, a name of ‘sample_paa’ would require the root directory to also © Copyright IBM Corporation 2011. All rights reserved. 40 be called ‘sample_paa’. 2. The next subelement is the element. This element does not require any alterations. For example: 3. The final element block is the element. This element provides the Solution Installer and the ConfigEngine with the information about what to install. The element is where the actual information is included. Set the ‘ID’ attribute of the element to the name of the application as used in the element of the element. sample_paa The element contains the sub-element. Set this element to the name of the assembly found in the name element. Although there is only one element in this example, there can be a number of these elements. One for each component included in the package. This element allows for ConfigEngine to register the components and informs it on where to find the component level sdd.xml file. The Solution Installer auto-generates the component level sdd.xml file during the install-paa command. The developer does not need to add this file for a basic PAA file. However, when the developer needs to provide custom code for installation or configuration, then the component level sdd.xml file must be provided. There are two attributes for the element. The ID must equal the path of the component relative to the assembly level sdd.xml file. For example, as the PAA file puts all components in the ‘components’ directory, a component name needs to also include the ‘components/’. For example, a component called ‘componentN’ would have the id=”components/componentN”. The pathname contains the path from the assembly sdd.xml file to the component level sdd.xml file. Continuing with the previous example, the pathname element is pathname="components/componentN/sdd.xml". © Copyright IBM Corporation 2011. All rights reserved. 41 Appendix D: The component level sdd.xml file When running the install-paa task, the Solution Installer examines each component to verify if an sdd.xml file has been included for that component. If an sdd.xml file is not found, one is generated using the information gathered from the directory parsing step. The Solution Installer uses the data gathered about the resource types included in the Portal Application Archive (PAA) file. It also uses the component directory name to generate the sdd.xml file. For many situations, this automated step is enough to allow the PAA files to be deployed successfully. However, there are situations where the developer needs to overwrite the functionality of Solution Installer as the auto-generated code does not meet their requirements for a specific resource type. In addition, there might be configuration steps that are not covered directly by the Solution Installer code generation that need to be included in the PAA file for the application to be successfully deployed and configured on the server. This article outlines the different pieces of the component level sdd.xml file in terms of their usage by the Solution Installer. In addition, steps on how to create your own custom sdd.xml file and where to include relevant information on the component for successful deployment are also included. Note: If you are providing a component level sdd.xml file, you do not need to provide information for all the resources included in the PAA file. Only provide information where you are not using the Solution Installer generated code. Also include information for steps that are not covered by the Solution Installer. If resources in the PAA file are still relying on the default code, the Solution Installer adds the relevant pieces to the sdd.xml file in addition to the elements included by the developer. The following is an example component level sdd.xml file: components/componentN © Copyright IBM Corporation 2011. All rights reserved. 42 7.0.0.0 Do Configuration Task 7.0.0.0 Do Configuration Task 1.0.0.0 Inside the root element the following three important sub-elements are required for installation with the Solution Installer: 1. The first element is the element; for example: components/componentN 7.0.0.0 The element informs Solution Installer and the ConfigEngine of the type of application to be installed. In this case, the contentType attribute equals "component". A component is the lowest level of granularity used by the ConfigEngine and thus Solution Installer for grouping application resources. One or more components are grouped together in an assembly. This grouping is the next level of granularity for grouping resources recognized by the ConfigEngine or the Solution Installer. Each PAA file is considered by Solution Installer as an assembly, even though it might only contain one component. In the case of the PAA file, a component must have a higher level assembly associated with it. See "The assembly level sdd.xml file" for additional information. If you look at the element there are a number of sub elements that provide © Copyright IBM Corporation 2011. All rights reserved. 44 information on the content being installed. The and element need to be altered to suit the application being installed. The element can also be edited to include the component name but is not required. It is important that the element must equal the path of the component relative to the assembly level sdd.xml file. For example, as the PAA file puts all components in the ‘components’ directory, a component name needs to also include the ‘components/’. For example a component called ‘componentN’ would have a component name of ‘components/componentN’. 2. The next subelement is the element. This element does not require any alterations. For example: 3. The final element block is the element. This element provides the Solution Installer and the ConfigEngine with the information on what is being installed and on which servers the package can be installed on. The element is where the actual information is included. You should set the id attribute of the element to the name of the component as used in the element of the element. For example: Do Configuration Task 1.0.0.0 © Copyright IBM Corporation 2011. All rights reserved. 45 The ConfigEngine requires the element for processing the content. You should not need to edit this section. Just include it in the component level sdd.xml file per the previous example. The element is the element of the file which is of most relevance to adding custom code to your PAA file. Each element represents a ConfigEngine extension point. These extension points govern how and when resources are installed or uninstalled on the server during the deploy-paa task. Each extension point has an equivalent implementation task which needs to be added to a .xml file in the components/componentN/config/includes directory. See appendix B for a list of extensions and how they map to directories. In the previous example, there are two places where you should make changes. The first place is the id attribute of the element. The ID should be set to the name of the required extension point with the applySIFeaturePack appended to the end. For example: deploy-apps-applySIFeaturePack. The second to change is the nested element. The value attribute of this element should also be set to the extension point string. In this case set it to deploy-apps-applySIFeaturePack. For each extension point that you want to implement, you need to provide a separate element. Therefore an additional element would be required to provide an equivalent remove-apps-removeSIFeaturePack extension. There is a second and rather important role assigned to the element. These elements also influence the order in which components are installed. You might have a PAA file with two components, where the second component is installed prior to the first component. A mechanism is necessary to ensure that the correct order is imposed on the deployment. This action can be done by adding a element to the element as shown in the following example: Do Configuration Task 1.0.0.0 © Copyright IBM Corporation 2011. All rights reserved. 46 The element can contain one or more elements, each one representing a component on which the current component depends on being previously installed. The name attribute of the element can be set to whatever value the developer chooses. The name attribute of the 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 element to the element for the 'deploy-apps-applySIFeaturePack', register an equivalent 'deploy-apps- applySIFeaturePack' extension point for the dependent component. © Copyright IBM Corporation 2011. All rights reserved. 47