talkdata Business Process Management

Installation HowTo:

A Step-by-step Visual Approach to the Installation and Configuration of

Lombardi Teamworks TeamWorks Version 6n on JBoss with SQL-Server 2005

By

Gary Samuelson

talkdata Business Process Management

FORWARD................................................................................................................................................... 1 SOFTWARE & DOCUMENTATION ....................................................................................................... 2

Required Software .................................................................................................................................. 2 Recommend Software ............................................................................................................................. 2 Recommending reading .......................................................................................................................... 2

SQL SERVER 2005 EXPRESS INSTALLATION AND SETUP ............................................................ 3 SQL Server 2005 Express Installation.................................................................................................... 3 SQL Server 2005 Express TCP/IP Connection Configuration ............................................................. 13

TEAMWORKS DATABASE SETUP ...................................................................................................... 16 Create a “teamworks” Database user ................................................................................................. 16 Create TeamWorks Database(s)........................................................................................................... 20

TEAMWORKS INSTALLATION ........................................................................................................... 28 Create Teamworks Directory ............................................................................................................... 28 Launch the Teamworks Installer .......................................................................................................... 28

POST INSTALLATION DATABASE SCRIPTS.................................................................................... 37 Process Server Database Loading Scripts............................................................................................ 37 Performance Server Database Loading Scripts ................................................................................... 38

POST INSTALLATION TEAMWORKS SYSTEM COMPONENTS ................................................. 39 ENABLE TEAMWORKS ADVANCED FEATURES AND MODELING THEME........................... 42

Advanced Features ............................................................................................................................... 42 Teamworks Modeling Theme................................................................................................................ 42 Teamworks Modeling Theme................................................................................................................ 43

TEAMWORKS APPLICATION INSTALLATION ERRATA............................................................. 44 Process and Performance Server Installation Database Parameters: ................................................. 44 Database Loader Script Properties Settings ........................................................................................ 44 Application Domain Configuration Fixes............................................................................................. 45 TeamWorks Authoring Environment Help System................................................................................ 46

ABOUT THE AUTHOR............................................................................................................................ 47

Forward

This document is supplemental to and does not intend to replace Lombardi’s own installation instructions. I wrote this chapter because I was receiving more than a few calls from people who were having install troubles since the introduction of schemas and “named” instances in SQL-Server 2005. This document also helps break out the installation into a simple, illustrated list of steps which may be slightly less intimidating than paging through a formal guide.

The intent of this document is to get a new Teamworks developer up and running quickly. Instructions are visually oriented, show clear examples, and are geared towards guiding the new developer through a complete, stand alone, desktop installation.

Though these instructions may serve equally well for setting up a shared, team environment, security and access configuration(s) are not covered. I intend to address these details in a later chapter.

A quick word on Lombardi’s new “express” installer –

The most efficient method for setting up a local Teamworks environment is to use the v6.1 express distribution. This new installer offers everything including an “express” MS-SQL database. An entire Teamworks system (both client and server) is effortlessly installed onto your desktop computer with the click of a single button!

However…

The express installer does not provide a full process server portal environment similar to that found within a regular installation. Missing from the express install is the “development” configuration (exploded war) of the process portal.

So, if you’re working on both process and portal, the express install will not fill your development needs. On-the-other-hand, when working strictly within the Authoring environment (e.g. no jsp or css) - I recommend the express distribution.

1

Software & Documentation

Required Software

1. Lombardi Teamworks 6.1 Installer

Teamworks-6.1-Installer.exe

2. MS SQL-Server 2005 Express

http://go.microsoft.com/fwlink/?LinkId=65212

NOTE: Make sure you install with “mixed authentication” – select the option allowing both Windows and SQL Server Authentication (you will see this choice during SQL-Server installation).

3. SQL Server Management Studio Express

http://go.microsoft.com/fwlink/?LinkId=65110

4. Download and install the .NET 2.0 framework (if not already installed on your computer).

http://www.microsoft.com/downloads/details.aspx?familyid=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en

Recommend Software

1. A good SQL tool that uses the very same JDBC drivers as JBOSS and Teamworks. This is important so that you can both test connectivity and develop SQL statements with confidence.

