6.3 Portlet deployment

< Day Day Up >

After the portlet application is developed and its portlets packaged into a Web Application Archive (WAR) file, it is ready for deployment. In the context of WebSphere Portal Server, it means installing the portlet on the server for users to place onto a portal page.

Portlet deployment on the z/OS platform is a two step process that performs a configuration change to the Portal Server and additionally performs a change to the WebSphere Application Server.

To deploy portlets in WebSphere Portal on z/OS and OS/390 platform, you perform the following steps.

Administrative tasks on WebSphere Portal using the administration portlets for installing portlets. These require a user with portal administrative rights to login via a browser from the portal home page. This portlet deployment step generates job files in the z/OS Portal HFS directory structure for further administration steps to be done to WebSphere Application Server. Changes to the portal configuration are effective immediately but the portlets are not operational until the second step is performed.

Note
This is different from portlet deployment on a distributed platform which does not have the second step.
Administrative tasks on WebSphere Application Server, where you install, update or delete portlets by running script WPAConfig and the jobs created in Step 1. The WPAConfig script searches for the jobs and executes them one by one in the sequence of their generation. After this step the portlets are operational on WebSphere Portal server.

Tip

If the Portal Server is running during Step 2 when executing script WPAConfig, it is stopped and restarted for each of the portlet deployment jobs it finds. Therefore, if you are deploying a large number of portlets from within a WAR file, we recommend you stop the Portal Server first, execute WPAConfig using one of the methods described later in this chapter, and then restart the Portal Server.

6.3.1 Portlet deployment jobs

When the administration portlets in WebSphere Portal server are used to install, delete, or update a portlet they generate portlet deployment job files on the HFS file system on z/OS. These files contain descriptions of further administrative steps to be done in WebSphere Application Server. There is one file for each configuration step, which is referred to as a job. Usually this file is accompanied by further resources, such as a file containing the portlet binaries. The job descriptions in the job files consist of name-value pairs that are recognized by the WPAConfig script. The generated job files only support application type or apptype of war.

Note

Although the ear apptype is recognized by WPAConfig script, it is officially not supported.

Table 6-1 shows the name-value pairs that WPAConfig recognizes and the context in which they apply.

Table 6-1: Name-value pairs that WPAConfig script recognizes
Name	Value	Required for action
action	CreateApp UpdateApp DeleteApp	All actions
apptype	war ear	CreateApp and UpdateApp
appsrc	File name relative to the job directory. It is usually the name of a WAR or EAR file	CreateApp and UpdateApp
context	Context Root value needed when generating an EAR file to wrap a WAR file	CreateApp and UpdateApp required only if apptype=war
appname	Display name of the application needed when generating an EAR file to wrap a WAR file. For the DeleteApp action, this is the name of the application to delete.	DeleteApp. CreateApp and UpdateApp required only if apptype=war
servername	Server Name to which the WebSphere Portal was deployed. For ex. WSPORT	All actions

6.3.2 Directory structure for portlet deployment jobs

Portlet deployment jobs are stored in a file hierarchy that is rooted in the portal temporary directory. The temporary directory is determined during installation of WebSphere Portal.

Note

During installation of our system the following variables were set up for the directory structure, and are referred to throughout the rest of this chapter:

WPS_PATH: /usr/lpp/PortalServer/PortalServer
WS_PATH: /usr/lpp/WebSphere
WS_CONFIG_PATH: /WebSphere390/CB390

The script wpsPre.root.sh, found in <WPS_PATH>/PortalServer/zosinst/scripts, writes the name of the temporary directory into WPAConfig script. It also writes it into the ConfigService.properties file found in this directory, by setting the property wps.deployment.jobs:

 <WPS_PATH>/PortalServer/libapp/config/services

The default location for this portal temporary directory is <WPS_PATH>/temp. The jobs directory is located in this temporary directory and contains five sub-directories. The name and contents of those sub-directories are shown in Table 6-2:

Table 6-2: Name and contents of deployment sub-directories
Directory name	Directory Contents
date	Generated by the administration portlet contains the jobs by date in the format yyyy_mm_dd. A job directory contains all the files that belong to a single job including the job file itself and the portlet's binary file that needs to be installed or updated.
done	Contains jobs and resources that have been successfully executed. Jobs are stored in the hierarchy when they were first generated.
failed	Contains all those jobs that were not successfully executed. Jobs are stored in the hierarchy when they were first generated.
work	Contains all those jobs that the script found in the jobs directory at the beginning of execution and moved to work directory.
log	For each run, the script writes a log file. These log files have the same name as the conversation that is used to make changes to WebSphere Application Server. This name consists of a prefix, the date, and the time of execution.

In our project environment, for example, WebSphere Portal was installed in /usr/lpp/PortalServer/PortalServer.

So the jobs file hierarchy was as follows:

    /usr/lpp/PortalServer/PortalServer/temp/jobs    /usr/lpp/PortalServer/PortalServer/temp/jobs/done/<date1-directory>    /usr/lpp/PortalServer/PortalServer/temp/jobs/failed<date1-directory>    /usr/lpp/PortalServer/PortalServer/temp/jobs/log/<WPConversation_date1_time    1.log>    /usr/lpp/PortalServer/PortalServer/temp/jobs/work/<date1-directory>

6.3.3 The Portlet deployment script

As mentioned, WPAConfig.sh is the name of the script and is found in the <WPS_PATH>/PortalServer/zosinst/scripts directory.

