Installing the Business Accelerator Framework version 1.0.0.16

This wiki article provides step-by-step instructions for installing and configuring each component of the Business Process Accelerator Framework (BPA). The BPA combines the reusable portlet technology of IBM WebSphere Portal and IBM WebSphere Process Server with the forms-based human interface of IBM Lotus Forms.

Installing and configuring Business Process Accelerator Framework components

To install the BPA Framework, you'll need the following products:

• IBM WebSphere Portal 6.1.0.2
• IBM WebSphere Application Server 6.1.0.21
• IBM WebSphere Process Server 6.2.0.1
• IBM Lotus Forms 3.5.1
• IBM Lotus Forms Server – API
• IBM Lotus Forms Server – Webform Server
• IBM Lotus Forms Designer

Installing IBM Lotus Forms Server Webform Server and IBM Lotus Forms Server API

Setting up the Business Process Accelerator Framework requires the installation of several Lotus Forms components. The instructions below guide you through a single server, and dual server installation of Webform Server and the API.

Before you begin

You need to have WebSphere Application Server (WAS) installed on the machine where you will install Webform Server.

About this task

Lotus Forms Server is a set of components, including the API and Webform Server. The Lotus Forms Server installer lets you choose any or all of the server components. The procedure below assumes that you will be using the graphical mode to install the API and Webform Server. The console procedure is almost identical except that you use the keyboard instead of the mouse to enter data and to navigate through the screens.

To install Webform Server on a single server topology:

1. Run the Lotus Forms Server installer.

• For Windows, run LFServer_xxx_Win32.exe.
• For Linux, run LFServer_xxx_Linux.bin.
• For AIX, run LFServer_xxx_AIX.bin.
• For Solaris, run LFServer_xxx_Solaris.bin.

2. Select the installation language and then click OK.
3. Read and accept the license agreement.
4. Specify the Lotus Forms Server install directory location, or use the default location and click Next.

Notes:

• The Windows default install location is C:\Program Files\IBM\Lotus Forms\Server\x.x. The default install location for Solaris, Linux, and AIX is /opt/IBM/LotusForms/Server/x.x.
• For non-Windows installations, the install path must be a directory where the user installing needs permission to read and write to it.

5. Select Production Installation as the environment type and then click Next.
6. Choose Webform Server - Application, Webform Server - Translator Server, and click Next.
7. Clear the check box beside Sample List and Form Display Portlets and click Next.
8. Leave Translator Server and Log Server selected and click Next.
9. Leave Deploy API... and Deploy Webform Server... selected and click Next.
10. Leave Use Default Location for the Shared File Cache selected and click Next.
11. Enter the path to the WAS server hosting WebSphere Process Server for the API and click Next.
12. On the API Deploy to WebSphere Application Server Details panel, set the server name to server1. Enter your WAS administrative credentials and click Next.

Note: There is a 5 - 10 minute delay before the next panel appears as the installation potentially starts and stops WebSphere Application Server.

13. Insert the name of the database to use, either DB2 or Cloudscape/Derby and click Next. Using DB2 is recommended. To use DB2, you must create a database called WS_ACDB prior to continuing through the remaining steps. Ensure that you set the path to the JDBC Driver for the DB2 database. For example: c:\DB2\sqllib\java. Click Next.
14. Enter the path to your WAS server for the Translator Server and click Next.
15. Enter your WAS administrative credentials in the Translator Deploy to WebSphere Application Server Details panel and click Next.

Note: There is a 1 - 5 minute delay before the next panel appears as the installation potentially starting and stopping server1.

Webform Server is now installed on your machine. To test if Webform Server is successfully running, go to: http://myTranslator:8085/translator/Translate?Action=toolbelt.

Note: Do not use this test URL to load forms. Should an installation error occur, error messages will appear in the following log files:

• [WAS Profile Dir]/logs/TranslatorServer/SystemOut.log
• [WAS Profile Dir]/logs/TranslatorServer/SystemErr.log
• [Lotus Server Install Dir]/WebformServer/LogServer/logs/translator/error.xml
• [Lotus Server Install Dir]/WebformServer/LogServer/logs/translator/operational.xml

16. Restart all servers.

Remember: If you use Derby for Webform Server, you must stop and start TranslatorServer and WebSphere Process Server in the following order:

• stopServer server1
• stopServer TranslatorServer
• startServer TranslatorServer
• startServer server1

To install Webform Server on a dual server topology:

1. Run the Lotus Forms Server installer on the computer where Webform Server will be installed.

• For Windows, run LFServer_xxx_Win32.exe.
• For Linux, run LFServer_xxx_Linux.bin.
• For AIX, run LFServer_xxx_AIX.bin.
• For Solaris, run LFServer_xxx_Solaris.bin.