DbVisualizer is a very good SQL tool but it costs a little money: http://www.minq.se/products/dbvis/ SQuirreL SQL is another good SQL tool and it’s FREE: http://www.squirrelsql.org/index.php?page=screenshots Eclipse also has a very nice SQL pluggin and it’s FREE: http://www.eclipse.org/ganymede/

Recommended reading

1. Teamworks 6 Enterprise Release 6.1 Installation and Configuration Guide for JBoss Windows

Teamworks-6.1-Installation_and_Configuration_Guide_for_JBoss_with_Windows.pdf

2. Teamworks 6 Enterprise Release 6.1 Administration Guide

Teamworks-6.1-Administration_Guide.pdf

2

SQL Server 2005 Express Installation and Setup

SQL Server 2005 Express Installation

1. Run SQLEXPR32.EXE installer.

SQLEXPR32.EXE

If you get prompted to first install a “.net” upgrade, then follow the installer’s advice. All required software links should be listed above in the previous section.

After a few administrative user-acceptance dialogs, you will see this welcome message:

3

2. Click the “next” button and the installer will then run a compatibility and requirements check on your environment. If all goes well, you should see the following:

The most common missing requirement is an out-of-date or missing “.net” component. I listed a link to this component in the previous section. You may need to stop the installation and install or upgrade “.net”.

4

3. Uncheck the “hide advanced configuration options”.

This is a critical step in the installation process!

Don’t forget to un-check this option.

You DO NOT want to hide advanced configuration options!

4. Install the following components

5

5. Instance Name

I recommend you use the “Default instance”. If this isn’t your first installation, click the “Installed instances” button to review the other servers currently running on your desktop.

Click “OK” to return the Instance Name dialog:

NOTE: The “TEAMWORKS_1” instance was created by a previous “Teamworks Express” installation.

6

6. Existing Components

Accept defaults and recommendations regarding existing components.

7

7. Service Account

I recommend you select built-in system account with “Network service” access. Using the “domain user account” may run you into a few pitfalls regarding your enterprise domain server and access. The help documentation provides further details on this part of the installation.

To be clear… I recommend using the “built-in System account” with “Network service” access.

8

8. Authentication Mode

Make sure that you select “mixed mode” authentication!

Type in the “sa” user’s password – “teamworks” is a good password for this initial installation. You can change this later if needed.

9

9. Collation Settings

The default setting should be “case insensitive” – Make sure that you do not setup a case sensitive server because this may cause some later runtime issues with Teamworks (Teamworks is not certified to run on a case-sensitive server).

I set my database to use the following: SQL_Latin1_General_CP1_CI_AS.

The options below reflect that this is the 2nd SQL Server installation on my desktop computer. The previous installation used “Latin1_general”, case-insensitive, for use with 1252 Character Set.

10

10. Configure User and Administrator Accounts

NOTE: The second option for Vista users. You may need to check “add user to the SQL Server Administration role”. Looks like Vista users need this for local desktop database administration. I do not use Vista so you’re on your own here – but please let me know how your Vista platform works with this installation guide.

I use the following settings:

11

11. Error and Usage Report Settings

I leave these unchecked…

12. Ready to Install

Click the Install button.

12

SQL Server 2005 Express TCP/IP Connection Configuration If you haven’t already noticed, SQL Server default configuration does not allow TCP/IP connectivity. This means that, without enabling TCP/IP, you won’t be able to connect to your SQL server with anything other than MS SQL Server Management Studio Express (aka MS Studio Express).

1. Start SQL Server Configuration Manager (should be available via the “start-programs-MS SQL Server 2005”)

2. Expand “SQL Server network Configuration” and select “Protocols for MSSQLSERVER”.

3. Make sure “TCP/IP” is enabled

13

4. Right-click the “TCP/IP” protocol and select “properties”

5. Select the “Protocol” tab

a. Under “general”, make sure “enabled” is set to “yes”

6. Select the “IP Addresses” Tab

a. Set your IP address and ports

i. Make sure you choose available ports! If you’re running a 2nd MS-SQL server 2000 on your computer, you’ll need to use a different port number other than default (and this will later haunt subsequent TeamWorks installations if you forget to use this port number during TeamWorks JDBC setup/configuration).

ii. I used both “localhost” and “127.0.0.1” (they’re the same – one using a name, the other the IP number. I was testing configurations…)

