Installation HowTo: talkdata. Lombardi Teamworks. Business Process Management. A Step-by-step Visual Approach to the Installation and Configuration of

Transcription

1 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

2 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 TEAMWORKS DATABASE SETUP Create a teamworks Database user Create TeamWorks Database(s) TEAMWORKS INSTALLATION Create Teamworks Directory Launch the Teamworks Installer POST INSTALLATION DATABASE SCRIPTS Process Server Database Loading Scripts Performance Server Database Loading Scripts POST INSTALLATION TEAMWORKS SYSTEM COMPONENTS ENABLE TEAMWORKS ADVANCED FEATURES AND MODELING THEME Advanced Features Teamworks Modeling Theme Teamworks Modeling Theme TEAMWORKS APPLICATION INSTALLATION ERRATA Process and Performance Server Installation Database Parameters: Database Loader Script Properties Settings Application Domain Configuration Fixes TeamWorks Authoring Environment Help System ABOUT THE AUTHOR... 47

3 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 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

4 Software & Documentation Required Software 1. Lombardi Teamworks 6.1 Installer Teamworks-6.1-Installer.exe 2. MS SQL-Server 2005 Express 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 4. Download and install the.net 2.0 framework (if not already installed on your computer). 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: SQuirreL SQL is another good SQL tool and it s FREE: Eclipse also has a very nice SQL pluggin and it s FREE: 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

5 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

6 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

7 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

8 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

9 6. Existing Components Accept defaults and recommendations regarding existing components. 7

10 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

11 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

12 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 2 nd SQL Server installation on my desktop computer. The previous installation used Latin1_general, case-insensitive, for use with 1252 Character Set. 10

13 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

14 11. Error and Usage Report Settings I leave these unchecked 12. Ready to Install Click the Install button. 12

15 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 startprograms-ms SQL Server 2005 ) 2. Expand SQL Server network Configuration and select Protocols for MSSQLSERVER. 3. Make sure TCP/IP is enabled 13

16 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 2 nd 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 (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

17 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

18 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

19 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

20 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

21 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

22 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

23 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

24 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

25 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

26 4. Leave the following alone for now a. Default Schema b. Schemas owned by user c. Role members 5. Click "OK" to finish. 24

27 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. 3. In the New Schema properties page, create a new schema called "teamworks" and associate it with the teamworks user id (e.g., "teamworks") by typing "teamworks' into both the Schema Name and Schema Owner input fields. 4. Click "OK" to finish. 25

28 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

29 Database Setup: twperformancedb_601 Follow the same instructions (above) for setting up the performance server DB, twperformancedb_61 27

30 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 Note: The Teamworks installer is an executable, self-extracting package. If you re planning to install or re-install a few of these, you might want to first extract this file and then directly run the install.exe from the exploded package. This way you re not required to wait for package extraction per installation. 28

31 Choose Teamworks Products Click through the licensing agreement and select the products you whish to install. In this example I m installing everything except Organizational Management. Select Application Server 29

32 Process Server Process Server Options Use the defaults. I don t recommend changing these values unless you re familiar with the consequences. The Application Server Host value should represent your own computer s name. For example, my host computer is named blazer. Note: The Multicast Address will most likely not be used for a desktop installation. However, leave the default value. Process Server Ports 30

33 Performance Server Options Note: The Multicast Address will most likely not be used for a desktop installation. However, leave the default value. Performance Server Ports 31

34 Mail Options I recommend you leave this alone for a desktop installation. Using your company s SMTP here could inadvertently lead your desktop installation into sending a high volume of unnecessary s to an unsuspecting admin. NOTE: Funny if there was a yourcompany.com domain out there receiving s? Well there is! Hopefully they require authentication on their SMTP server 32

35 Database Connection Parameters Process Server Database 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. 33

36 Performance Server Database Parameters 34

37 Install Folder (Installation Directory) Choose Shortcut Folder I recommend new shortcut menu items per installation that reflect product version. 35

38 Review Parameters and Install Review your installation settings and start the installer. Install Complete 36

39 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

40 Performance 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. DBLoad.bat mssql 38

41 Post Installation Teamworks System Components We re now going to startup the process server and Teamworks Authoring Environment (TAE). 1. Start Teamworks Process server via the windows start menu 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. 39

42 5. Right click the TeamWorks top folder and select import 6. Browse to the following imports directory and select TWSystemData.zip [installation]\imports\twsystemdata.zip 40

43 Select TWSystemData.zip and import into the Teamworks library Click finish to complete the import process. 41

44 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

45 Teamworks Modeling Theme Select Appearance and set the Modeling Theme to Teamworks Theme 43

46 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/asciistring Parameters=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/asci istringparameters=false 44

47 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 whereas it should be using mycompany.com:1100. You ma y need a configuration that includes the server s full domain: myserver.mycompany.com On Updating the Server URLs in the configuration files. You will need to update the following files: In [installation]\process-server\resources\config\system (and same for performance server) Static.xml (1 instance) 2. 50AppServer.xml (2 instances) 3. 80EventManager.xml (1 instance) 4. 99Local.xml (10 instances) 5. 99Sharepoint.xml (not really necessary unless using MS share-point integration) Add the full domain to all server references. Example from 00Static.xml: <url>jnp:// myserver.mydomain.com:9100</url> (note: this is one of the references I fixed) The original reference was: <url>jn p:// myserver:9100</url> (note: this reference may not work on most enterprise networks) I used a grep search/replace tool to find and update all occurrences of the server reference. 45

48 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

49 About The Author Gary Samuelson is the Director of Systems Architecture at TalkData Consulting. Somewhat a jack-of-all-trades with over 19 years experience in information technologies, he has turned his focus on BPM - the new catchphrase for integrated business/operations support systems and ERP (aka BSS/OSS). In addition to his BPM consulting work he spends his free time writing on technology and building custom desktop and server machines for use in video postproduction and computer game development. His website: 47