Integrating IBM Business Process Manager with SharePoint

Pre-requisites:
Software:

SharePoint Server requirements

To run IBM BPM for Microsoft SharePoint on a server system, the server must have the required software installed and running. Client systems must have Microsoft Internet Explorer installed to access SharePoint sites.

Operating system:

Microsoft Windows® Server 2008 R2 or with SP2

SharePoint 2010 prerequisites:

Microsoft Internet Information Services (IIS)

Microsoft .NET Framework 3.5 SP1

ASP.NET 2.0 enabled in IIS

SharePoint Server 2010:

Microsoft SharePoint Server 2010, 64-bit edition. The 64-bit edition requires a 64-bit edition of the operating system.

On Windows Server, Microsoft Internet Information Services (IIS) must be enabled using the Application Server (ASP) option. After the .NET Framework is installed, ASP.NET 2.0 can be enabled using the following steps.

1. In the Windows Server Control Panel, click Administrative Tools.
2. Click Configure Your Server Wizard.
3. Click Next twice.
4. In the Configure Your Server Wizard - Server Role window, select Application server.
5. Make sure that the Application Server role is enabled with IIS and ASP.NET, and that Configured is set to Yes for the Application server role.

Hardware:

The suggested hardware requirements are the minimum required to run IBM Business Process Manager for Microsoft SharePoint Add-On.

• Intel® Pentium® 4, 2.0 GHz processor
• 1-2 GB RAM
• About 50 MB of free disk space for the application

Installing IBM BPM for Microsoft SharePoint

There are 3 ways the IBM BPM for Microsoft SharePoint can be installed:

• Running the IBM BPM for Microsoft SharePoint installer - Install IBM Business Process Manager for Microsoft SharePoint Add-On using the installer program.
• Running the silent installer - Install IBM Business Process Manager for Microsoft SharePoint Add-On silently using a command.
• IBM BPM for Microsoft SharePoint directories and files installed on the server and the client - The IBM Business Process Manager for Microsoft SharePoint Add-On installer program creates several important directories and files on the Microsoft SharePoint server system and your local system.

Running the IBM BPM for Microsoft SharePoint installer:

Procedure:

1. On the SharePoint Server system, double-click the IBM-BPM-for-Sharepoint-x64.exe installer file.
2. In the installer Welcome window, click Next to continue the installation.
3. Click to select the terms of the license agreement.
4. If your IIS installation is not on drive C:\ or if you are not using port 80, you must change the default directory information. Click Change and then navigate to the directory where the web.config file is located.
5. The next window verifies the security policy directory. Click Change to modify the security policy directory. In this window, you can also enable a security policy for the SharePoint server. The installer program modifies the existing IIS web.config file by adding the IBM BPM for Microsoft SharePoint application files to the list of allowed DLLs. Optionally, an example security policy file can also be added to the web.config file to help you configure IBM BPM for Microsoft SharePoint for your environment. If you want to add the security policy to the web.config file, select the Enable this policy in SharePoint option.
   Note: Selecting the Enable this policy in SharePoint option changes the security policy for all of your SharePoint web pages, and might break other programs installed on the SharePoint server. If you have other programs installed, do not select the Enable this policy in SharePoint option. Instead, you must manually modify the SharePoint security policy to add support for IBM BPM for Microsoft SharePoint.