iii. I used port number 1433, which is the default MS-SQL Server port number. You don’t have to use this port if it’s already taken by another application – just remember to be consistent during the Teamworks (TW) installation.

14

iv. Click “Apply” and “OK” on all windows until you’re back to the main “SQL Server Configuration Manager” console.

7. Restart SQL Server. If you get an error, check the error event posted into WinXP (or server) event viewer. Most likely you need to switch ports until you find one not in use by another application.

8. SQL Server Express setup should now be complete and ready for your TeamWorks databases.

15

Teamworks Database Setup

Create a “teamworks” Database user

Connecting to The SQL Server Database Before creating the databases, a SQL Server user must be created to own the two Teamworks databases:

1. From the Windows Start menu, launch the "SQL Server Management Studio" under the Microsoft SQL Server 2005 folder. Log in to the appropriate server instance.

2. For a basic localhost installation – here is what the “connect to server” dialog should look like

Notice that I’m using “windows authentication” here. I could also have selected “SQL Server Authentication” and used my “sa” account.

NOTE: You may need to reference your port number in “Server name”. Example: localhost, 1453 (if using a port other than default).

16

3. If you’re logging into a server with the "Named instance" option – for example if you setup an instance called “tw61” on server “BLAZER”, your “connect to server” “Server name” would look like this:

Server name: BLAZER\tw61,1533 [server]\[instance],[port number]

NOTE: In this example I’m using my local admin and Windows Authentication

Verify That SQL Server Authentication is Enabled 1. Right click on the top level Server folder, and click on the "Properties" menu item.

2. Click on the "Security" link, and make sure that the "SQL Server and Windows" option is selected for Server Authentication type.

17

Create Teamworks login 1. Navigate to the Security folder under top level Server folder, and right click on

"Logins".

2. Click the "New Logins..." option from the right-click menu.

3. In the New Login Properties page, enter the user name "teamworks" (all lowercase). Click on the "SQL Server Authentication" option, and enter the password "teamworks".

a. NOTE: I recommend using a user/pass of “teamworks/teamworks”. This is a well known user/pass setup on most initial Teamworks installations. I recommend things be kept simple at this point to insure reasonably uncomplicated trouble-shooting if the installation doesn’t go well.

18

4. Uncheck the "Enforce password policy", this will allow you to have a password

that is the same as the login name. If you don't want to disable this password policy you will need to choose a different password.

5. Leave other options default

Default database: master Default language: <default>

6. Click "OK" to finish.

19

Create TeamWorks Database(s) Make sure that you’re logged in as “sa” and that this user’s login is set to use the “dbo” schema by default. Unless somebody changed your new SQL Server database, the default settings for the SA should already be using the “dbo” schema.

1. Connect to SQL Server using your “sa” user/pass:

2. Verify that the “sa” user is setup to use the “dbo” schema (this is the default).

20

3. You will create two databases, both following the same instructions with the exception of

database name. The first database will be called:

• twProcessDB_61

I recommend you use the following naming pattern:

twProcessDB_[dev cycle]_[teamworks version]

Example1 : twProcessDB_61 (note: I left out the “dev cycle” because this installation is running on a local MS-SQL server.)

Example 2: If this were a development server installation the name would be twProcessDB_dev_61

• twPerformanceDB_61

See above for naming pattern.

21

Create Database: twProcessDB_61 1. In SQL Server Management Studio, navigate to the Databases folder under the top

level Server folder, right click and select the "New Database..." menu item.

2. In the New Database properties page, enter the name of the Process Server database