2. Select the installation language and then click OK.
3. Read and accept the license agreement.
4. Specify the Lotus Forms Server install directory location, or use the default location and click Next.

Notes:

• The Windows default install location is C:\Program Files\IBM\Lotus Forms\Server\x.x. The default install location for Solaris, Linux, and AIX is /opt/IBM/LotusForms/Server/x.x.
• For non-Windows installations, the install path must be a directory where the user installing needs permission to read and write to it.

5. Select Production Installation as the environment type and then click Next.
6. Choose Webform Server - Translator Server and click Next.
7. Leave Translator Server and Log Server selected and click Next.
8. Leave Deploy Webform Server... selected and click Next.
9. Leave Use Default Location for the Shared File Cache selected and click Next.
10. Insert the name of the database to use, either DB2 or Cloudscape/Derby and click Next. Using DB2 is recommended. To use DB2, you must create a database called WS_ACDB prior to continuing through the remaining steps. Ensure that you set the path to the JDBC Driver for the DB2 database. For example: c:\DB2\sqllib\java. Click Next.
11. Enter the path to your WAS server for the Translator Server and click Next.
12. Enter your WAS administrative credentials in the Translator Deploy to WebSphere Application Server Details panel and click Next.

Note: There is a 1 - 5 minute delay before the next panel appears as the installation potentially starting and stopping server1.

Webform Server is now installed on your machine. To test if Webform Server is successfully running, go to: http://myTranslator:8085/translator/Translate?Action=toolbelt.

Note: Do not use this test URL to load forms.

Should an installation error occur, error messages will appear in the following log files:

• [WAS Profile Dir]/logs/TranslatorServer/SystemOut.log
• [WAS Profile Dir]/logs/TranslatorServer/SystemErr.log
• [Lotus Server Install Dir]/WebformServer/LogServer/logs/translator/error.xml
• [Lotus Server Install Dir]/WebformServer/LogServer/logs/translator/operational.xml

13. Run the Lotus Forms Server installer on the computer where WebSphere Process Server is installed.

• For Windows, run LFServer_xxx_Win32.exe.
• For Linux, run LFServer_xxx_Linux.bin.
• For AIX, run LFServer_xxx_AIX.bin.
• For Solaris, run LFServer_xxx_Solaris.bin.

14. Select the installation language and then click OK.
15. Read and accept the license agreement.

16. Specify the Lotus Forms Server install directory location, or use the default location and click Next.

Notes:

• The Windows default install location is C:\Program Files\IBM\Lotus Forms\Server\x.x. The default install location for Solaris, Linux, and AIX is /opt/IBM/LotusForms/Server/x.x.
• For non-Windows installations, the install path must be a directory where the user installing needs permission to read and write to it.

17. Select Production Installation as the environment type and then click Next.
18. Choose Webform Server - Application Server and click Next.
19. Specify the Lotus Forms Server install directory location, or use the default location and click Next.
20. Clear the check box beside Sample List and Form Display Portlets and click Next.
21. Leave Deploy API... selected and click Next.
22. Enter the path to the WAS server hosting WebSphere Process Server for the API and click Next.
23. On the API Deploy to WebSphere Application Server Details panel, set the server name to server1. Enter your WAS administrative credentials and click Next.

Note: There is a 5 - 10 minute delay before the next panel appears as the installation potentially starts and stops WebSphere Application Server.

24. Restart all servers.

Remember: If you use Derby for Webform Server, you must stop and start TranslatorServer and WebSphere Process Server in the following order:

• stopServer server1
• stopServer TranslatorServer
• startServer TranslatorServer
• startServer server1

Installing Business Process Accelerator Framework extension

The Business Process Accelerator (BPA) Framework extensions contains the code and configuration to bridge IBM Lotus Forms, WebSphere Portal and a workflow engine, such as IBM WebSphere Process Server.

To install the BPA Framework:

1. Unzip ibm.bpa.installer.packaging-XXXX.zip into a folder on your machine, such as c:\BPA. Throughout these instructions, the installation directory is referred to as [INSTALLDIR] Once the BPA framework extensions are unzipped and installed, you will have the [INSTALLDIR]/redist folder and other files in the BPA folder.

Now the BPA Framework must be installed and configured into its specific deployment directory. This directory is pre-configured to be:

• Windows – c:\ibm\Lotus Forms\bpa
• Unix – /ibm/LotusForms/bpa

Throughout these instructions, the deployment directory is referred to as [DEPLOYDIR]. If you need to change the deployment directory, you need to update the panel called "Initialize parameters for servlets" within WebSphere Application Server's administration console for the Enterprise Application called BPA Server. However, this EAR is not available until after the section called "Updating the WebSphere Application Server (WAS) administrative console for WebSphere Process Server" is complete.

