Using the Portlet Deployment Tool

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 either the build.properties file or the xmlpropfile.xml file to specify the parameters for the PDT.
Execute the PDT by submitting an Ant command in the directory where the build.properties file or the xmlpropfile.xml file is located. The PDT places your custom portlets in the custom content directory for the BI Portlets Web application so that the portlets are included automatically when you rebuild it. The PDT also creates PAR files for the portlets, which are included automatically in the SAS Information Delivery Portal when you rebuild it.
Rebuild the BI Portlets and SAS Information Delivery Portal Web applications by using the SAS Deployment Manager. For more information about rebuilding Web applications, see "Rebuilding the SAS 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. These files are located in the SAS-config-directory/Levn/Web/Staging/ directory. For more information about redeploying Web applications, see "Redeploying the SAS Web Applications" in the "Middle-Tier Administration" chapter of the SAS Intelligence Platform: Web Application Administration Guide.

Specify Build Parameters for the PDT

Overview of Specifying the PDT Build Parameters

The Portlet Deployment Tool is an Ant script that obtains its build parameters from an external file. You can use either of the following parameters files:

build.properties

a plain text file. The PDT uses this file by default. This file is simplest to use if you are defining a single portlet and you do not need to specify locale information.

xmlpropfile.xml

an XML file that enables you to define multiple portlets at one time. You can also specify localized titles and descriptions for the portlets. To use the XML file, you must specify the -Dxmlpropfile=xmlpropfile.xml option when you execute the PDT script.

Specifying Parameters in the build.properties File

The build.properties file is located in SAS-config-directory/Levn/Web/Applications/SASBIPortlets<version>/PortletDeploymentTool/src/. You must specify the following parameters:

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 temporary files.

supported-portlet-modes

specifies which portlet modes are supported by this portlet. Specify one of the following values:

all	specifies that the view, edit, and help modes are supported.
edit	specifies that the view and edit modes are supported.
help	specifies that the view and help modes are supported.

If you do not specify a value, then only the view mode is supported.

Specifying Parameters in the xmlpropfile.xml File

The xmlpropfile.xml file is located in SAS-config-directory/Levn/Web/Applications/SASBIPortlets<version>/PortletDeploymentTool/src/. The format of the xmlpropfile.xml file is as follows:

<webapps server-type="server-type" work-dir="working-directory" >
  <webapp
      servlet-context-name="context-name"
      web-app-name="Web-application-name"
      portlet-ear-file-name="filename"
      portlet-ear-file-path="fully-qualified-filename"
      default-supported-portlet-modes="modes-value" >

      <portlets>
          <portlet name="portlet-name" supported-portlet-modes="modes-value" >
              <locales>
                  <locale name="locale-code"
                          title="portlet-title"
                          description="portlet-description"
                  />
              </locales>
          </portlet>
      </portlets>
   </webapp>
</webapps>

The file contains one <webapps> element, with a <webapp> element inside it for each Web application that you will add. The TestPortlet Scripting Facility configures each portlet as a separate Web application.

<webapps>

specifies the properties that are common to all of the Web applications in the file. You must specify the following attributes:

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

work-dir: specifies the working directory where the PDT places temporary files.

<webapp>

specifies properties for a specific Web application. You must specify the following attributes:

servlet-context-name: specifies the context name for the portlet. The value of this parameter must match the value of the <context-root> element value 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.

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).

default-supported-portlet-modes

specifies which portlet modes are supported by default for the portlets in this Web application. Specify one of the following values:

all	specifies that the view, edit, and help modes are supported.
edit	specifies that the view and edit modes are supported.
help	specifies that the view and help modes are supported.

If you do not specify a value, then only the view mode is supported.

Each <webapp> element can contain an optional <portlets> element. The <portlets> element contains one or more <portlet> elements:

<portlet>

specifies the properties for a portlet. You can specify the following attributes:

name: specifies the name of the portlet.

supported-portlet-modes

specifies which portlet modes are supported by this portlet. Specify one of the following values:

all	specifies that the view, edit, and help modes are supported
edit	specifies that the view and edit modes are supported
help	specifies that the view and help modes are supported

If you do not specify a value, then only the view mode is supported.

Note: The supported-portlet-modes attribute is optional. If you specify a value or a null value, then the supported-portlet-modes attribute overrides the value of the default-supported-portlet-modes attribute on the <webapp> element.

Each <portlet> element can contain an optional <locales> element. The <locales> element contains one or more <locale> elements:

<locale>

specifies the properties for a locale. You must specify the following values:

name: specifies the name for the locale.

title: specifies the locale-specific title for the portlet. The value of this attribute is an escaped-UTF-8 ASCII string.