(e.g., "twProcessDB_61).

3. Leave the “Owner” setting as “default”

4. Click “OK” to finish.

22

Create User for Database: twProcessDB_61 1. Navigate to the "Security -> Users" folder under that new twProcessDB_61 database

folder.

2. Right click and select the "New User..." menu item.

3. In the New User properties page, type the teamworks user id (e.g., "teamworks") into

both the "User name" and "Login name" input fields.

23

4. Leave the following alone for now

a. “Default Schema”

b. Schemas owned by user

c. Role members

5. Click "OK" to finish.

24

Create Schema for User “teamworks”: twProcessDB_61 1. Navigate to the "Security -> Schemas" folder under that new database folder

2. Right click and select the "New Schema..." menu item.

called "teamworks" and associate it with the teamworks user id (e.g., "teamworks") by typing "teamworks'

4.

3. In the New Schema properties page, create a new schema

into both the Schema Name and Schema Owner input fields.

Click "OK" to finish.

25

Associate teamworks Schema to teamworks User 1. Navigate to the "Security -> Users -> teamworks" folder under the new database

folder (e.g., " twProcessDB_61")

2. Right click the teamworks user and select "Properties" menu item.

3. In the "Default schema" textbox, enter (or browse and select) the "teamworks"

schema as the default.

4. In the section "Schemas owned by this user", select the "teamworks" schema, if not already selected.

5. In the section "Database role membership", select the "db_owner" role.

6. Click "OK" to finish.

26

27

Database Setup: twPerformanceDB_601 Follow the same instructions (above) for setting up the performance server DB, “twPerformanceDB_61”

Teamworks Installation

The Teamworks installation and configuration guide covers most steps and issues. This guide may have a few more pictures – Lombardi’s document sufficiently covers the material otherwise.

Before you begin, please review “Teamworks Application Installation Errata”.

Create Teamworks Directory Create the following directory. I usually use a naming pattern of:

teamworks_[version]_[platform]

For this installation we’ll use:

C:\ teamworks_61_jboss_full (Note: I’m running this alongside an express installation to compare differences)

Since you may end up running multiple versions of Teamworks, I recommend you follow this naming convention to avoid confusion between installed Teamworks versions.

Launch the Teamworks Installer

Teamworks-6.1-Installer.exe

xecutable, self-extracting package. If you’re this file and

stall.exe” from the exploded package. This way you’re not required to wait for package extraction per installation.

Note: The Teamworks installer is an eplanning to install or re-install a few of these, you might want to first extractthen directly run the “in

28

29

hoose Teamworks Products Click through the licensing agreement and select the products you whish to install. In this

g except Organizational Management.

C

example I’m installing everythin

Select Application Server

29

Process Server

Process Server Options

familiar with the r own computer’s

stallation.

Use the defaults. I don’t recommend changing these values unless you’re consequences. The “Application Server Host” value should represent youname. For example, my host computer is named “blazer”.

Note: The “Multicast Address” will most likely not be used for a desktop inHowever, leave the default value.

Process Server Ports

30

Performance Server Options

ddress” will most likely not be used for a desktop installation. However, leave the default value. Note: The “Multicast A

Performance Server Ports

31

Mail Options I recommend you leave this alone for a desktop installation. Using your company’s SMTP

ing admin. here could inadvertently lead your desktop installation into sending a high volume of unnecessary emails to an unsuspect

NOTE: Funny if there was a “yourcompany.com” domain out there receiving emails? Well there is! Hopefully they require authentication on their SMTP server…

32

Database Connection Parameters

Make sure to use the following values

Database: Microsoft SQL Server

Database Host: localhost I recommend using “localhost” for your database host because we’re running a local SQL-Server DB. It’s best to avoid any issues, whatsoever, with Teamworks/Jboss discovering your database.

It’s very, very important that you DO NOT SELECT “Windows Authentication”.

Test your connections before continuing. Teamworks will not work if the test fails.

Process Server Database Parameters

33

Performance Server Database Parameters

34

Install Folder (Installation Directory)

Choose Shortcut Folder I recommend new shortcut menu items per installation that reflect product version.

35

Review Parameters and Install Review your installation settings and start the installer.

Install Complete

36

Post Installation Database Scripts

Process Server Database Loading Scripts Run the following scripts from the windows cmd.

Note: Don’t forget to add the “mssql” option to the script comments.

1. DBSLoad.bat mssql

2. DBSpLoad.bat mssql

3. DBLoad.bat mssql

37

38

erformance Server Database Loading Scripts Run the following scripts from the windows cmd.

the script comments.

P

Note: Don’t forget to add the “mssql” option to

1. DBSload.bat mssql

2. DBLoad.bat mssql

38

39

Post Installation Teamworks System Components

We’re now going to startup the process server and Teamworks Authoring Environment (TA

cess server via the windows start menu

E).

1. Start Teamworks Pro

2. Start the Teamworks authoring environment

3. Click the little people at the bottom of the screen to enable: Note: I generally enable all the features in the Teamworks Authoring Environment (TAE)

• Process Analyst Capability

• Process Modeler Capability

• Developer Capability

• Report Designer Capability

4. Go to the workbench by clicking the arrow at top-right.

5. Right click the TeamWorks top folder and select “import”

ystemData.zip 6. Browse to the following imports directory and select TWS

[installation]\imports\TWSystemData.zip

40

Select TWSystemData.zip and import into the Teamworks library

Click “finish” to complete the import process.

41

Enable Teamworks Advanced Features and Modeling Theme

Advanced Features From the Teamworks Authoring Environment (TAE) click the Window top-menu item and select Preferences:

Select: Window -> Preferences

From the Teamworks capabilities section, select Capabilities. Turn on all the Teamworks Advanced Features:

42

43

eamworks Modeling Theme Select Appearance and set the Modeling Theme to “Teamworks Theme” T

43

TeamWorks Application Installation Errata

Note: I discovered these issues with Teamworks v6.0.1 and I’m not sure if these issues were fixed with the v6.1 release.

Process and Performance Server Installation Database Parameters:

1. Database name and instance must be specified in lower case

The Database name and instance must be specified in lower case or you will get a host named not found error when testing the connection.

2. Database double-slash bug - must test with “\” but then use “\\”

When specifying a DB instance name, use a single back slash between the hostname and instance when testing. Once you have verified that the connection test is successful, add a second backslash between the hostname and instance.

a. Example: use “mysqlserverhost\one” for testing but then add the second slash before moving forward to next screen. The final value should be (for example) “mysqlserverhost\\one”.

Failure to add the second slash (“\\”) will cause problems later in the configuration files that will cause errors during Teamworks server startup.

Example Connection String for JSQLConnect driver with double slashes (“\\”):

jdbc:JSQLConnect://myServer.myDomain.com\\one/portNumber=0/database=TW_Process_601/asciiStringParameters=false

NOTE: Though a single slash will “test connection” as “OK” during installation, you will encounter runtime errors without the “\\” between db server and db instance!

Database Loader Script Properties Settings

1. Before running the scripts to create the tables for the Process and Performance databases, open the DBLoad.properties file and make sure that there are two back slashes between the database host name and instance name in the jdbc connection string.

Example dburl in the “DBLoad.properties” file

dburl=jdbc:JSQLConnect://myServer.myDomain.com\\one/portNumber=0/database=TW_Process_601/asciiStringParameters=false

44

Application Domain Configuration Fixes A minor annoyance of the Teamworks installation is that it simply assumes, for better or worse, the correct application domain settings. You may discover that debugging is practically impossible because your browser can’t find “http://myserver:1100” whereas it

You y

myserve

On Updating the Server URLs in the configuration files.

should be using “http://mysever. mycompany.com:1100”.

ma need a configuration that includes the server’s full domain:

r.myCompany.com

You

In [insta ver).

1. 00Static.xm

2. 50AppSe e

3. 80EventMana

4. 99Local.xml

5. 99S

00Static.xml:

will need to update the following files:

llation]\process-server\resources\config\system (and same for performance ser

l (1 instance)

rv r.xml (2 instances)

ger.xml (1 instance)

(10 instances)

harepoint.xml (not really necessary unless using MS share-point integration)

Add the full domain to all server references.

Example from

<url>jnp:// myServer.myDomain.com:9100</url> (note: this is one of the references I fixed)

The original reference was:

<url pnetw

>jn :// myServer:9100</url> (note: this reference may not work on most enterprise orks)

I used a grep search/replace tool to find and update all occurrences of the server reference.

45

TeamWorks Authoring Environment Help System Teamworks 6 uses Eclipse 3.2. And, Eclipse has trouble accessing its help system on corporate networks. The problem has to do with an inability to resolve a connection into its own help system.

My workaround was to configure Eclipse (TeamWorks authoring environment) to use an external browser (I chose Firefox). I then configured Firefox to correctly find its way around the enterprise firewall/proxi configuration.

46

About The Author

Gary Samuelson is the Director of Systems Architecture at TalkData Consulting. Somewhat jack-of-all-trades with over 19 years experience in information technologies, he has turned hfocus on BPM - the

a is

new catchphrase for integrated business/operations support systems and ng

His website:

http://Garysamuelson.com

ERP (aka BSS/OSS). In addition to his BPM consulting work he spends his free time writion technology and building custom desktop and server machines for use in video post-production and computer game development.

47