2. Install the base BPA Framework environment by copying the contents of [INSTALLDIR]/redist/core into the deployment directory folder. You will end up with the following folders: [DEPLOYDIR]/configuration, [DEPLOYDIR]/extensions, and [DEPLOYDIR]/repositories.

3. Configure the core by modifying [DEPLOYDIR]/extensions/config/Primary.properties.

• The base_host property must point at the fully qualified name of the box.
• The base_port property must point at the port number of the server.

Note: If you have a different topology than a single computer. You will need to change additional parameters within this file.

At this point, you can set which document repository and workflow engine to use. There are many products that support the Quickr REST API, for example: IBM Lotus Quickr, IBM Content Manager, and IBM FileNet. To use a repository based on a REST API (whether it is IBM Lotus Quickr, IBM Content Manager, or IBM FileNet), configure the following properties:

4. Modify the file [DEPLOYDIR]/extensions/config/Primary.properties:

• ibm.TemplateMap.defaultrepo.map.defaultrepo_host={bpaserver_host}
• ibm.TemplateMap.defaultrepo.map.defaultrepo_port={bpaserver_port}
• ibm.TemplateMap.defaultrepo.map.defaultrepo_auth=BASIC
• ibm.TemplateMap.defaultrepo.map.defaultrepo_username=wasadmin
• ibm.TemplateMap.defaultrepo.map.defaultrepo_password=masque
• ibm.TemplateMap.defaultrepo.map.defaultrepo_url={bpaserver_baseurl}/wfsp/repo/dm/atom/

a. Change the defaultrepo_host entry to the fully qualified name of the server containing the repository. Note: This will be resolved on the bpaserver_host computer.
b. Change the defaultrepo_port to the port of the server that contains the repository.
c. Change the defaultrepo_auth to either BASIC or DIGEST, depending on the authentication needed .
d. Change the defaultrepo_username to the user name of the user that can access all the files in the repository.
e. Change the defaultrepo_password to the password of the user that can access all the files in the repository.
f. Change the defaultrepo_url to the appropriate URL. You can find examples of appropriate URLs at: http://quickserver/dm/atom.
5. If you don't have an existing, supported, document repository, the BPA Framework ships with a simple, file system based repository. This repository is not meant for high production use. Install the repository provided with the BPA Framework by copying the contents of [INSTALLDIR]/redist/file_system_repo into [DEPLOYDIR]. There are several repositories that will be used which are located in the [DEPLOYDIR]/repositories folder.

There are many different workflow engines used by the BPA Framework. You may install your own workflow engine, or use the complete bridge to IBM WebSphere Process Server provided.

6. To install the WebSphere Process Server workflow engine, copy the contents of [INSTALLDIR]/redist/ibm_process_server into [DEPLOYDIR]. You will end up with a folder called: [DEPLOYDIR]/extensions/workflow_wps.

Deploying sample forms

The Business Process Accelerator Framework ships with some predefined forms. You can use these forms as the basis for creating your own forms.

To deploy sample forms:

1. Copy the [INSTALLDIR]/samples/LoanApplication/repositories into the [DEPLOYDIR] directory. Once the sample repository is installed, you will have a [DEPLOYDIR]/repositories/forms/LoanApplication folder containing several files.

Updating the WebSphere Application Server administrative console for WebSphere Portal and installing the BPA Framework EAR file for WebSPhere Process Server

The WAS administrative console is used to create users and groups, and to deploy the BPA Framework EAR file.

Before you begin

Ensure you are logged into the WAS administrative console for the WebSphere Process Server (server1).

To updated the WAS administrative console for WebSphere Process Server, first create a group called BPAAdmins:

1. Expand Users and Groups.
2. Choose manageGroups.
3. Click Create... to create a new group.
4. Set BPAAdmins as the new group name and click Create.
5. Add your administrative users to the new group. Administrative users can monitor the components within the server.

Now create a BPADeployers group and add your deployer users to it. Deployer users will use the Eclipse tool to publish forms and metadata to the server. Ensure you add the BPAAdmins group as a member of the BPADeployers group.

5. Expand Users and Groups.
6. Choose manageGroups.
7. Click Create... to create a new group.
8. Set BPADeployers as the group name and click Create.
9. Go to the Members tab and click Add Groups...
10. Click Search and select the BPAAdmins group.
11. Click Add and Close.

The following steps describe how to deploy the BPA Framework EAR file using the WAS administrative console.

12. Go to Applications and expand the section.
13. Select Install New Application.
14. Browse to ibm.bpa.server.ear.packaging-XXXX.ear, located at [INSTALLDIR]/redist and click Next.
15. Leave all settings in "Step 1: Select installation options" and click Next.
16. In "Step 2: Map modules to servers", click the checkbox beside Lotus Forms Services Platform WAR.
       a. Choose the WebSphere:cell=XXX,node=yyyy,server=zzz that is your WebSphere Process Server and click Apply.