6. In the SharePoint Server URL window, enter the URL of the SharePoint Server using the syntax http://servername.
7. In the IBM Business Process Manager Information window, enter the URL and port number of the IBM Process Server using the syntax http://servername:port. The IBM Process Server information is used to configure SharePoint site templates to work in your environment. Select the Authentication Mode, either Basic or Integrated.
   • If you select basic authentication mode, you must also enter your user name and password.
   • If you select integrated authentication mode, the Username and Password fields are not available.
   Note: IBM Business Process Manager supports both NTLM-based and Kerberos-based automatic login, also referred to as single sign-on (SSO). The SSO function reduces configuration effort and simplifies the authentication process by using your Windows credentials to authenticate with IBM Business Process Manager. The NTLM and Kerberos protocols allow you to automatically log on to IBM Process Portal Console, IBM Process Admin Console, IBM BPM for Microsoft Office, and IBM BPM for Microsoft SharePoint. IBM BPM for Microsoft SharePoint supports SSO with IBM Business Process Manager through the Kerberos protocol. NTLM is not supported for IBM BPM for Microsoft SharePoint. For more information, see Configuring integrated authentication in IBM BPM for Microsoft SharePoint.
8. The installer program is now ready to begin writing the IBM BPM for Microsoft SharePoint files. You can click Back to change the installation settings, or click Install to continue.
9. During the installation process, the status bar indicates progress towards completion, which typically takes several minutes.
10. When the installation is complete, click Finish. The installer program restarts IIS so that the IBM Business Process Manager services and web parts are available for immediate use.

Running the silent installer

Before running the silent installer, make sure that your system meets these requirements:

• Remove any earlier versions of the product.
• Prerequisite client software is installed.

Run the IBM-BPM-for-Sharepoint-x64.exe install command, using the following command arguments to perform the silent configuration:

• WLESERVERURL : Specifies the URL of the IBM Process Server. For example: http://MyServer:PortNumber.
• PATHTOVIRTUALDIRECTORYWEBCONFIG: Specifies the path to the virtual configuration directory.
• PATHTOSECURITYPOLICYDIR: Specifies the path to the security policy directory.
• ENABLESHAREPOINT: Enables the policy in SharePoint. Valid values are TRUE or FALSE. The default value is FALSE.
• SHAREPOINTURL: Specifies the SharePoint URL.
• WLEAUTHMODE: Sets the authentication mode of the IBM Process Server. Valid values are Basic and Integrated. The default value is Integrated.
• WLEUSERNAME: Indicates the username to authenticate to the IBM Process Server. This argument is required for basic authentication mode only.
• WLEPASSWORD: Indicates the password to authenticate to the IBM Process Server. This argument is required for basic authentication mode only.
• INSTALL_MODE: Specifies the installation mode. Valid values are Install or Upgrade. The default value is Install.

The following example shows the installation command for basic authentication:

"./IBM-BPM-for-Sharepoint-x64.exe" /s /v"/qn SHAREPOINTURL=http://myserver ENABLESHAREPOINT=TRUE WLEAUTHMODE=Basic WLEPASSWORD=tw_admin WLEUSERNAME=tw_admin"

The following example shows the installation command for integrated authentication:

"./IBM-BPM-for-Sharepoint-x64.exe" /s /v"/qn SHAREPOINTURL=http://myserver ENABLESHAREPOINT=TRUE"

To upgrade from an earlier version of the product, add the INSTALL_MODE=Upgrade argument to the command.

IBM BPM for Microsoft SharePoint directories and files installed on the server and the client

The IBM Business Process Manager for Microsoft SharePoint Add-On installer program creates several important directories and files on the Microsoft SharePoint server system and your local system.

These files and directories include web parts and services. The installer program adds files to the SharePoint Server system, and can also modify server configuration files.

By default, IBM BPM for Microsoft SharePoint application files are installed in the following directory:

C:\Inetpub\wwwroot\wss\VirtualDirectories\80\

The subdirectories in this directory contain the program DLLs. For example, the bin\Lombardi.Server.WebParts.dll file enables the Portal web parts function.

The installer program can modify the existing web.config file to add an example security policy. This optional modification can help you configure IBM BPM for Microsoft SharePoint for your environment. The web.config file is updated to point to the new policy file only if you select the Enable this policy in SharePoint option during installation.

The file name of the example security policy file added by the installer program is wss_mediumtrust_lombardi.config. By default, this file is installed in the following directory:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\14\CONFIG