The value of the title attribute corresponds to the "portlet.description" entry in the locale-specific portletDisplayResources_locale-name.properties file in the portlet's generated PAR file.

description: specifies the locale-specific description for the portlet. The value of this attribute is an escaped-UTF-8 ASCII string.

The value of the description attribute corresponds to the "portlet.description" entry in the locale-specific portletDisplayResources_locale-name.properties file in the portlet's generated PAR file.

For example, the following file deploys two portlets and specifies localization options for the second portlet:

<webapps server-type="websphere" work-dir="c:/temp/pdt-test" >
   <webapp
       servlet-context-name="HelloUserJSR168PortletSample"
       web-app-name="sample.hellouser.jsr168"
       portlet-ear-file-name="sample.hellouser.jsr168.ear"
       portlet-ear-file-path="C:/SAS/EBI/Lev1/Web/Staging/sample.hellouser.jsr168.ear"
       default-supported-portlet-modes="all" >
   </webapp>
   <webapp
       servlet-context-name="HelloUserJSR168PortletSample2"
       web-app-name="sample2.hellouser.jsr168"
       portlet-ear-file-name="sample2.hellouser.jsr168.ear"
       portlet-ear-file-path="C:/SAS/EBI/Lev1/Web/Staging/sample2.hellouser.jsr168.ear"
       default-supported-portlet-modes="all" >
       <portlets>
           <portlet name="HelloUserSample2" 
                    supported-portlet-modes="view help">
               <locales>
                   <locale name="zh_CN"
                           title="\u4e66\u7b7e"
                           description="\u7528\u6765\u7ba1\u7406\u4e66\u7b7e\u7684 Portlet" />
                   <locale name="en"
                           title="CheckWindowStateNormalTestPortlet"
                           description="The HelloUserSample 2 portlet" />
               </locales>
           </portlet>
       </portlets>
   </webapp>
</webapps>

Execute the PDT Script

To execute the PDT with the build.properties file, follow these steps:

In a command shell, navigate to the SAS-config-directory/Levn/Web/Applications/SASBIPortlets<version>/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 PDT.

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

To execute the PDT with the xmlpropfile.xml file, follow these steps:

If you do not have Apache Ant on your machine, download it from ant.apache.org and install it by using the instructions from Apache.
In a command shell, navigate to the SAS-config-directory/Levn/Web/Applications/SASBIPortlets<version>/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 ant.bat script to execute the PDT.

On Windows, enter the following command:

ant -lib "%DEPLOYWIZ%"\ant-contrib.jar -lib "%DEPLOYWIZ%"\bsf.jar -lib "%DEPLOYWIZ%"\bsh.jar -Dxmlpropfile=xmlpropfile.xml

On UNIX, enter the following command:

ant -lib $DEPLOYWIZ/ant-contrib.jar -lib $DEPLOYWIZ/bsf.jar -lib $DEPLOYWIZ/bsh.jar -Dxmlpropfile=xmlpropfile.xml

Add Portlets to the BI Portlets Web Application

To add your portlets to the BI Portlets Web Application:

Stop the Web application server on which the SAS Information Delivery Portal and the BI Portlets Web application are running.
Specify the parameters for your custom portlet in build.properties or, for multiple portlets, in xmlpropfile.xml.
Run the PDT. The new portlets are added to the custom content area for the BI Portlets Web application.
If you want to add additional portlets, repeat steps 2–3 as needed.
Rebuild the BI Portlets and SAS Information Delivery Portal Web applications by using the SAS Deployment Manager. For more information about rebuilding Web applications, see "Rebuilding the SAS 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. These files are located in the SAS-config-directory/Levn/Web/Staging/ directory. For more information about redeploying Web applications, see "Redeploying the SAS 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

If you want to remove any custom 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 portlet PAR files and exploded portlet directories that were generated by the PDT for the custom portlets that you want to remove. The PAR files are located in the SAS-config-directory\Levn\Web\Applications\SASPortlets<version>\Deployed directory. The exploded portlet directories are located in the SAS-config-directory\Levn\Web\Applications\SASPortlets<version>\Exploded directory.
Remove the files in the BI Portlets custom content area that were created by the PDT. The files are located in the SAS-config-directory\Levn\Web\Common\<app-server>\SASBIPortlets<version>\CustomContent\ears\sas.biportlets directory.
Rebuild the BI Portlets and the SAS Information Delivery Portal Web applications by using the SAS Deployment Manager. For more information about rebuilding Web applications, see "Rebuilding the SAS 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. These files are located in the SAS-config-directory/Levn/Web/Staging/ directory. For more information about redeploying Web applications, see "Redeploying the SAS 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.