While processing a portlet deployment job, the WPAConfig script:

Parses the arguments. If the optional parameter that determines the number of jobs to process is incorrect, it writes an error message and exits.
Builds global variables that are used throughout the script.
Searches for new jobs in the jobs directory and moves them into the work directory.
Looks in the work directory and checks for jobs. If there are no jobs, it exits.
Creates a new conversation.
Performs a loop over all the jobs or over as many jobs as specified by the optional parameter:
1. Analyzes the job file to see what action is required.
2. If the action is CreateApp or UpdateApp, resolves the WAR or EAR file and deploys the portlet into the application server.
3. If the action is DeleteApp, removes the portlet from the application server
4. Moves successful jobs to the done directory.
5. If the deployment of an individual job fails, it moves the failed job to the failed directory.
Closes the conversation.
Exits the script.

Every step of the script is documented with messages that are written to the standard output and to a log file. When the script finishes, it exits with a return code that indicates whether or not it was successful. The return codes are shown in Table 6-3.

Table 6-3: WPAConfig script return codes
Return code	Meaning
0	Everything was successfully run.
4	There were warnings.
8	There were errors.

The WPAConfig script has one optional parameter, which must be a positive integer. This parameter determines the maximum number of jobs that are processed by the script. If the parameter is not specified, the script will process all available jobs.

6.3.4 Portlet deployment steps

There are two methods to execute WPAConfig.sh script when deploying portlets. The first is to run the WPACONF job that was used during installation to deploy the portlets installed with Portal Server, and the other way is to use the WPAConfig.sh script by telnet'ing to the z/OS UNIX environment.

Portlet deployment using a TSO session

The steps to deploy a portlet using the WPACONF job are:

Bring up the login portal page by entering the following URL in a Web browser: http://<HOST_NAME:8082>/wps/portal.
Log on to WebSphere Portal as a user with administrator rights, and via the Portal Administration GUI, install, delete, or update portlets as required. Make sure this step completes successfully.
Logon to a TSO session and stop WebSphere Portal via the command: /p <WPS_PROCNAME>.<WPS_SERVERNAME>A.

For example, we used: /p WSPORT.WSPORTA.

Submit the WPACONF job to deploy the portlets to the hosting WebSphere Application Server to make them operational. The JCL for this job was customized during installation; refer to Chapter 2, "Portal installation" on page 19.

Note

For the file <WPS_PATH>/PortalServer/zosinst/tools/deploy/client_env, make sure it is configured to set up the correct client environment for using the System Management Scripting API of WebSphere Application Server for z/OS or OS/390.

This job runs the shell script WPAConfig.sh which installs the portlets on the application server.
Check the job log for successful completion.
From the TSO console, start WebSphere Portal via the command: /s <WPS_PROCNAME>.<WPS_SERVERNAME>A.

For example, we used: /s WSPORT.WSPORTA.

The startup performs naming registration for newly-deployed portlets and displays console messages about starting and completing the registration. Wait until the naming registration has successfully completed before using the newly deployed portlets.

Portlet deployment using the WPAConfig script

The steps to deploy a portlet using WPAConfig script are:

Bring up the login portal page by entering the following URL in a Web browser: http://<HOST_NAME:8082>/wps/myportal.
Log on to WebSphere portal as a user with administrator rights and install, delete, or update portlets via the Portal Administration GUI. Make sure this step was successful.
Go to a z/OS or OS/390 console screen, stop WebSphere Portal via the command: /p <WPS_PROCNAME>.<WPS_SERVERNAME>A. For example: /p WSPORT.WSPORTA.
Invoke the WPAConfig.sh script to deploy the portlets to the hosting WebSphere Application Server to make them operational. To do this:
1. Log on to the UNIX System Services on the target system as a user with administrator authority for WebSphere Application Server.
2. Change directory to <WPS_PATH>/PortalServer/zosinst/tools/deploy
3. Make sure the environment of this user is setup to use the SM Scripting API of WebSphere Application Server for z/OS or OS/390. If you need to perform this setup, run the batch file client_env, as follows:. client_env
4. Run WPAConfig. This will install, delete, or update the portlet, as the case may be, on the WebSphere Application Server for z/OS or OS/390.
5. Wait for the conversation committed message:
```
 Conversation WPSConversation_xxxxxx_hh:mm:ss was committed. 
```
From the z/OS or OS/390 console, start WebSphere Portal via the command: /s <WPS_PROCNAME>.<WPS_SERVERNAME>A,srvname='<WPS_SERVERNAME>A'. For example: /s WSPORT.WSPORTA. This startup performs naming registration for newly-deployed portlets and displays console messages about starting and completing the registration.
Wait until the naming registration has successfully completed before using the portlets.

6.3.5 Verifying deployment

First check that the processing of the job and script on z/OS was successful. Check the log files for error messages or warnings. The totals are displayed at the end of the log file as messages WP00047I and WP00048I. If there are warnings and no error messages, everything was, most likely, successfully configured.

Jobs that have errors are moved to the failed directory and not to the done directory. Therefore, after the problem is fixed, move the job from the failed directory to the jobs or work directory. Then re-run the WAPCONF job or WPAConfig script.

If everything was successful, go to a Web browser and bring up the default portal page, via the URL http://<HOST_NAME>:8082/wps/portal. If need be, login and navigate to the page where the new portlets are placed. If the portlets were placed on a place and page after Step 1 of the deployment process then they should now be visible without errors.

< Day Day Up >