The installer program automatically adds references to wss_mediumtrust_lombardi.config inside the specified web.config file, as shown in this example:

<securityPolicy> <trustLevel name="WSS_Medium" policyFile="C:\Program Files\Common Files\Microsoft Shared\web server extensions\14\config\wss_mediumtrust.config" /> <trustLevel name="WSS_Minimal" policyFile="C:\Program Files\Common Files\Microsoft Shared\web server extensions\14\config\wss_minimaltrust.config" /> <trustLevel name="WSS_Medium_Lombardi" policyFile="C:\Program Files\Common Files\Microsoft Shared\web server extensions\14\config\wss_mediumtrust_lombardi.config" /> . . .

This security policy becomes the current trust level in the web.config file if the Enable this policy in SharePoint option is selected during installation. The trust level entry in the web.config file is shown in the following example:

<trust level="WSS_Medium_Lombardi" originUrl="" />

Post Installation - Configuration

Manually configuring the security policy

During installation of IBM Business Process Manager for Microsoft SharePoint Add-On, if you did not select the Enable this policy in SharePoint option in the security policy installer window, then you must perform the following steps to successfully run IBM BPM for Microsoft SharePoint.

The IBM BPM for Microsoft SharePoint services and web parts do not run until you manually enable the website to use a security policy that allows the installed files to run on the web server. You can enable the policy by setting the trust level in web.config to full(not recommended), or by creating a custom policy file. Creating a custom policy file is the best approach to optimize security while allowing IBM BPM for Microsoft SharePoint to run properly.

If the trust level is currently set to WSS_Minimal, which means that you are using the default contents of the wss_minimaltrust.config file, IBM BPM for Microsoft SharePoint will not run. To run properly, SharePoint web parts and web services require a higher level of permissions than the level provided by the default SharePoint permissions.

You can modify an existing custom security policy file to add the necessary policy information, or you can modify a default policy file. IBM BPM for Microsoft SharePoint provides a policy updater tool to help you modify the policy file and audit the results. Follow these steps to run the policy updater tool. 

Start the policy updater by double-clicking the TeamworksSharePointSecurityPolicyUpdater.exe file. This file is located in the directory where the policy file was created during installation. By default, the policy file location is: 
C:\Program Files\Common Files\Microsoft Shared\web server extensions\14\CONFIG

In the IBM BPM for Microsoft SharePoint Policy Updater window, click Browse and then navigate to an existing policy file that you want to modify. The existing policy file can be a custom file that is already in use, or the default wss_mediumtrust.config policy file. 

The updater tool computes default names for the reformatted existing policy file and the new output file. By saving the original policy file, the tool allows you to compare the original file with the output file, in case the saved original is necessary for future troubleshooting. You can change the default file names, but you must make these changes before clicking Generate. If you enter a file name instead of clicking Browse, the tool computes default file names when you click Generate.

Click Generate. The original policy file is saved to the Reformatted Original File For Comparison file name. The new policy file is saved to the New Security Policy File with strong names file name. You can use a comparison program or utility to compare the original file with the new file. The policy updater tool does not add redundant IBM BPM for Microsoft SharePoint strong names to a policy file that already contains the strong names.
Close the policy updater window when you have finished using the updater tool.

After you have successfully generated the modified policy file, place the new file on the web server and reference the policy file from the web.config file. This step enables the new policy to become the global policy for the website.

Web parts overview

IBM Business Process Manager for Microsoft SharePoint Add-On provides web parts that enable you to view data from IBM Process Portal within a Microsoft SharePoint site.

Using IBM BPM for Microsoft SharePoint, you can perform many of the same tasks in SharePoint that you can do in the web-based IBM Process Portal, including: 

Launch processes from a list of favorites.
View and perform assigned tasks.
Manage in-flight processes, including starting and stopping process instances, viewing process diagrams, and reassigning tasks to balance workload.
View real-time reports showing performance for individuals, teams and business processes.



