Transcription
Serena Collage Integration Guide forSerena TeamTrack
Copyright 2001–2005 Serena Software, Inc. All rights reserved.This document, as well as the software described in it, is furnished under license and maybe used or copied only in accordance with the terms of such license. Except as permittedby such license, no part of this publication may be reproduced, photocopied, stored in aretrieval system, or transmitted, in any form or by any means, electronic, mechanical,recording, or otherwise, without the prior written permission of Serena. Any reproductionof such software product user documentation, regardless of whether the documentationis reproduced in whole or in part, must be accompanied by this copyright statement in itsentirety, without modification.The content of this document is furnished for informational use only, is subject to changewithout notice, and should not be construed as a commitment by Serena. Serenaassumes no responsibility or liability for any errors or inaccuracies that may appear in thisdocument.TrademarksSerena, TeamTrack, StarTool, PVCS, Collage, and ChangeMan are registered trademarksof Serena Software, Inc. The Serena logo, Dimensions, Professional, Tracker, VersionManager, Builder, Meritage, and Mover are trademarks of Serena Software, Inc.Macromedia and Contribute are the trademarks or registered trademarks of Macromedia,Inc. in the United States and/or other countries.The Sentry Spelling-Checker Engine is Copyright 2000 Wintertree Software Inc.All other products or company names are used for identification purposes only, and maybe trademarks of their respective owners.U.S. Government RightsAny Software product acquired by Licensee under this Agreement for or on behalf of theU.S. Government, its agencies and instrumentalities is "commercial software" as definedby the FAR. Use, duplication, and disclosure by the U.S. Government is subject to therestrictions set forth in the license under which the Software was acquired. Themanufacturer is Serena Software, Inc., 2755 Campus Drive, San Mateo, CA 94403.Publication date: December 2005
Table of ContentsChapter 1Welcome to Serena Collage . . . . . . . . . . . . . . . . . . .5Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7About This Chapter . . . . . . . . . . . . . . . . . . . . . . . .What is the Collage-TeamTrack Integration? . . . . . . .Use Case . . . . . . . . . . . . . . . . . . . . . . . . . . . .Who Should Use the Collage-TeamTrack Integration?.Chapter 2.Getting Started Using the Collage-TeamTrack Integration .Where to Start? . . . . . . . . . . . . . . . . . . . . . . . . . . .Integration Prerequisites . . . . . . . . . . . . . . . . .Setting Up the Integration . . . . . . . . . . . . . . . . . . .Integrating with a New TeamTrack Solution . . . .Integrating with an Existing TeamTrack Solution .Integration Guide for Serena TeamTrack .888911.12121212163
Table of Contents4Serena Collage 5.1
Welcome to Serena Collage Thank you for choosing Serena Collage, a complete Web content management package.Purpose of thismanualThis manual provides an introduction to the integration between Collage and Serena TeamTrack .It is assumed that the TeamTrack administrator has access to the Collage server to gatherthe proper information for the administrative activities of entering all of the Collageinformation about projects, users, and task templates. In addition, they should have theknowledge necessary to populate the proper auxiliary tables. For this integration, it isassumed that users will primarily be Collage or TeamTrack users that would prefer toremain within those respective environments.For moreinformationRefer to the Introduction to Serena Collage for a description of the Serena Collagedocumentation set, a summary of the ways to work with Serena Collage, and instructionsfor accessing the online help.For detailed information on TeamTrack, refer to the following manuals available with yourTeamTrack installation: Serena TeamTrack Reviewer Guide Serena TeamTrack Installation and Setup Guide Serena TeamTrack Administrator Guide Serena TeamTrack User Guide Serena TeamTrack TeamScript Reference Guide Serena TeamTrack SourceBridge User GuideTypographical ConventionsThe following typographical conventions are used in the online manuals and online help.These typographical conventions are used to assist you when using the documentation;they are not meant to contradict or change any standard use of typographical conventionsin the various product components or the host operating system.ConventionExplanationitalicsIntroduces new terms that you may not be familiar with andoccasionally indicates emphasis.boldEmphasizes important information and field names.UPPERCASEIndicates keys or key combinations that you can use. For example,press the ENTER key.monospaceIndicates syntax examples, values that you specify, or results thatyou receive.monospaceditalicsIndicates names that are placeholders for values you specify; forexample, filename.Integration Guide for Serena TeamTrack 5
6ConventionExplanationmonospaceboldIndicates the results of an executed command.vertical rule Separates menus and their associated commands. For example,select File Copy means to select Copy from the File menu.Also, indicates mutually exclusive choices in a command syntax line.Serena Collage 5.1
Chapter 1OverviewAbout This Chapter8What is the Collage-TeamTrack Integration?8Who Should Use the Collage-TeamTrack Integration?9Integration Guide for Serena TeamTrack 7
Chapter 1 OverviewAbout This ChapterThis chapter introduces you to the primary concepts that you need to understand beforeyou start setting up the integration between Serena Collage and Serena TeamTrack. For abroad introduction to additional Collage concepts, see the Introduction to Serena Collage.For more information on TeamTrack, see the Serena TeamTrack Administrator’sGuide.What is the Collage-TeamTrack Integration?The Collage-TeamTrack integration is a feature of Collage that enables information to besynchronized between Collage and TeamTrack. A state within the TeamTrack workflow isused specifically for users to fill out all of the required Collage task information. Once theinformation is supplied, the TeamTrack workflow triggers TeamTrack’s TeamScript toinvoke the command-line client of Collage to create the task. If successful, the TeamTrackissue will enter the "Collage Task" state.Once the Collage task is created, Collage users and administrators can modify andtransition it within Collage. When changes do occur, the information is added to the notessection of the TeamTrack issue. Once the Collage task reaches the Finished state, Collagenotifies TeamTrack and the TeamTrack issue is transitioned to the next state.Use CaseThe purpose of the Collage-TeamTrack integration is to manage issues that requirechanges to a Web site controlled by Collage. Following is an example of how thisintegration may be used:81A product manager finds an issue in an existing Web site.2The product manager logs into TeamTrack using his Web browser and creates a newissue of type "defect" to track the issue.3The issue is promoted through the TeamTrack workflow. When the issue istransitioned to the Collage task state, the user is prompted to supply the Collageproject name, task template, and assignee. When the issue is submitted, a task iscreated in Collage.4In Collage, the developer sees the task assigned to her and addresses it accordingly.TeamTrack is updated with a note every time the task in Collage is assigned a newstate.5When the task is closed in Collage, the associated issue in TeamTrack is updated andpromoted to the next state. The product manager is able to see in TeamTrack that theissue was addressed.Serena Collage 5.1
Who Should Use the Collage-TeamTrack Integration?Who Should Use the Collage-TeamTrack Integration?The Collage-TeamTrack integration is for Collage or TeamTrack users who want to useTeamTrack for issue management and Collage for content and Web site changemanagement.Administrators of this integration should have access to and familiarity with bothTeamTrack and Collage administration, specifically: TeamTrack knowledge necessary to populate the proper auxiliary tables. Collage information about projects, users, and task templatesIntegration Guide for Serena TeamTrack 9
Chapter 1 Overview10Serena Collage 5.1
Chapter 2Getting Started Using the CollageTeamTrack IntegrationWhere to Start?12Setting Up the Integration12Integration Guide for Serena TeamTrack 11
Chapter 2 Getting Started Using the Collage-TeamTrack IntegrationWhere to Start?The first thing to do is to install Serena Collage, Serena TeamTrack, and set up all serversand databases. Collage and TeamTrack do not need to be installed to the same system.For detailed information on installing and setting up a Collage system, see the SerenaCollage Installation and Setup Guide. For information on installing and setting upTeamTrack, see the Serena TeamTrack Installation and Setup Guide.Once installation is complete, you configure the integration.Integration PrerequisitesFor the Collage to TeamTrack integration to work, you must have: Collage. The Collage installation must contain at least one project with at least onetask template and at least one user within the Projects User list for all integratingprojects and have the project level permission "Open Project". TeamTrack (Windows only) Serena TeamTrack XML Bridge Serena License ManagerSee the readme for the specific versions of these installations required for this integration.Setting Up the IntegrationHow the integration is set up depends on whether you want to integrate Collage with anexisting or new TeamTrack solution.Integrating with a New TeamTrack SolutionTo integrate with a new TeamTrack solution:1Unzip the following TeamTrack integration files located in\Collage\Extra\TeamTrackIntegration.zip on the Collage DVD to a location on the localfile system where the TeamTrack server is running. collageapi.jar ttcollagecmd.jar collageAPIcmd.bat createnewtask.tsc ttintegr schema.xml ttintegr workflows.xml ttintegr schema aux.xmlNOTE The path to the files should not contain spaces.12Serena Collage 5.1
Setting Up the Integration2Create a new TeamTrack database as described in the TeamTrack documentation. Usethe following settings: Set the License Server Host Name to the address of the machine where SerenaLicense Manager is running. Accept the Field Information page with the default settings.After the database creation is done, the TeamTrack Administrator Connect dialogopens.3Specify the Database Login ID and Database Password and click OK.4Register the database with Serena License Manager.a Start the Serena License Manager client and select the Products tab.b Select TeamTrackTTT from the Product Licenses list and click Manage UserIDs.c On the User Management screen, enter the database identifier for the databasecreated in TeamTrack and click OK. The database identifier can be viewed in theTeamTrack Administrator utility by choosing Options License Options.d Restart the License Manager Service.5Create an Issue Management Solution in TeamTrack with the following settings: The solution must be called "Issues". On the Workflow tab, select Minimum/Standard. Use the default settings for the rest of the configuration.See the Serena TeamTrack Getting Started Guide for information about creatingsolutions in TeamTrack.6Validate the TeamTrack setup.a Create TeamTrack users and assign appropriate roles.b Log into the TeamTrack solution using a Web browser.7Import the database schema from the XML file ttintegr schema.xml to create thedatabase tables. This file is one of the files unzipped in Step 1. See the Serena TeamTrack Administrator Guide for information about importing XML files inTeamTrack.8Import the TeamTrack workflow from the XML file ttintegr workflows.xml tocreate the workflow and project. This file is one of the files unzipped in Step 1. SelectBase Workflow and Base Project as parent. See the Serena TeamTrack Administrator Guide for information about importing XML files in TeamTrack.9Set up the XMLBridge utility for the integration.a Start the OWA Administrator utility by selecting Options OWA Administrator2.0 in TeamTrack Administrator. You will be prompted to log into TeamTrack.NOTE You must have the TeamTrack server running before attempting to log in.b Select the Tools tab and add a tool for the Collage integration.c Select the Bridges tab and create a bridge for the integration.Integration Guide for Serena TeamTrack 13
Chapter 2 Getting Started Using the Collage-TeamTrack Integration10Update the following integration scripts:a On the OWA Administrator Scripts tab, select the Create Collage Task script andmodify the string:const PATH Icmd.bat"to point to the correct location of the Collage command line utility. This bat file isone of the files unzipped in Step 1.b In the same script, make sure that const BridgeName has the name of the bridgeyou created in the prior step, for example: const BRIDGENAME "CollageIssues Bridge"c Update the file collageAPIcmd.bat so that all paths refer to the directory in whichthe files for the command line utility reside. This file is one of the files unzipped inStep 1.11Set up TeamTrack users. Add at least one user with Managed Administrator access and privileges to modifythe integration tables to populate them with data. Be sure to add users from the Development and Management groups.12Populate data in the integration tables.a Login to TeamTrack and click Manage Data.b Select tables starting with "Collage " and click the Create New Item link.TIP It is a good idea to add data in the following sequence. Collage Server table14FieldValueServer IdShould be set to 'collage'.HostThe Collage host/IP addressincluding port number (Forexample, host:8080).User NameThe Collage user name thatis used to connect to theCollage server and project.This user should be in theproject’s user list for allintegrating projects and havethe project level permission"Open Project".PasswordThe password for the Collageuser name.Serena Collage 5.1
Setting Up the Integration Collage Projects tableFieldValueNameThe Collage project nameintegrating with TeamTrack.TitleA short description of theproject.DescriptionA long description of theproject. Collage Templates tableFieldValueNameThe name of the tasktemplate to be shown in theTeamTrack interface.TitleA short description of thetemplate.Collage ProjectThe Collage project to whichthe template belongs.Template IdThe template ID in Collage.To get the value for thetemplate ID: DescriptionLog into Collage.Under Home TaskTemplates, open theProperties screen forthe template.The Template ID hereshould match the AssetID on the Propertiesscreen.A long description oftemplate. Collage Users tableFieldValueUser NameA Collage user name that willbe using the integration. Thisuser should be in theproject’s user list for allintegrating projects and havethe project level permission"Open Project".Full NameThe user’s full name.Integration Guide for Serena TeamTrack 15
Chapter 2 Getting Started Using the Collage-TeamTrack Integration Collage Project Users tableFieldValueCollage ProjectReference to the Collageproject.Collage UserReference to the Collageuser. Collage Task Priority tableFieldValuePriority IdThe ID for the priority.NameThe display name for thepriority.The values for priority are:PRIORITY HIGH 1;PRIORITY MEDIUM 2;PRIORITY LOW 3;At this point, the integration from TeamTrack to Collage is complete. Items in TeamTrackthat transition to the state created for the Collage integration will trigger a task in Collagebased on the task template selected.Integrating Collage to TeamTrackOnce the integration is configured within TeamTrack, you must configure the integrationwithin Collage.To integrate Collage to TeamTrack:1Modify the tmtrack.properties file located in the Collage installation. The file is inservlet\WEB-INF.a Edit the owaserver.url line and enter the URL for the OWA server.b On the tmtrack.user and tmtrack.password lines, enter a TeamTrack user andpassword. This user must have the API/Script product access set in TeamTrack.Optionalc Set tmtrack.transattrname to the value of the transition attribute name if differentfrom the default. The default value is "Collage Resolved."2Restart Collage.This completes the integration from Collage into TeamTrack.Integrating with an Existing TeamTrack SolutionTo integrate with an existing TeamTrack solution:1Unzip the following TeamTrack integration files located in\Collage\Extra\TeamTrackIntegration.zip on the Collage DVD to a location on the localfile system where the TeamTrack server is running. collageapi.jar16Serena Collage 5.1
Setting Up the Integration ttcollagecmd.jar collageAPIcmd.bat createnewtask.tsc ttintegr schema.xml ttintegr workflows.xml ttintegr schema aux.xmlNOTE The path to the files should not contain spaces.2Import the database schema from the XML file ttintegr schema.xml to create thedatabase tables. This file is one of the files unzipped in Step 1. See the Serena TeamTrack Administrator Guide for information about importing XML files inTeamTrack.3Modify your TeamTrack workflow to add in the states that reflect the integration. Seethe Serena TeamTrack Administrator Guide for information about modifyingworkflows in TeamTrack.a Add a new state, such as Collage Assign (name of state could be different).b Create a new transition from some existing state to the new Collage state.c Create a new transition from the Collage state to another existing state. Thetransition name should be CollageResolveTransNOTE The transition from the Collage Assign state should not have any requiredfields on it.4On the Default Fields tab of the TeamTrack workflow editor, add the following fieldsinto the Standard Fields section of the tree:a Add a Single Relational field for Collage Project with the following values: Relational Field Type: Collage Project Logical Field Name: Collage Project Database Field Name: COLLAGE PROJECT Appears in Report Field Lists selected Fully Populated List selected Required selected (Attributes tab)b Add a Single Relational field for Collage Project User with the following values: Relational Field Type: Collage Project User Logical Field Name: Collage Project User Database Field Name: COLLAGE PROJECT USER Appears in Report Field Lists selected Fully Populated List selected Required selected (Attributes tab)Integration Guide for Serena TeamTrack 17
Chapter 2 Getting Started Using the Collage-TeamTrack Integrationc Add a Single Relational field for Collage Template with the following values: Relational Field Type: Collage Template Logical Field Name: Collage Template Database Field Name: COLLAGE TEMPLATE Appears in Report Field Lists selected Fully Populated List selected Required selected (Attributes tab)d Add a Text field for Collage Task Name with the following values: Logical Field Name: Collage Task Name Database Field Name: COLLAGE TASK NAME Appears in Report Field Lists selected Required selected (Attributes tab) Fixed Length of set to 80 bytes (Options tab) Include Field in Keyword Searches selected (Options tab)e Add a Single Relational field for Collage Task Priority with the following values:f Logical Field Name: Collage Task Priority Appears in Report Field Lists selected Fully Populated List selected Required selected (Attributes tab) Display Options of Single Drop-down List selected (Options tab)Add a Text field for Collage Task Status Log with the following values: Logical Field Name: Collage Task Status Log Database Field Name: COLLAGE TASK STATUS LOG Appears in Report Field Lists selected Display Options Style of Journal with Append Only selected (Options tab) Include Field in Keyword Searches selected (Options tab)g Add a Sub-Relational field for Collage Project Title with the following values: Relational Field: Collage Project Sub-Field: Title Logical Field Name: Collage Project Title Appears in Report Field Lists selectedh Add a Text field for Collage Task Notification with the following values:18 Logical Field Name: Collage Task Notification Database Field Name: COLLAGE TASKNOTIFICATION Appears in Report Field Lists selectedSerena Collage 5.1
Setting Up the Integrationij Display Options Style of Memo (Options tab) Include Field in Keyword Searches selected (Options tab)Add a Binary/Trinary field for Track Task Status with the following values: Logical Field Name: Track Task Status Database Field Name: TRACK TASK STATUS Appears in Report Field Lists selected Display Options of Checkbox selected (Options tab)Add a Date/Time field for Collage Task Due Date with the following values: Logical Field Name: Collage Task Due Date Database Field Name: COLLAGE TASK DUE DATE Appears in Report Field Lists selected Display Options of Date and Time selected (Options tab)k Add a Binary/Trinary field for Is Scheduled Task with the following values:5 Logical Field Name: Is scheduled Task Database Field Name: IS SCHEDULED TASK Appears in Report Field Lists selected Display Options of Checkbox selected (Options tab)Set up the XMLBridge utility for the integration.a Start the OWA Administrator utility by selecting Options OWA Administrator2.0 in TeamTrack Administrator. You will be prompted to log into TeamTrack.NOTE You must have the TeamTrack server running before attempting to log in.b Select the Tools tab and add a tool for the Collage integration.c Select the Bridges tab and create a bridge for the integration. Make sure to selectthe workflow that you modified for the integration.6Update the following integration scripts:a On the OWA Administrator Scripts tab, select the Create Collage Task script andmodify the string:const PATH Icmd.bat"to point to the correct location of the Collage command line utility. This bat file isone of the files unzipped in Step 1.b In the same script, make sure that const BridgeName has the name of the bridgeyou created in the prior step, for example: const BRIDGENAME "CollageIssues Bridge"c Update the file collageAPIcmd.bat so that all paths refer to the directory in whichthe files for the command line utility reside. This file is one of the files unzipped inStep 1.7Set up TeamTrack users.Integration Guide for Serena TeamTrack 19
Chapter 2 Getting Started Using the Collage-TeamTrack Integration Add at least one user with Managed Administrator access and privileges to modifythe integration tables to populate them with data. Be sure to add users from the Development and Management groups.8Edit the workflow to execute the integration script when the item transitions to theCollage Assigned state. To do this, select the transition that leads into the CollageAssigned state and edit it to execute the "Collage Integration Script" as a PostTransition script.9Populate data in the integration tables.a Login to TeamTrack and click Manage Data.b Select Tables starting with "Collage " and click the Create New Item link.TIP It is a good idea to add data in the following sequence. Collage Server tableFieldValueServer IdShould be set to 'collage'.HostThe Collage host/IP addressincluding port number (Forexample, host:8080).User NameThe Collage user name thatis used to connect to theCollage server and project.This user should be in theproject’s user list for allintegrating projects and havethe project level permission"Open Project".PasswordThe password for the Collageuser name. Collage Projects table20FieldValueNameThe Collage project nameintegrating with TeamTrack.TitleA short description of theproject.DescriptionA long description of theproject.Serena Collage 5.1
Setting Up the Integration Collage Templates tableFieldValueNameThe name of the tasktemplate to be shown in theTeamTrack interface.TitleA short description of thetemplate.Collage ProjectThe Collage project to whichthe template belongs.Template IdThe template ID in Collage.To get the value for thetemplate ID: DescriptionLog into Collage.Under Home TaskTemplates, open theProperties screen forthe template.The Template ID hereshould match the AssetID on the Propertiesscreen.A long description oftemplate. Collage Users tableFieldValueUser NameA Collage user name that willbe using the integration. Thisuser should be in theproject’s user list for allintegrating projects and havethe project level permission"Open Project".Full NameThe user’s full name. Collage Project Users tableFieldValueCollage ProjectReference to the Collageproject.Collage UserReference to the Collageuser.Integration Guide for Serena TeamTrack 21
Chapter 2 Getting Started Using the Collage-TeamTrack Integration Collage Task Priority tableFieldValuePriority IdThe ID for the priority.NameThe display name for thepriority.The values for priority are:PRIORITY HIGH 1;PRIORITY MEDIUM 2;PRIORITY LOW 3;10Open your TeamTrack database within your database tool.a Edit the TS TRANSATTR table to create a record for the Collage Resolve transitionattribute. Set: TS ID to the next high value TS NAME to "Collage Resolved" TS PREFIX to "TTX" TS EXTID to "1" TS PREMACROID and TS POSTMACROID to "0"(zero)b Edit the TS LASTIDS table. Change the TS LASTID column value to the valueused in previous step for the record whose TS NAME column has value ofTransAttrs.11In TeamTrack, edit the CollageResolveTrans transition attributes and set the TTX Collage Resolved attribute to "Executed for the Transition".At this point, the integration from TeamTrack to Collage is complete. Items inTeamTrack that transition to the CollageAssign state will trigger a task in Collagebased on the task template selected.Integrating Collage to TeamTrackOnce the integration is configured within TeamTrack, you must configure the integrationwithin Collage.To configure Collage to integrate with TeamTrack:1Modify the tmtrack.properties file located in the Collage installation. The file is inservlet\WEB-INF.a Edit the owaserver.url line and enter the URL for the OWA server.b On the tmtrack.user and tmtrack.password lines, enter a TeamTrack user andpassword. This user must have the API/Script product access set in TeamTrack.Optionalc Set tmtrack.transattrname to the value of the transition attribute name if differentfrom the default. The default value is Collage Resolved.2Restart Collage.This completes the integration from Collage into TeamTrack.22Serena Collage 5.1
Any Software product acquired by Licensee under this Agreement for or on behalf of the U.S. Government, its agencies and instrumentalities is "commercial software" as defined by the FAR. Use, duplication, and disclosure by the U.S. Government is subject to the . Serena TeamTrack Installation and Setup Guide