The module is now assigned to the WebSphere Process Server. Click Next.

17. Leave all settings in "Step 3: Map virtual hosts for Web modules" and click Next.
18. Click Finish in "Step 4: Summary".
19. Click Save directly to the master configuration.
20. Go to your Process Server [INSTALLDIR]\profiles\serverName\installedApps\cellName\TaskContainer_nodeName_serverName.ear file and copy the taskejb.jar file to Process Server's [INSTALLDIR]profiles\serverName\installedApps\cellName\BpaServer.ear\wfsp.war\WEB-INF\lib folder.
21. Go to your Process Server [INSTALLDIR]\profiles\serverName\installedApps\cellName\BPEContainer_nodeName_serverName.ear file and copy the bpecontainer.jar file to Process Server's [INSTALLDIR]profiles\serverName\installedApps\cellName\BpaServer.ear\wfsp.war\WEB-INF\lib folder.
22. Go to your Process Server [INSTALLDIR]\ProcessChoreographer\client and copy the bpe137650.jar and task137650.jar to Process Server's [INSTALLDIR]profiles\serverName\installedApps\cellName\BpaServer.ear\wfsp.war\WEB-INF\lib folder.

Starting and testing the BPA Framework server

Use the WebSphere Application Server (WAS) administrative console to start and test the BPA Framework.

To test the BPA server:

1. Expand Applications.
2. Choose Enterprise Applications and click the checkbox beside BPA Server.
3. Click Start. To test if the server is working properly, go to [bpaserver_baseurl]/wfsp/bpa/rest/currentuser/workflow (for example, http://portalServer:10040/bpaserver/wfsp/bpa/rest/currentuser/workflow). You must log in with a username associated with the BPAAdmins group. You should see a basic HTML page that shows the further REST actions you can run.

Note: If you do not see the HTML page, check the following log files:

• [Process Server Profile Dir]/logs/server1/SystemOut.log
• [Process Server Profile Dir]/logs/server1/SystemErr.log

Installing the Forms View Portlet

The Forms View Portlet provides the ability to display forms and to communicate with other portlets. The steps below show how to install the Forms View Portlet using WebSphere Portal.

To install the Forms View Portlet:

1. Log on to WebSphere Portal as an administrative user.
2. Go to the Administration page.
3. Under Portlet Management, click Web Modules.
4. Click Install.
5. Click Browse, go to your installation directory and find [INSTALLDIR]/redist/portlets/forms_view/ibm.integrations.portlets.form-3.5.1.X.war.
6. Click Next and then Finish.

Installing the Forms List Portlet

The Forms List Portlet provides a listing of all forms the current user can access to start processes. The instructions below describe how to install the Forms List Portlet using WebSphere Portal.

To install the Forms List Portlet:

1. Log on to WebSphere Portal as an administrative user.
2. Go to the Administration page.
3. Under Portlet Management, click Web Modules.
4. Click Install.
5. Click Browse, go to your installation directory and find [INSTALLDIR]/redist/portlets/forms_list/ibm.bpa.ui.portal.form.list-XXXX.war.
6. Click Next and then Finish.

Installing the IBM Lotus Forms Designer publish plugin

The Designer publish plugin is used to publish a Lotus form into the document repository, and is used to configure the association (or mapping) between the form and the underlying workflow engine.

To install the Designer publish plugin:

1. Install by copying the contents of the [INSTALLDIR]/redist/eclipse/publishing folder into the installation directory to C:/Program Files/IBM/Lotus Forms/Designer/3.5/platform/eclipse/dropins. Once installed, you will have the following file in your Designer directory: C:/Program Files/IBM/Lotus Forms/Designer/3.5/platform/eclipse/dropins/com.ibm.forms.designer.tools.extension.bpapublishing_XXX.jar

Installing WebSphere Integration Developer Forms Generation plugin

The WebSphere Integration Developer (WID) Forms Generation plugin provides the ability to generate a basic form from a human task in a workflow diagram.

To install the WID plugin:

1. Install by copying the contents of the [INSTALLDIR]/redist/eclipse/WID folder into C:/Program Files/IBM/WID62/plugins.

Building a sample portlet page

To test a complete installation, build the following sample page that wires together the portlet and displays a form.

1. Setup an instance of the Forms View Portlet using the WebSphere Application Server administrative console for WebSphere Portal.

a. Go to the Configure menu item.
b. Expand Advanced.
c. Select the radio button for Display blank portlet.
d. Set the Webform Server URL to: [translatorLocation]. For example, the translator location could be: http://myTranslator:8085/translator.
e. Click Save.

2. Test the portlet by clicking Edit Shared Settings.
a. In the Form URL, enter: [bpaserver_baseurl]/wfsp/bpa/rest/repos/forms/welcome.xfdl.
If the installation was completed correctly, you will see a simple form displayed.