The following table describes the function of the IBM Process Portal web parts.

Table 1. Web part function

Web part
Function

Saved Search
Displays active tasks from an IBM BPM saved search.
Process Start
Launches IBM BPM processes from a SharePoint site.
ScoreBoard Launcher
Displays commonly used links from IBM Process Portal.
Embedded Web Site
Displays a IBM BPM report or Coach within a SharePoint site. This web part can also display other types of web sites using any valid URL.

Adding web parts to a SharePoint site

Add functions such as saved searches and processes to IBM Business Process Manager for Microsoft SharePoint Add-On by adding web parts to a Microsoft SharePoint site.

The IBM BPM for Microsoft SharePoint installer creates sample templates that use web parts. You can add and modify these templates instead of using the web parts directly, since the web parts rely on the structure of the SharePoint site.

To add web parts to a SharePoint site:

1. Click Site Actions > Edit Page.
2. Go to the web part zone and click Add a Web part.
3. In the Add Web Parts window, expand the tree until you see the Miscellaneous section.
4. Click to select the IBM BPM web parts that you want to add to your SharePoint site.
5. Click Add.

To configure the properties for each web part, click Edit > Modify Shared Web Part.

Configuring integrated authentication in IBM BPM for Microsoft SharePoint

The integrated authentication between Microsoft® Windows® and IBM Business Process Manager for Microsoft SharePoint Add-On allows you to access the IBM BPM for Microsoft SharePoint client more efficiently.

IBM® Business Process Manager supports both NTLM-based and Kerberos-based automatic logon. These authentication modes are also referred to as single sign-on (SSO). SSO reduces configuration effort and simplifies the authentication process by using the credentials of the current Windows user to authenticate with IBM Business Process Manager consoles. The NTLM and Kerberos protocols allow users to automatically log on to IBM Process Portal Console, IBM Process Center Console, IBM Process Admin Console, IBM BPM for Microsoft Office, and IBM BPM for Microsoft SharePoint.

Note: IBM BPM for Microsoft SharePoint supports SSO with IBM Business Process Manager through the Kerberos protocol. The NTLM protocol is not supported for IBM BPM for Microsoft SharePoint.

IBM BPM for Microsoft SharePoint supports integrated authentication by default. During installation, the authentication mode is configured for each site template and the sample IBM Business Process Manager site, using the authentication mode selected in the installer program. A web part can be manually configured to use either integrated or basic authentication. To change the authentication settings, click Edit > Modify Shared Web Part in a page. If you select basic authentication mode, you must specify the authentication credentials for the IBM Process Server, including user name and password. You can encrypt the password that is used for basic authentication. In the web part properties window, click Encrypt Credentials. For help with implementing single sign-on for IBM BPM for Microsoft SharePoint, contact IBM Support.

Using Process Portal with IBM BPM for Microsoft SharePoint

Using IBM Business Process Manager for Microsoft SharePoint Add-On, you can do many things in Microsoft SharePoint that you can do in the web-based Process Portal, including:

• Launch processes from a list of IBM BPM for Microsoft SharePoint processes.
• View and perform assigned tasks.
• Manage inflight processes, including starting and stopping process instances, viewing process diagrams, and reassigning tasks to balance workload.
• View real-time reports showing performance ScoreBoards for individuals, teams and/or business processes.

Process Portal web parts

Using Process Portal web parts, you can view data from Process Portal inside a Microsoft® SharePoint site.

The following table describes the Process Portal web parts.

Table 1. Process Portal web parts

Web part name	Description
Saved Search	Display active tasks from an IBM BPM for Microsoft SharePoint saved search.
Process Start	Launch IBM BPM for Microsoft SharePoint processes from a SharePoint site.
ScoreBoards	Display IBM BPM for Microsoft SharePoint performance data from a SharePoint site.
Embedded Web site