Using the Portlet Deployment Tool :: Developing JSR-168-Compliant Portlets for the SAS(R) Information Delivery Portal 4.2

Overview of the Portlet Deployment Tool

The Portlet Deployment Tool (PDT) is a command-line script that enables you to add JSR-168-compliant portlets to the BI Portlets Web application.

The basic process to deploy a portlet with the PDT is as follows:

Modify the build.properties file to specify the parameters for the PDT.
Execute the PDT by submitting an Ant command in the directory where the build.properties file is located.
Redeploy the BI Portlets Web application by using the modified sas.biportlets.ear file that is created by the PDT. This file is located in the /staging subdirectory of the working directory that you specify in the build.properties file.

Specify Parameters in the build.properties File

The Portlet Deployment Tool is an Ant script that obtains its parameters from a file called build.properties. This file is located in SAS-config-directory/Levn/Web/Applications/SASBIPortlets4.2/PortletDeploymentTool/src/.

Before you can execute the PDT, you must specify the following parameters in the build.properties file:

servlet-context-name

specifies the context name for the portlet. The value of this parameter must match the value of the <context-root> element in the application.xml file in the portlet source.

Note: If you use the Testportlet Scripting Facility, then the <context-root> value in application.xml is obtained from the webapp.testportlet.contextroot parameter in the custom.properties file.

web-app-name

specifies the name of the WAR file for the portlet, without the .war extension. For example, if the WAR file for your portlet is named sample.hellouser.jsr168.war, then specify the value sample.hellouser.jsr168.

web-app-server

specifies the type of Java application server where the BI Portlets Web application is deployed. Specify either jboss, weblogic, or websphere.

portlet-ear-file-name

specifies the name of the EAR file for the portlet.

portlet-ear-file-path

specifies the full path to the EAR file for the portlet, including the filename. You must use the forward slash (/) character to delimit the directories in your path. For example, C:/SAS/EntBIServer/Lev1/Web/Staging/myportlet.ear.

work-dir

specifies the working directory where the PDT places the modified files for the BI Portlets Web application.

If the working directory contains BI Portlets files from a previous execution of PDT, then the PDT adds the new portlet to the BI Portlets files in the working directory. For more information, see Add Additional Portlets to the BI Portlets Web Application.

Execute the PDT Script

To execute the PDT, follow these steps:

In a command shell, navigate to the SAS-config-directory/Levn/Web/Applications/SASBIPortlets4.2/PortletDeploymentTool/src directory.
Call the level_env.bat script to set environment variables.

On Windows, enter the following command:
```
..\..\..\..\..\level_env.bat
```
On UNIX, enter the following command:
```
../../../../../level_env.sh
```
Call the launchant.bat script to execute the Portlet Deployment Tool.

On Windows, enter the following command:
```
..\..\..\..\..\..\Utilities\launchant.bat
```
On UNIX, enter the following command:
```
../../../../../../Utilities/launchant.sh
```

Add Additional Portlets to the BI Portlets Web Application

You can add only one portlet to the BI Portlets Web application each time you run PDT. However, you can add additional portlets by running the PDT again for each additional portlet.

The work-dir parameter in build.properties specifies the working directory where the PDT places the modified files for the BI Portlets Web application. If the working directory is empty, then PDT adds the new portlet to a copy of the original BI Portlets EAR file. If the working directory contains BI Portlets files from a previous execution of PDT, then the PDT adds the new portlet to the files that are in the working directory.

For example, to add two portlets:

Stop the Web application server on which the SAS Information Delivery Portal and the BI Portlets Web application are running.
Specify the parameters for the first portlet in build.properties. Specify an empty directory for the work-dir parameter.
Run the PDT. The portlet is added to a copy of the original BI Portlets Web application. The modified copy is placed in the working directory that you specified.
Modify build.properties again to specify the properties for the second portlet. Specify the same working directory that you did in step 1.
Run the PDT again. The second portlet is added to the modified BI Portlets Web application in the working directory. The BI Portlets Web application in the working directory now contains both new portlets.
Redeploy the BI Portlets Web application by using the sas.biportlets.ear file in the /staging subdirectory of the working directory. For instructions about redeploying Web applications, see "Redeploying Web Applications" in the "Middle-Tier Administration" chapter of the SAS Intelligence Platform: Web Application Administration Guide.
Restart the Web application server on which the SAS Information Delivery Portal is deployed.

Retaining Custom Portlets after Rebuilding the BI Portlets Web Application

When a hot fix is applied or maintenance is installed, the SAS Deployment Manager is used to rebuild the BI Portlets Web application. The SAS Deployment Manager can also be run manually. In any of these cases, the BI Portlets Web application is rebuilt from scratch; it does not contain any custom portlets.

To add your custom portlets back to the BI Portlets Web application, follow these steps after the SAS Deployment Manager process has completed:

Stop the web application server on which the SAS Information Delivery Portal and the BI Portlets Web application are running.
The PDT can add only one portlet to the BI Portlets Web application at a time (for more information, see Add Additional Portlets to the BI Portlets Web Application). Start by specifying the parameters for the first portlet in build.properties. Specify an empty directory for the work-dir parameter.
Run the PDT. The portlet is added to a copy of the original BI Portlets Web application. The modified copy is placed in the working directory that you specified.
Modify build.properties again to specify the properties for the next portlet. Specify the same working directory that you did in step 2. Repeat steps 3 and 4 for the remaining portlets. The portlets are added to the modified BI Portlets Web application in the working directory. The BI Portlets Web application in the working directory contains all of the portlets when finished.
Redeploy the BI Portlets Web application by using the sas.biportlets.ear file in the /staging subdirectory of the working directory. For instructions about redeploying Web applications, see "Redeploying Web Applications" in the "Middle-Tier Administration" chapter of the SAS Intelligence Platform: Web Application Administration Guide.
Restart the Web application server on which the SAS Information Delivery Portal is deployed.

Start Over with the BI Portlets Web Application

If you want to add a portlet to a copy of the original BI Portlets Web application and remove any portlets that you added previously, follow these steps:

Stop the Web application server on which the SAS Information Delivery Portal and the BI Portlets Web application are running.
Remove any unused portlet PAR files and exploded portlet directories that were generated by the Testportlet Scripting Facility. The PAR files are located in the SAS-configuration-directory\Levn\Web\Applications\SASPortlets4.2\Deployed directory. The exploded portlet directories are located in the SAS-configuration-directory\Levn\Web\Applications\SASPortlets4.2\Exploded directory.
Remove any unused portlet EAR files and exploded application directories that were generated by the Testportlet Scripting Facility. The EAR files are located in the SAS-configuration-directory\Levn\Web\Staging directory. The exploded application directories are located in the SAS-configuration-directory\Levn\Web\Staging\exploded directory.
Specify the parameters for the new portlet in build.properties. Specify an empty directory for the work-dir parameter.
Run the PDT. Modified files for the BI Portlets Web application are placed in the working directory that you specified.
Rebuild the EAR file for the SAS Information Delivery Portal. This EAR file contains files that are associated with each portlet. To add the new portlet, you must rebuild the SAS Information Delivery Portal by using the SAS Deployment Manager. For instructions about redeploying Web applications, see "Redeploying Web Applications" in the "Middle-Tier Administration" chapter of the SAS Intelligence Platform: Web Application Administration Guide.
Redeploy the SAS Information Delivery Portal and the BI Portlets Web applications. The SAS Information Delivery Portal EAR file is located at SAS-config-directory/Levn/Web/Staging/sas.portal4.2.ear. The BI Portlets EAR file is located in the /staging subdirectory of the working directory. For instructions about redeploying Web applications, see "Redeploying Web Applications" in the "Middle-Tier Administration" chapter of the SAS Intelligence Platform: Web Application Administration Guide.
Restart the Web application server on which the SAS Information Delivery Portal is deployed.

Remove Custom Portlets from the BI Portlets Web Application

To remove any custom JSR-168-compliant portlets from the BI Portlets Web application, redeploy BI Portlets by using the original file in SAS-config-directory/Levn/Web/Staging. Follow these steps to remove the custom portlets:

Stop the Web application server on which the SAS Information Delivery Portal and the BI Portlets Web application are running.
Remove any unused portlet PAR files and exploded portlet directories that were generated by the Testportlet Scripting Facility. The PAR files are located in the SAS-configuration-directory\Levn\Web\Applications\SASPortlets4.2\Deployed directory. The exploded portlet directories are located in the SAS-configuration-directory\Levn\Web\Applications\SASPortlets4.2\Exploded directory.
Remove any unused portlet EAR files and exploded application directories that were generated by the Testportlet Scripting Facility. The EAR files are located in the SAS-configuration-directory\Levn\Web\Staging directory. The exploded application directories are located in the SAS-configuration-directory\Levn\Web\Staging\exploded directory.
Rebuild the EAR file for the SAS Information Delivery Portal by using the SAS Deployment Manager.
Redeploy the SAS Information Delivery Portal and the original BI Portlets Web applications. The SAS Information Delivery Portal EAR file is located at SAS-config-directory/Levn/Web/Staging/sas.portal4.2.ear. The original BI Portlets EAR file is located at SAS-config-directory/Levn/Web/Staging/sas.biportlets4.2.ear. For instructions about redeploying Web applications, see "Redeploying Web Applications" in the "Middle-Tier Administration" chapter of the SAS Intelligence Platform: Web Application Administration Guide.
Restart the Web application server on which the SAS Information Delivery Portal is deployed.