Edition 3.0 SERENA CHANGEMAN DIMENSIONS DEVELOPMENT INTERFACE IMPLEMENTATION GUIDE

Edition 3.0 SERENA CHANGEMAN DIMENSIONS DEVELOPMENT INTERFACE IMPLEMENTATION GUIDE

Copyright 2001 2004 Merant, Inc. All rights reserved. This document, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by such license, no part of this publication may be reproduced, photocopied, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Merant. Any reproduction of such software product user documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification. The content of this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Merant. Merant assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. Trademarks Serena, TeamTrack, StarTool, and ChangeMan are registered trademarks of Serena Software, Inc. The Serena logo is a trademark of Serena Software, Inc. Merant, PVCS, and Collage are registered trademarks of Merant Inc. Dimensions, Professional, Tracker, Version Manager, Builder, Meritage, and Mover are trademarks of Merant, Inc. All other products or company names are used for identification purposes only, and may be trademarks of their respective owners. U.S. Government Rights 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 restrictions set forth in the license under which the Software was acquired. The manufacturer is Merant, Inc., 3445 NW 211th Terrace, Hillsboro, Oregon 97124. Optional Oracle components embedded in Dimensions are also subject to the following Copyright Notices: Copyright 2003-2004 Oracle Corporation. All rights reserved. NOTICE OF RESTRICTED RIGHTS Programs delivered subject to the DOD FAR supplement are 'commercial computer software' and use, duplication, and disclosure of the programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, programs delivered subject to the Federal Acquisition Regulations are 'restricted computer software' and use, duplication, and disclosure of the programs, including documentation, shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software-Restricted Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065. Part Number: MA-DIMIMP-002

3 Table of Contents Welcome to Dimensions...................... 15 About this Manual................................... 16 Typographical Conventions............................ 17 Printing Manuals.................................... 18 Ordering Media Kits................................. 18 Contacting Technical Support.......................... 19 Part 1: The Dimensions Development Interface Introduction........................................ 22 1 Overview of Dimensions Source Control..........23 Introduction........................................ 24 Source Control Concepts.............................. 24 Dimensions Representation of IDE Projects............ 24 Dimensions Role Requirements..................... 27 How Dimensions Integrates with IDEs................... 27 2 Integrating SCC Projects with Dimensions........31 Introduction........................................ 32 Configuring Source Control Options.................... 32 Connecting to Dimensions............................ 35 Registering IDE Projects with Dimensions................ 37 About Workset Scope............................. 40 Specifying an Existing Project....................... 41 About Adding Files to Dimensions Source Control......... 43 Development Interface Implementation Guide

4 Table of Contents Upload Rules Management........................... 44 What are Upload Rules?.......................... 45 Testing Dimensions SCC........................... 45 3 Integrating COM Projects with Dimensions.......47 Introduction....................................... 48 About Web Projects................................. 48 Recommended Workflow............................ 49 Supported Web Servers.............................. 50 Configuring Web Server Security...................... 50 Windows Directory Permissions..................... 50 Windows Challenge/Response Authentication......... 51 FrontPage User Permissions........................ 51 Configuring Source Control Defaults................... 52 Configuring the Server............................ 52 About User Accounts............................. 53 Defining the Default Workset...................... 54 Enabling External Source Control................... 55 About Using COM IDEs with Remote UNIX Nodes......... 56 Adding Web Projects to Source Control................. 56 Nested project structure.......................... 56 Disconnecting Web Projects from Source Control......... 57 Checking Out a Previous Revision...................... 58 Part 1: Get the Previous Revision.................... 58 Part 2: Update the Current Revision................. 59 4 Using Dimensions with IDE Projects.............61 Introduction....................................... 62 Accessing Files from Source Control.................... 62 Overriding Default Options........................... 63 Overriding Get Options........................... 63 Serena ChangeMan Dimensions

Table of Contents 5 Overriding Check Out Options...................... 64 Overriding Undo Check Out Options................. 65 Overriding Check In Options........................ 66 Change Management................................ 68 Enabling Change Management with the DM.CFG File... 69 Using Change Management........................ 69 Viewing Source Control Information.................... 72 File Detail Tab................................... 74 History Tab...................................... 76 Relationships Tab................................. 79 Merge - Diff Tab.................................. 81 Customize Tab................................... 83 Viewing File or Project Differences..................... 84 Viewing File Differences........................... 86 Viewing Project Differences........................ 86 Part 2: IDE Reference Introduction........................................ 90 5 DOORS.....................................91 Introduction........................................ 92 Accessing Supported Features......................... 92 Setting Up the Integration............................ 94 Installing the Integration.......................... 95 Configuring User IDs.............................. 95 Configuring Dimensions........................... 95 Configuring the DOORS-Dimensions Integration....... 96 Configuring Dimensions to Open DOORS Requirements from Dimensions Change Documents.... 104 Using the Integration................................ 105 Logging the Integration into Dimensions............. 105 Checking In a DOORS Baseline...................... 106 Locking a Baseline Item............................ 108 Development Interface Implementation Guide

6 Table of Contents Unlocking a Baseline Item......................... 108 Exporting DOORS Objects to Dimensions Change Documents.................... 109 Browsing Change Documents Associated with DOORS Objects.................... 110 Updating DOORS with Change Document Status from Dimensions..................................... 110 Viewing Dimensions Change Document Status from within DOORS............... 111 Opening a DOORS Requirement from a Dimensions Change Document..................... 111 Fixing a Failed Baseline Check In.................... 112 Running Reports................................. 113 Doors-specific Usability Notes...................... 115 6 FrontPage..................................117 Introduction....................................... 118 Accessing Supported Features......................... 118 Setting Up Source Control Projects..................... 119 Adding Web Projects to Source Control.............. 120 Disconnecting Web Projects from Source Control...... 122 Using Source Control................................ 122 Checking Out Files............................... 123 Undoing a Check Out............................. 123 Checking In Files................................. 124 Checking Out a Previous Revision................... 125 Adding New Files................................ 125 7 JBuilder....................................127 Introduction....................................... 128 Accessing Supported Features......................... 128 Setting Up Source Control Projects..................... 130 Selecting the Source Control Provider for a Project..... 130 Serena ChangeMan Dimensions

Table of Contents 7 Connecting JBuilder Projects to Source Control........ 131 Adding Files to Source Control...................... 132 Connecting Additional Workstations to a Source Control Project.......................................... 135 Removing Files from Source Control................. 136 Disconnecting Workstation Projects from Source Control......................................... 137 Configuring Integration Options.................... 137 Using Source Control................................. 139 Getting Files..................................... 139 Checking Out Files................................ 140 Undoing Check Out............................... 141 Checking In Files................................. 142 Accessing Specific Revisions........................ 145 8 PowerBuilder...............................147 Introduction........................................ 148 Accessing Supported Features in PowerBuilder........... 148 Setting Up Source Control Projects in PowerBuilder........ 149 Connecting PowerBuilder Workspaces to Source Control......................................... 150 Adding Objects to Source Control................... 153 Configuring Workstations in a Multi-User Environment.. 154 Removing Objects from Source Control............... 156 Disconnecting Workspaces from Source Control........ 157 Using Source Control with PowerBuilder................. 157 Getting Objects.................................. 157 Checking Out Objects............................. 158 Undoing Check Out............................... 159 Checking In Objects............................... 160 Accessing Specific Revisions........................ 161 Adding New Objects.............................. 162 Adding New Targets or PBLs........................ 163 Development Interface Implementation Guide

8 Table of Contents PowerBuilder Specific Usability Notes................... 163 Doing a Merge - Diff on the Working Copy of an Object 163 Unable to Read Registry Value: Software\Serena\Dimensions \9.1\PcmsScc\SccServerName....................... 164 Selecting a Different Application May Not Change the Active SCC Project.................. 165 9 Rational Rose...............................167 Introduction....................................... 168 Accessing Supported Features......................... 168 Setting Up Source Control Projects..................... 169 Before Adding Files to Source Control............... 170 Adding Files to Source Control..................... 171 Removing Files from Source Control................. 173 Using Source Control................................ 174 Getting Files.................................... 175 Checking Out Files............................... 176 Undoing Check Out.............................. 177 Checking In Files................................. 178 Accessing Specific Revisions........................ 180 10 TestDirector................................181 Introduction....................................... 182 About the Dimensions Integrations to TestDirector....... 182 About TestDirector Defect Status and Dimensions Lifecycle States........................ 183 Accessing Supported Features......................... 184 Source Control Features........................... 184 Issue Management Features....................... 185 Setting Up Source Control Projects..................... 187 Installing and Configuring the Software............. 187 Enabling Source Control.......................... 192 Serena ChangeMan Dimensions

Table of Contents 9 Adding Projects to Source Control................... 192 Removing Projects from Source Control.............. 194 Using Source Control................................. 195 Getting Tests.................................... 195 Checking Out Files................................ 196 Undoing Check Out............................... 199 Checking In Files................................. 199 Adding New Tests................................ 200 Viewing Version History........................... 201 Setting Up Issue Management......................... 202 Installing the Software............................ 202 Enabling History for Fields and Attributes............. 202 Overview of Setting Up the Issue Management Integration.......................... 204 Configuring a Connection to a Dimensions Database... 205 Configuring a Connection to a TestDirector Project..... 207 Mapping a TestDirector Project to a Dimensions Product......................................... 209 Editing Existing Attribute Mappings................. 219 Editing Existing Status Mappings.................... 223 Editing Existing TestDirector Restrictions.............. 226 Editing Existing Dimensions Restrictions.............. 226 Deleting Connections............................. 227 Deleting Links................................... 229 Troubleshooting Links............................ 229 Using Issue Management............................. 231 Replicating Defects to Dimensions................... 232 Replicating Change Documents to TestDirector........ 233 Resolving Conflicts................................ 234 Viewing Change Document and Defect Status......... 236 11 Visual Basic................................237 Introduction........................................ 238 Development Interface Implementation Guide

10 Table of Contents Accessing Supported Features......................... 238 About Visual Basic Files.............................. 239 Setting Up Source Control Projects..................... 240 Enabling SCC Integration.......................... 240 Supporting Files Outside the Project Directory........ 242 Configuring Source Control Behavior................ 243 Adding Visual Basic Projects to Source Control........ 244 Connecting Additional Workstations to a Source Control Project......................................... 246 Removing Files from Source Control................. 247 Using Source Control................................ 248 Getting Files.................................... 248 Checking Out Files............................... 250 Undoing Check Out.............................. 251 Checking In Files................................. 253 Accessing Specific Revisions........................ 255 Adding New Files to Source Control................. 256 Visual Basic Specific Usability Notes.................... 257 12 Visual C++.................................259 Introduction....................................... 260 Accessing Supported Features......................... 260 Setting Up Source Control Projects..................... 261 Configuring Source Control Behavior................ 262 Using a UNIX Based Dimensions Server with Visual C++. 263 Adding Visual C++ Files to Source Control............ 264 Connecting Additional Workstations to a Source Control Project......................................... 266 Removing Files from Source Control................. 268 Using Source Control................................ 269 Getting Files.................................... 270 Checking Out Files............................... 270 Undoing Check Out.............................. 271 Serena ChangeMan Dimensions

Table of Contents 11 Checking In Files................................. 272 Accessing Specific Revisions........................ 274 13 Visual InterDev.............................275 Introduction........................................ 276 About Web Projects.................................. 276 Accessing Supported Features from Web Projects......... 277 Setting Up Web Projects.............................. 278 About Visual InterDev Web Projects.................. 279 Adding Web Projects to Source Control............... 279 Disconnecting Web Projects from Source Control....... 280 Removing Files from Source Control................. 281 Deleting Files from Visual InterDev and Source Control.. 281 Using Source Control with Web Projects................. 282 Getting Files..................................... 282 Project-wide Get Options.......................... 284 Checking Out Files................................ 285 Undoing a Check Out............................. 286 Checking In Files................................. 287 Checking Out a Previous Revision.................... 289 Adding New Files................................. 289 About Non-Web Projects.............................. 289 Accessing Supported Features from Non-Web Projects..... 290 Integrating Source Control with Non-Web Projects........ 291 Adding Non-Web Projects to Source Control........... 291 Disconnecting Non-Web Projects from Source Control... 293 Removing Files from Source Control................. 293 Deleting Files from Visual InterDev and Source Control.. 294 Using Source Control with Non-Web Projects............. 295 Getting Projects or Solutions....................... 295 Getting Files..................................... 296 Checking Out Files................................ 297 Development Interface Implementation Guide

12 Table of Contents Undoing Check Out.............................. 298 Checking In Files................................. 299 Accessing Specific Revisions........................ 300 Adding New Files................................ 300 14 Visual Studio.NET...........................303 Introduction....................................... 304 Accessing Supported Features......................... 305 Setting Up Source Control Projects..................... 306 Configuring Source Control Behavior................ 306 Configuring Web Projects......................... 307 Excluding or Removing Files from Source Control...... 308 Adding Visual Studio Files to Source Control.......... 309 Configuring a Multi-Developer Environment.......... 311 Using Source Control................................ 314 Getting Files.................................... 315 Checking Out Files............................... 316 Undoing Check Out.............................. 318 Checking In Files................................. 318 Accessing Specific Revisions........................ 320 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3)....................321 Introduction....................................... 322 Accessing Supported Features......................... 323 Setting Up Source Control Projects..................... 324 Configuring Merge Behavior....................... 325 Excluding Files and Directories from Source Control.... 325 Connecting Projects to Source Control............... 326 Connecting Additional Workstations to a Source Control Project......................................... 330 Adding New Files to Source Control................. 333 Serena ChangeMan Dimensions

Table of Contents 13 Refactoring: Moving or Renaming Projects or Project Elements........................ 335 Disconnecting Projects from Source Control........... 342 Removing Files from Source Control................. 342 Using Source Control................................. 343 Viewing Source Control Status...................... 343 Getting Files..................................... 345 Checking Out Files................................ 345 Locking Files..................................... 346 Undoing Check Out............................... 347 Checking In Files................................. 348 Accessing Specific Revisions........................ 349 Using Local Mode................................ 349 Working Offline.................................. 353 Synchronizing Your Workspace with Source Control.... 355 Comparing with Local History....................... 359 Replacing with Local History........................ 360 Notes for WebSphere Studio Enterprise Developer........ 362 Upload Rules.................................... 362 WebSphere Studio Enterprise Developer 5.0 LPEX Editor.......................................... 362 WebSphere Studio Enterprise Developer 5.0 eglbld Editor.......................................... 363 Index..................................... 365 Development Interface Implementation Guide

14 Table of Contents Serena ChangeMan Dimensions

15 Welcome to Dimensions Purpose of this manual Thank you for choosing Serena ChangeMan Dimensions, a powerful process management and change control system that will revolutionize the way you develop software. Dimensions helps you organize, manage, and protect your software development projects on every level from storing and tracking changes to individual files, to managing and monitoring an entire development cycle. The Dimensions Development Interface enables developers using Source Code Control (SCC), COM, and Eclipse compliant Integrated Development Environments (IDEs) to perform source control operations from within their IDE. This manual provides a conceptual overview of how to work with the Dimensions Development Interface outside of the context of a specific IDE, as well as procedures to help you set up and use the Dimensions Development Interface with your IDE. For more information Edition status Refer to the Serena ChangeMan Dimensions Getting Started Guide for a description of the Dimensions documentation set, a summary of the ways to work with Dimensions, and instructions for accessing the Online Help. This is Edition 3 of the Development Interface Implementation Guide. The information in this edition applies to Release 9.1.0 of Dimensions or later. This edition supersedes earlier editions of this manual. Development Interface Implementation Guide

16 Welcome to Dimensions About this Manual Contents The Serena ChangeMan Dimensions Development Interface Implementation Guide contains two parts: Part 1: The Dimensions Development Interface, on page 21, contains conceptual and procedural information common to setting up and using the Dimensions Development Interface with all supported IDEs. Unsupported features Additional information Part 2: IDE Reference, on page 89, contains procedures specific to setting up and using the Dimensions Development Interface with each supported IDE. Some IDEs do not support all of the features described in this manual. For information on which features are supported and how to access them, see Part 2: IDE Reference, on page 89. Use this manual in conjunction with these additional sources of information: For more information about... Installing Dimensions Setting up and configuring Dimensions Dimensions concepts Dimensions clients See the... Serena ChangeMan Dimensions Installation Guide Serena ChangeMan Dimensions Tool Administration Guide Serena ChangeMan Dimensions User s Guide and Serena ChangeMan Dimensions Process Modeling User s Guide Serena ChangeMan Dimensions User s Guide Serena ChangeMan Dimensions

Typographical Conventions 17 For more information about... Setting up and using your IDE with source control See the... Documentation and online help provided by the vendor of your IDE Typographical Conventions The 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 conventions in the various product components or the host operating system. Convention italics bold UPPERCASE monospace monospaced italics monospace bold Explanation Introduces new terms that you may not be familiar with and occasionally indicates emphasis. Indicates the names of controls and fields on dialog boxes and emphasizes important information. Indicates keys or key combinations that you can use. For example, press the ENTER key. Indicates syntax examples, values that you specify, or results that you receive. Indicates names that are placeholders for values you specify; for example, filename. Indicates the names of commands and command options in syntax examples. Also indicates the results of an executed command. Development Interface Implementation Guide

18 Welcome to Dimensions Convention Explanation vertical rule Separates menus and their associated commands. For example, select File Copy means to select Copy from the File menu. Also, separates mutually exclusive syntax choices. braces {} Encloses a list of mutually exclusive syntax choices, which are themselves set apart by vertical rules. For example, {version from_ver*to_ver}. brackets [] Indicates optional items. For example, in the following statement: SELECT [DISTINCT], DISTINCT is an optional keyword.... Indicates command arguments that you can use multiple times in a single instance of a command. Shows you which shortcut button to click. Shortcut buttons are placed in the margin. Printing Manuals As part of your Dimensions license agreement, you may print and distribute as many copies of the Serena ChangeMan Dimensions manuals as needed. Ordering Media Kits Dimensions can either be purchased as a media kit or by downloading it directly from the Serena web site. Serena ChangeMan Dimensions

Contacting Technical Support 19 The media kit comprises: Dimensions server/client CDs. Documentation CD. ChangeMan Builder for Dimensions CD. Dimensions for Visual Studio CD. Installation Guide. Getting Started Guide. Serena Licensing for Dimensions Quick Start. Oracle Runtime DVD or CD (optional). Dimensions for z/os CD (optional). To order initial (download customers) or additional copies of this media kit, please contact your sales representative for assistance. Contacting Technical Support Serena provides technical support for all registered users of this product, including limited installation support for the first 30 days. If you need support after that time, contact Serena Online Services at the following URL and follow the instructions: http://support.serena.com/ Language-specific technical support is available during local business hours. For all other hours, technical support is provided in English. The Serena Online Services web page can also be used to: Report problems and ask questions. Development Interface Implementation Guide

20 Welcome to Dimensions Obtain up-to-date technical support information, including that shared by our customers via the Web, automatic E-mail notification, newsgroups, and regional user groups. Access a knowledge base, which contains how-to information and allows you to search on keywords for technical bulletins. Download fix releases for your Serena products. Serena ChangeMan Dimensions

21 Part 1: The Dimensions Development Interface This chapter Overview of Dimensions Source Control Integrating SCC Projects with Dimensions Integrating COM Projects with Dimensions Using Dimensions with IDE Projects Starts on page 23 31 47 61 Development Interface Implementation Guide

22 Part 1 The Dimensions Development Interface Introduction Contents Purpose Unsupported features Additional information This part of the manual contains conceptual and procedural information common to setting up and using the Dimensions Development Interface with all supported IDEs. The purpose of this part of the manual is to provide a conceptual and procedural overview of how to set up and use the Dimensions Development Interface outside the context of a specific IDE. Some IDEs do not support all of the features described in this part of the manual. For information on which features are supported and how to access them, see Part 2: IDE Reference, on page 89. Use this part of the manual in conjunction with these additional sources of information. For more information about... Dimensions concepts Setting up and using your IDE with source control See the... Serena ChangeMan Dimensions User s Guide and Serena ChangeMan Dimensions Process Modeling User s Guide Documentation and online help provided by the vendor of your IDE Serena ChangeMan Dimensions

23 1 Overview of Dimensions Source Control In this Chapter For this section... See page... Introduction 24 Source Control Concepts 24 How Dimensions Integrates with IDEs 27 Development Interface Implementation Guide

24 Chapter 1 Overview of Dimensions Source Control Introduction Purpose For more information IDE specific information This chapter is an introduction to key source control concepts and the way in which Dimensions represents and integrates with IDE projects. For more detailed conceptual information about source control and working with Dimensions, see the Serena ChangeMan Dimensions User s Guide and Serena ChangeMan Dimensions Process Modeling User s Guide. For information about the Dimensions features supported in your IDE, see Part 2: IDE Reference, on page 89. Source Control Concepts Most IDEs require that you work in the context of a Project. Projects serve to group associated files such as the source code for a program or the HTML and resource files of a Web site. In addition, the IDE may allow the creation of workspaces consisting of multiple projects. Dimensions represents and controls access to this information as follows. Dimensions Representation of IDE Projects The Dimensions Development Interface uses the concepts of products and worksets to represent the organization and management of software development and to control parallel streams of development. A Dimensions product is normally used to represent a high level of abstraction, probably containing many subsystems or IDE Serena ChangeMan Dimensions

Source Control Concepts 25 projects. A workset provides an insulated environment within a product in which you can develop a collection of files under configuration management. Dimensions uses two entities in order to map the concept of IDE projects to Dimensions products: Workset directories Project marker files Workset Directory All files registered in Dimensions for an IDE Project normally fall within the scope of a directory in a user-specified workset. This is known as the project directory or project path. The path within the workset matches the tail component(s) of the IDE project directory on the user s machine. Files outside the project directory, but still within the scope of the workset, can also be used by the IDE Project. For more information See About Workset Scope on page 40. Project Marker File Project marker files enable IDEs to identify their own projects. Thus a Visual C++ user would be able to see only Visual C++ projects. Similarly, a PowerBuilder user would see only PowerBuilder projects. Each IDE project has a project marker file located in the workset directory that corresponds to the root of the IDE project. Project marker files are named after the IDE project or, if that information is not provided by the IDE, the IDE project directory. The file extension of a given project marker file is dependent upon the IDE it is associated with, as shown below: Development Interface Implementation Guide

26 Chapter 1 Overview of Dimensions Source Control NOTE Integration with some of the IDEs in this list is supported by third parties, not directly by Serena. For the list of integrations supported by Serena, see How Dimensions Integrates with IDEs on page 27. IDE Caliber-RM Eclipse FrontPage Extensions GDPro MainFrame Express JBuilder Net Express PowerBuilder Rational Rose Together Visual Basic Visual C++ VisualStudio Extension.crm.ecl.fp.gdp.mfe.jb.ne.pb.rr.tg.vb.vc.vs NOTE Do not delete project marker files. They are required in order for your IDE projects to work with Dimensions source control. To identify the workset and the project marker file, the Dimensions Development Interface passes an identification string to the IDE. The IDE records this string in its control files and uses it when accessing projects that are under Dimensions source control. These values allow Dimensions to identify the relevant Dimensions workset and directory so you do not have to explicitly select the workset and project directory. Serena ChangeMan Dimensions

How Dimensions Integrates with IDEs 27 Dimensions Role Requirements Dimensions uses role assignments to define who can perform specific actions within particular products and worksets. To... Browse or get files Check out files Add files You need the role allowing... Browsing or getting of the desired items in the project Creation of new revisions of the item types used by files in the project Creation of new revisions of the item types used by files in the project And you need the WORKSET-MANAGER role for the workset containing the project Add projects Creation of new revisions of the item types used by files in the project Creation of items of type PROJECT in the workset And you need the WORKSET-MANAGER role for the workset containing the project. For information on assigning roles, see the Serena ChangeMan Dimensions Process Modeling User s Guide. How Dimensions Integrates with IDEs The Dimensions Development Interface supports four methods of integrating with IDEs: SCC, COM, Custom SCC Based and Custom integrations. The following list shows the method used by each supported IDE: Development Interface Implementation Guide

28 Chapter 1 Overview of Dimensions Source Control Source Code Control (SCC) PowerBuilder Rational Rose Visual Basic Visual C++ Visual InterDev (non-web projects) Visual Studio.NET COM FrontPage TestDirector (source control) Visual InterDev (web projects) Custom SCC Based JBuilder Eclipse, WebSphere Studio Application Developer WebSphereStudio Enterprise Edition (Local Cobol, PL/1) Custom Integrations DOORS (source control and issue management) Remedy ARS (Issue Synchronization - Separate Documentation) Additional information TestDirector (Issue Synchronization) For information on setting up Dimensions with your IDE, see the following: For more information about... Procedures common to integrating with SCC compliant IDEs See the... Chapter 2, Integrating SCC Projects with Dimensions, on page 31 Serena ChangeMan Dimensions

How Dimensions Integrates with IDEs 29 For more information about... Procedures common to integrating with COM compliant IDEs Procedures for integrating with specific IDEs See the... Chapter 3, Integrating COM Projects with Dimensions, on page 47 Part 2: IDE Reference, on page 89 Development Interface Implementation Guide

30 Chapter 1 Overview of Dimensions Source Control Serena ChangeMan Dimensions

31 2 Integrating SCC Projects with Dimensions In this Chapter For this section... See page... Introduction 32 Configuring Source Control Options 32 Connecting to Dimensions 35 Registering IDE Projects with Dimensions 37 About Adding Files to Dimensions Source 43 Control Upload Rules Management 44 Testing Dimensions SCC 45 Development Interface Implementation Guide

32 Chapter 2 Integrating SCC Projects with Dimensions Introduction Contents and purpose IDE specific information This chapter contains generic conceptual and procedural information common to setting up the Dimensions Development Interface with supported IDEs. The purpose of this chapter is to help you place IDE projects and files under source control. For information specific to your IDE, see Part 2: IDE Reference, on page 89. Configuring Source Control Options This section describes how to enable and set the defaults for advanced source control features. For information on overriding the defaults during a source control operation, see Overriding Default Options on page 63. NOTE For Eclipse-based IDEs, such as WebSphere Studio, you should enable merge on check in. To configure source control options: 1 From the Windows Start menu, select Serena ChangeMan Dimensions 9.1 Administration Tools Configuration Parameters. The dm.cfg file opens in your default text file editor. Concurrent development 2 The settings for concurrent development are now the default for Dimensions SCC. It is no longer necessary to set the DIMENSIONS_SCCPLUS configuration variable.this option provides the following behavior: Notifies the user during concurrent check out operations. Serena ChangeMan Dimensions

Configuring Source Control Options 33 Displays a glyph to indicate files are checked out by other users, if the IDE is so equipped. Launches the Merge Tool during check in if your revisions conflict with concurrent edits already checked in by other users. (See the merge defaults above.) The default option has the same effect as the following four options combined: DM_SCC_SHOWRESOLVEMERGE Y DM_SCC_NEWSTATUS Y DM_SCC_FNEWSTATUS Y DM_SCC_CONFIRMWARNINGS Y The effect of the default setting can be reversed by specifying the following option: DIMENSIONS_SCCPLUS N NOTE You should leave this feature enabled for Eclipsebased IDEs, such as WebSphere Studio. Merge defaults 3 To configure default merging behavior, add or modify the following lines: DM_SCC_SHOWRESOLVEMERGE Y DM_SCC_MERGECONFIRM Value Where Value is one of the following: ASK: Prompts the user for what to do with each conflicting file. This is the default unless you have configured a different one. AUTO_ALL: Merges the revisions without invoking the Merge tool window, unless there are line-by-line conflicts in which case, the Merge tool appears so you can resolve the conflicts. Development Interface Implementation Guide

34 Chapter 2 Integrating SCC Projects with Dimensions MANUAL_ALL: The Merge tool appears so you can manually resolve the conflicts. REPLACE_ALL: Overwrites the local workfiles rather than performing a merge. SKIP_ALL: Leaves the local workfiles as they are. Timestamps 4 To set the timestamp of the local workfile to the current local system time when getting or checking out revisions, add the following line: DM_SCC_TIMESTAMP Y By default, the timestamp is set to the modification time of the revision. Get newer only 5 To get a revision only if it has a newer timestamp than its workfile, add the following line: DM_SCC_GETMODIFIEDONLY Y By default, revisions are retrieved regardless of the timestamp. Remove/Delete 6 To delete items from the Dimensions repository when a Remove operation is invoked from an IDE, add the following line: DM_SCC_REMOVEISDELETE Y Enabling this option restores the old behavior. The current default is to remove the items from the project workset but leave them in the repository. 7 Save the configuration file. The changes will take effect the next time you start your IDE. Serena ChangeMan Dimensions

Connecting to Dimensions 35 Connecting to Dimensions To perform any operations that access Dimensions, you must first connect to the Dimensions server. To log in: 1 Invoke Dimensions through your IDE. For the IDE specific menu command, see Part 2: IDE Reference, on page 89. The Dimensions Login dialog box appears. 2 Do one of the following: To populate the fields with previously saved values: a) Select a previous connection from the Profile dropdown list. Development Interface Implementation Guide

36 Chapter 2 Integrating SCC Projects with Dimensions b) Enter a password in the Password field. Proceed to Step. To enter new values in the fields, type a new connection name in the Profile field and/or deselect the Save settings checkbox to avoid overwriting the stored values of the currently selected connection. Continue to the next step. 3 Enter a user name in the User name field. 4 Enter a password in the Password field. 5 Enter the name and location of a Dimensions server in the Server field. 6 Enter the name of a Dimensions database in the DB Name field. 7 Enter a database connection string in the DB Connection field, if it is not already present. 8 To skip this dialog box in the future, select the Enable automatic login checkbox. The next time you initiate Dimensions from an IDE, you will be automatically logged into Dimensions using the current settings. T I P To override automatic login, press the CTRL key while Dimensions is loading. The Dimensions Login dialog box will then appear. 9 Click the Connect button. Serena ChangeMan Dimensions

Registering IDE Projects with Dimensions 37 Registering IDE Projects with Dimensions Before you can add the files within an IDE project to source control, you must register the IDE project with the Dimensions Development Interface. IMPORTANT! To register an IDE project with Dimensions, you must have the WORKSET-MANAGER role for the workset concerned and the Dimensions role required to create items of type PROJECT in the Dimensions product. IDE specific context Procedure The following procedure is referenced by each IDE specific chapter contained in Part 2 of this manual as a step in the procedure to add projects to source control (SCC compliant IDEs only). For the IDE specific context in which this procedure is used, please see Part 2: IDE Reference, on page 89. To register an IDE project with Dimensions: 1 Depending on the IDE you are using and how it is configured, you may invoke the registration process by: Creating a new IDE project Opening an existing IDE project not currently under source control Selecting the command from your IDE s menu to add a project to source control (For the IDE specific menu command, see Part 2: IDE Reference, on page 89.) Development Interface Implementation Guide

38 Chapter 2 Integrating SCC Projects with Dimensions The following dialog box appears. 2 Do one of the following: To add the IDE project to an existing Dimensions project, click the Select Project button. Proceed to Specifying an Existing Project on page 41. To create a new Dimensions project for the IDE project, continue to the next step. 3 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Select a workset from the Workset drop-down list. By default, your default workset is used. Serena ChangeMan Dimensions

Registering IDE Projects with Dimensions 39 Example Select a design part from the Design Part drop-down list. By default, this field will contain the top design part of the default workset. Specify a path within the workset under which to place the project. By default, the value of the Project path field matches the last component of the IDE project path. If you change the Project path field, you must base it upon the IDE project path as shown in the Local Path field. For example, if the local path is c:\myprojects\superpad, the default value of the Project path field would be superpad. You could change the Project path field to myprojects\superpad or accept the default value of superpad; no other values would be valid. You can copy (CTRL + C) directories from the Local path field and paste them (CTRL + V) into the Project path field. To navigate existing workset directories use the Directory tree; directories that cannot be used to match the tail of the IDE project path are marked with a prohibition ( ) symbol. IMPORTANT! The scope of the workset is determined by the Project path field. All project files must be located within the scope of the workset. For more information about defining the scope of the workset, see About Workset Scope on page 40. Additional information 4 Click OK. Use this section in conjunction with these additional sources of information: For information about... Follow-on procedures specific to your IDE See... Part 2: IDE Reference, on page 89 Development Interface Implementation Guide

40 Chapter 2 Integrating SCC Projects with Dimensions For information about... Adding files to source control, described in generic, non-idespecific terms See... About Adding Files to Dimensions Source Control on page 43 About Workset Scope The value you enter in the Project path field of the Select workset directory for project dialog box, determines the workset directory and the scope of the workset for the project. All project files must be located within the scope of the workset. The scope of a workset includes all directories in the Project path field and those directories that are at the same level on that branch of the directory tree. The following examples illustrate the relationship between the value of the Project path field and workset scope. Example 1 Project path: Project1 Workset scope Example 2 Project files could be located in: FolderTwo Project1 Project path: MyProjects\Project1 Workset scope Serena ChangeMan Dimensions

Registering IDE Projects with Dimensions 41 Project files could be located in: FolderTwo Project1 MyProjects FolderOne Specifying an Existing Project The Select SCC Project dialog box allows you to add an IDE project to an existing Dimensions project. It also allows you to specify which Dimensions project to use if the IDE or Dimensions is unable to determine this on its own. To specify an existing project: 1 Click the Select Project button on the Select workset directory for project dialog box. (See Registering IDE Projects with Dimensions on page 37. The Select SCC Project dialog box may also appear when you try to access a project if: The IDE project files have been deleted. The Dimensions workset has been deleted. Development Interface Implementation Guide

42 Chapter 2 Integrating SCC Projects with Dimensions The project has been moved into another workset or directory. 2 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Select an existing workset from the Workset drop-down list. By default, your default workset is used. Select an existing project from the Project drop-down list. From some IDEs, you can select a project that was created by a different IDE. NOTE The New Project button opens the Select workset directory for project dialog box which allows you to create a new Dimensions project. For more information, see Registering IDE Projects with Dimensions on page 37. 3 Click OK. Serena ChangeMan Dimensions

About Adding Files to Dimensions Source Control 43 About Adding Files to Dimensions Source Control Purpose This section describes, in generic, non-ide-specific terms, how IDE files are added to Dimensions source control. For procedures specific to your IDE, see Part 2: IDE Reference, on page 89. Once you have created and saved an IDE project and are working in the context of that project, you may add it to Dimensions source control. The procedure for doing this varies somewhat with each IDE, but most of the following applies to supported SCC compliant IDEs: You can place a whole project under Dimensions control when you create it. Additional files can be added to the source control project during the course of development. NOTE The IDE may prompt you to add files/projects when you create them or you may explicitly add them using menu commands. The automatic prompting is normally an option you can set in the IDE. Dimensions creates an item for each file added, using rules to determine the attributes of the item. NOTE Default rules are set up for each IDE. The rules can be customized, to create new defaults or on a project-by-project basis, using the Dimensions Administration Console (See Upload Rules Management on page 44). New Dimensions projects use a copy of the default rules for the appropriate IDE. The Owning Design Part information in the default rules is not copied. Items are always created in the product that owns the workset in which the Dimensions project was created. Development Interface Implementation Guide

44 Chapter 2 Integrating SCC Projects with Dimensions All items created will be owned by the top-level design part of the product unless you specify different Owning Design Part information. If you are putting an existing IDE project under source control, the IDE may not prompt you to create the Dimensions SCC project until you attempt to add files to Dimensions SCC. In this case, you can make preliminary changes to the rules at any time between creating the Dimensions SCC project and confirming the Add operation. Upload Rules Management Through the Administration Console you can: Specify rules that determine which files can be added to the Dimensions database, and which files should be excluded. Constraints Invocation View, edit, and delete rules for Dimensions clients, IDEs, and IDE projects. You must be the Tool Manager to modify default rules for Dimensions or IDEs. You must be the Product Manager to modify rules for a specific IDE project. Dimensions Administration Console Configuration Object Management Upload Rules NOTE The Upload Rules function in the Dimensions Administration Console was previously known as IDE Setup in releases prior to Dimensions 8.0. For information on launching the Administration Console, see the Serena ChangeMan Dimensions Getting Started Guide. Serena ChangeMan Dimensions

Upload Rules Management 45 What are Upload Rules? Upload rules map file name patterns to Dimensions file formats and item types. These rules determine whether files that match a certain file name pattern can be added to the database using a Dimensions client or an IDE. Upload rules also determine the attributes of new items that are created in Dimensions. Upload rules must exist in the base database before you can start adding files. Starting with Dimensions 7.0, default upload rules are automatically included when you create a database. The default rules apply to Dimensions clients and each supported IDE. You can modify the default rules, as well as create and modify rules for specific IDE projects. If you modify the: Default rules for Dimensions: The modified rules will be used for all files added to Dimensions through the desktop client, the web client, and the Project Merge tool. Default rules for an IDE: All subsequent projects created by that IDE in the same base database will use a copy of the new default rules. For more information Rules for a specific project: The modified rules will be used for all subsequent operations in that project. See Serena for more information on working with upload rules. Testing Dimensions SCC Dimensions includes a tool to test that the SCC component of Dimensions is loading properly. Development Interface Implementation Guide

46 Chapter 2 Integrating SCC Projects with Dimensions To test Dimensions SCC: 1 Select Programs Serena ChangeMan Dimensions 9.1 Administration Tools SCC Diagnostics from the Start menu. The Dimensions SCC Diagnostics dialog box appears. 2 Click the Test button. The test results are displayed in the dialog box. Serena ChangeMan Dimensions

47 3 Integrating COM Projects with Dimensions In this Chapter For this section... See page... Introduction 48 About Web Projects 48 Recommended Workflow 49 Supported Web Servers 50 Configuring Web Server Security 50 Configuring Source Control Defaults 52 About Using COM IDEs with Remote UNIX 56 Nodes Adding Web Projects to Source Control 56 Disconnecting Web Projects from Source Control 57 Checking Out a Previous Revision 58 Development Interface Implementation Guide

48 Chapter 3 Integrating COM Projects with Dimensions Introduction Contents and purpose IDE specific information This chapter contains information common to setting up the Dimensions Development Interface with supported COM compliant IDEs. The purpose of this chapter is to help administrators configure web servers and Dimensions for webbased IDE projects. For information specific to your IDE, see Part 2: IDE Reference, on page 89. About Web Projects In a typical web development project, web application files are stored on a web server. Developers access and edit the files from local installations of development environments, such as Microsoft FrontPage. With a source control system in place, only one developer may check out, edit, and update a file on the server at a time. This ensures that multiple users do not produce conflicting versions of the same files and makes it easier to track changes to each file. For more information on how source control can help your team manage and track changes to files, see Chapter 1, Overview of Dimensions Source Control, on page 23. Serena ChangeMan Dimensions

Recommended Workflow 49 Recommended Workflow Administrators We recommend that project leads or administrators first follow these steps: 1 Install the following to the web server: FrontPage Server Extensions Serena ChangeMan Dimensions The Serena ChangeMan Dimensions Development Interface For information on installing the Dimensions Development Interface in a web development environment, see the Serena ChangeMan Dimensions Installation Guide. NOTE By default, the Development Interface is not installed. You must select it during the Dimensions installation process. 2 Configure web server security. See Configuring Web Server Security on page 50. 3 Configure default settings for new source control projects. See Configuring Source Control Defaults on page 52. All users 4 Add the IDE projects to source control. See Adding Web Projects to Source Control on page 56. All users can then perform the following source control tasks: Check out files. For IDE specific information, see Part 2: IDE Reference, on page 89. Edit the files. Check in files. For IDE specific information, see Part 2: IDE Reference, on page 89. Development Interface Implementation Guide

50 Chapter 3 Integrating COM Projects with Dimensions IMPORTANT! Before implementing source control, make sure that Dimensions, the FrontPage Server Extensions, and the Dimensions Development Interface are properly installed on the web server. Supported Web Servers The Dimensions Development Interface is compatible with the following web servers: Use this web server Internet Information Server 5.0 With this operating system Windows 2000 Server SP4 Configuring Web Server Security The Dimensions Development Interface relies on Windows security to control access to and from the web server. Windows security requires assigned user accounts for all operations. You can also use FrontPage user permissions to manage access to webs. Windows Directory Permissions Windows user privileges, as defined on the web server, determine the level of access each user has to files and directories on the server. Every HTTP request to the web server from a FrontPage client runs under a user account on the web server. The rights granted to that user account on the web server Serena ChangeMan Dimensions

Configuring Web Server Security 51 define the operations that can be performed during an HTTP request. IIS checks requests against the Windows user account (user name and password), then impersonates that account to process the request. If a user does not exist, or if a user enters an incorrect password, then the user will be prompted for a valid user ID and password. For more information on creating user accounts, adding users to groups, and defining permissions for directories, see the Windows documentation. Windows Challenge/Response Authentication Windows authentication automatically encrypts user names and passwords. Actual user names and passwords are never sent over a network; they are encrypted over multiple transactions, providing better security against would be hackers attempting to monitor traffic between the client and server. Configure Windows authentication on the Directory Security tab of the Microsoft Management Console. FrontPage User Permissions FrontPage has defined three types of users, which can be assigned to Windows user groups on FrontPage-enabled IIS web servers: This user type Administrator Author Visitor (end-users) Has these privileges Administrative, authoring, browsing Authoring, browsing Browsing Development Interface Implementation Guide

52 Chapter 3 Integrating COM Projects with Dimensions When setting up your user permissions, keep in mind that user permissions are defined on a per-web basis. You cannot control permissions on a per-file or per-directory basis. All FrontPage sub-webs either inherit the permissions of the root web or are specifically assigned their own unique permissions. Configuring Source Control Defaults Once you have installed a Dimensions server, FrontPage Server Extensions, and the Dimensions Development Interface to your web server, you can begin setting up Dimensions for use with web projects. For more information on installing the Dimensions Development Interface, see the Serena ChangeMan Dimensions Installation Guide and the README file. NOTE The Dimensions server must be on the web server. To increase performance, you can locate the Dimensions database on a separate system by setting the LOCAL system environment variable to the database alias for the remote server. Configuring the Server You must perform the following steps to configure the Dimensions server for use with COM IDEs. 1 Update the dm.cfg file: a From the Windows Start menu, select Serena ChangeMan Dimensions 9.1 Administration Tools Configuration Parameters. The dm.cfg file opens in your default text file editor. Serena ChangeMan Dimensions

Configuring Source Control Defaults 53 b Add the following line to the file: DIMENSIONS_COM_BASEDB BaseDatabase@DSN Where BaseDatabase equals the name of the Dimensions base database you are using with COM IDEs and DSN equals the Data Source Name. IMPORTANT! If at some point you designate a new base database, you must restart your COM server application. Example To work with the intermediate database and a Data Source Name of DIM8, you would add the following line: DIMENSIONS_COM_BASEDB intermediate@dim8 NOTE The Data Source Name is the same as the DB Connection field on the Dimensions Login dialog box. For more information, see the Serena ChangeMan Dimensions Getting Started Guide. c Save the dm.cfg file. 2 Create a Dimensions product for use with COM IDEs and enable a process model for it. For more information, see the Serena ChangeMan Dimensions Process Modeling User s Guide. About User Accounts For each Windows login account that is to have access to the COM integration, you must create an identically named Dimensions user. Development Interface Implementation Guide

54 Chapter 3 Integrating COM Projects with Dimensions Setting Up User Accounts To configure Dimensions user accounts: 1 Use the Dimensions Administration Console to create secure user accounts with the following form: WindowsUserName Where WindowsUserName equals the login ID of the user in Windows. For example, JohnD. 2 Give each user the WORKSET-MANAGER and DEVELOPER roles for the workset that will contain COM IDE files. For more information on working with process models, see the Serena ChangeMan Dimensions Process Modeling User s Guide. Defining the Default Workset The integration with COM IDEs uses the default Dimensions workset. You must ensure that the default workset is the same for all users who work on the same projects; it cannot be the global workset. Do one of the following: To allow users to use separate worksets, use the desktop client to set the default workset for each user. Each user can then access a separate workset, but if users are working on the same projects they must use the same workset. For information on setting the default workset with desktop client, see the Serena ChangeMan Dimensions User s Guide. IMPORTANT! Users must avoid changing the default workset or source control will no longer work correctly. To set the same default workset for all users, add the following line to the dm.cfg file: Serena ChangeMan Dimensions

Configuring Source Control Defaults 55 DIMENSIONS_COM_WORKSET Product:Workset Where Product equals the name of the product and Workset equals the name of the workset that will contain the COM IDE files. For information on editing the dm.cfg file see Configuring the Server on page 52. Enabling External Source Control Before you can add COM projects to source control, you must configure the web server to use external source control. IMPORTANT! Your Windows user account must have the rights needed to launch the Microsoft Management Console. This user must also have the Dimensions roles necessary to create projects and add files. To enable external source control: 1 From the web server, launch the Microsoft Management Console. 2 Right-click on the default web site. A pop-up menu appears. 3 Select Properties. The Properties dialog box appears. 4 Select the Server Extensions tab. 5 Select Use external from the Version control list. 6 Click OK. The Source Control Project dialog box appears. 7 Click OK. Development Interface Implementation Guide

56 Chapter 3 Integrating COM Projects with Dimensions About Using COM IDEs with Remote UNIX Nodes Though the Dimensions server must be on a Windows system, you can integrate your COM IDEs with item libraries on a remote UNIX node. This can be accomplished via the Dimensions Administration Console. For detailed information on: Launching the Dimensions Administration Console, see the Serena ChangeMan Dimensions Getting Started Guide Defining item libraries, see the Serena ChangeMan Dimensions Process Modeling User s Guide Configuring remote nodes, see the Serena ChangeMan Dimensions Distributed Development Guide Adding Web Projects to Source Control Prerequisites Once you have configured the default settings for new Dimensions projects, you can place your web projects under source control. Nested project structure When you place a web project under source control, Dimensions automatically creates a new source control project in the default workset. The workset directory structure mimics the web project structure. If your web project contains subdirectories, the subdirectories appear in Dimensions as workset directories. Serena ChangeMan Dimensions

Disconnecting Web Projects from Source Control 57 Example For example, in the illustration below, the web project Pub_web contains two sub-directories called Marketing_home and Sales_home: Web Web subdirectories If you place Pub_web under source control, Dimensions will create the two workset subdirectories, Marketing_home and Sales_home, as well. For example, If the project is added to a Dimensions Workset called SOFTWARE:WS_DEV, the Dimensions project structure appears as follows in the Dimensions desktop client: IDE specific information For information specific to your IDE, see Part 2: IDE Reference, on page 89 Disconnecting Web Projects from Source Control Disconnecting a project from source control does not delete the source control files; it only removes the association with the Dimensions project. You can always reconnect the project to source control later. IDE specific information For information specific to your IDE, see Part 2: IDE Reference, on page 89. Development Interface Implementation Guide

58 Chapter 3 Integrating COM Projects with Dimensions Checking Out a Previous Revision By design, Visual InterDev and FrontPage allow you to check out only the latest revision of a file. However, you can get a previous revision using the Dimensions desktop client, then update the latest revision with it. The previous revision is then available to check out from within your IDE as the latest revision. The procedure to check out a previous revision has two parts: 1 Get the previous revision. 2 Update the current revision. Special Considerations Before you get a previous revision, make sure the workfile that you want to change is checked in. Depending on how security is set up within your organization, you may need to have your Web Administrator perform this task. Part 1: Get the Previous Revision Get the previous revision to a temporary location: 1 Open the Workset containing the web project in the desktop client and select the previous revision of the item. 2 Select Item Get. The Get dialog box appears. 3 Enter a temporary get location in the Name of the file to contain Item field, or click the browse button to select one. 4 Click OK. Serena ChangeMan Dimensions

Checking Out a Previous Revision 59 Part 2: Update the Current Revision Update the current revision with the previous revision: 1 Select the item in desktop client 2 Select Item Update. The Update dialog box appears. 3 Enter the location you got the previous revision to in the Name of file to update item from field, or click the browse button to select it. 4 Click OK. Development Interface Implementation Guide

60 Chapter 3 Integrating COM Projects with Dimensions Serena ChangeMan Dimensions

61 4 Using Dimensions with IDE Projects In this Chapter For this section... See page... Introduction 62 Accessing Files from Source Control 62 Overriding Default Options 63 Change Management 68 Viewing Source Control Information 72 Viewing File or Project Differences 84 Development Interface Implementation Guide

62 Chapter 4 Using Dimensions with IDE Projects Introduction Purpose For more information This chapter is an introduction to the features available to users of the Dimensions Development Interface. For more detailed conceptual information about source control and working with Dimensions, see the Serena ChangeMan Dimensions User s Guide and Serena ChangeMan Dimensions Process Modeling User s Guide. For more information about the Serena ChangeMan Merge Tool for merging files, see the Serena ChangeMan Dimensions User s Guide or the Merge Tool s online help. IDE specific information For more information about the Serena ChangeMan Dimensions Project Merge Tool for merging projects, see the Serena ChangeMan Dimensions User s Guide or the Project Merge Tool s online help. For information about the Dimensions features supported in your IDE, see Part 2: IDE Reference, on page 89. Accessing Files from Source Control Each supported IDE provides a means of accessing the following basic source control operations: Get (Fetch): Retrieves a read-only copy of a file from Dimensions. Check Out (Extract): Retrieves a writable copy of a file from Dimensions and assigns it the next revision number. Undo Check Out: Releases the revision number that was created during check out and replaces the writable workfile with a read-only copy of the latest revision. Serena ChangeMan Dimensions

Overriding Default Options 63 Check In (Return): Updates the Dimensions repository with changes made to the workfile and replaces the writable workfile with a read-only copy. The means of invoking these functions varies from IDE to IDE. For IDE specific menu commands and features, see Part 2: IDE Reference, on page 89. Overriding Default Options This section describes how to override the default options during source control operations. For information on setting the defaults, see Configuring Source Control Options on page 32. Overriding Get Options To override get options: 1 Click the Advanced button on the Get dialog. The Dimensions SCC Advanced Options dialog box appears. (See the chapter specific to your IDE for information about invoking your IDE s Get dialog box.) Development Interface Implementation Guide

64 Chapter 4 Using Dimensions with IDE Projects 2 Select the action to take if the revision you get conflicts with the local workfile. The options are: Ask: Prompts the user for what to do with each conflicting file. This is the default unless you have configured a different one. Automatic Merge All: Merges the revisions without invoking the Merge Tool window, unless there are line-byline conflicts in which case, the Merge Tool appears so you can resolve the conflicts. Manual Merge All: The Merge Tool appears so you can manually resolve the conflicts. Replace All: Overwrites the local workfiles rather than performing a merge. Skip All: Leaves the local workfiles as they are rather than performing a merge. 3 Select the Set Local File to Current date/time check box to set the timestamp of the local workfile to the current time of the local system, instead of the modification date of the revision. 4 Select the Only Modified (newer) Files check box to limit the get operation to revisions that are newer than the timestamp of the local workfile. 5 Click OK. Overriding Check Out Options To override check out options: 1 Click the Advanced button on the Check Out dialog. The Dimensions SCC Advanced Options dialog box appears. (See Serena ChangeMan Dimensions

Overriding Default Options 65 the chapter specific to your IDE for information about invoking your IDE s Check Out dialog box.) 2 Select the Set Local File to Current date/time check box to set the timestamp of the local workfile to the current time of the local system, instead of the modification date of the revision. 3 Click OK. Overriding Undo Check Out Options To override undo check out options: 1 Click the Advanced button on the Undo Check Out dialog. The Dimensions SCC Advanced Options dialog box appears. Development Interface Implementation Guide

66 Chapter 4 Using Dimensions with IDE Projects (See the chapter specific to your IDE for information about invoking your IDE s Undo Check Out dialog box.) 2 Select the Set Local File to Current date/time check box to set the timestamp of the local workfile to the current time of the local system, instead of the modification date of the revision. 3 Click OK. Overriding Check In Options To override check in options: 1 Click the Advanced button on the Check In dialog. The Dimensions SCC Advanced Options dialog box appears. (See Serena ChangeMan Dimensions

Overriding Default Options 67 the chapter specific to your IDE for information about invoking your IDE s Check In dialog box.) 2 Select the action to take if the revision you are checking in conflicts with edits made in parallel. The options are: Ask: Prompts the user for what to do with each conflicting file. This is the default unless you have configured a different one. Automatic Merge All: Merges the revisions without invoking the Merge Tool window, unless there are line-byline conflicts in which case, the Merge Tool appears so you can resolve the conflicts. Manual Merge All: The Merge Tool appears so you can manually resolve the conflicts. Replace All: Overwrites the local workfiles rather than performing a merge. Skip All: Leaves the local workfiles as they are rather than performing a merge. 3 Click OK. Development Interface Implementation Guide

68 Chapter 4 Using Dimensions with IDE Projects Change Management Change documents can be used to control item check out and creation by means of a dialog that automatically appears in the following circumstances: If Change Management rules have been set ON in Dimensions for an item type and an item of that type is being checked out with the IDE. If the rules for an item type in Dimensions are that it requires a Change Document for its creation and an Add to Source Control command is being done for an item of that type in the IDE. If Change Management rules have been set OFF in Dimensions for the item but the DM_SCC_ENABLECHANGE entry in the dm.cfg file has been set for the type of operation being invoked in the IDE. For more information on this method of enabling change management, see the next section. For more information See the Serena ChangeMan Dimensions User s Guide and Serena ChangeMan Dimensions Process Modeling User s Guide. Serena ChangeMan Dimensions

Change Management 69 Enabling Change Management with the DM.CFG File To modify the DM.CFG file to enable change management: 1 From the Windows Start menu, select Programs Serena ChangeMan Dimensions 9.1 Administration Tools Configuration Parameters. The dm.cfg file opens in your default text editor. 2 Add the following line to the file: DM_SCC_ENABLECHANGE X Where X equals one of the following integer values: 1 - To enable change management on check out operations 2 - To enable change management on create operations 3 - To enable change management on both check out and create operations 3 Save the file. Using Change Management Once change management is configured, it is invoked when ever a relevant operation is performed from the IDE. For a list of relevant operations and configurations, see Change Management on page 68. Development Interface Implementation Guide

70 Chapter 4 Using Dimensions with IDE Projects To use change management: 1 The following dialog box appears when you perform any relevant operation from an IDE. The title of the dialog reflects the file and the type of operation for which it was invoked. The line beneath the title bar indicates: If Change Management Rules are ON or OFF If the user has the CHANGE-MANAGER role Additional information on the requirements for change documents 2 Select a change document or documents from the list. The list displays any valid change documents for the operation according to one of the following conditions: Change Management Rules Are Off: All pending change documents of the types detailed in the process model valid relationships for the item type for the user in the product that the SCC project exists in. This does not Serena ChangeMan Dimensions

Change Management 71 include change documents in the CLOSED or REJECTED phases. Also both the Change Document and the Item types must not have rules enabled. Change Management Rules Are On: All pending change documents of the types detailed in the process model valid relationships for the user in the product that the SCC project exists in. This is additionally qualified by the Change Documents being in the AN+WORK or WORK phase and not already related in response to this or any earlier revision. NOTE If the user is CHANGE-MANAGER, change documents for all users will be listed. When checked, the check boxes indicate that the change document already affects the item being checked out, or the owning part if the item is being created. 3 Do any of the following: Select the Only Show Related check box to show only the change documents that have a relationship of type Affected to the item or part in question. Select the Auto Relate check box to create a relationship of type Affected to the item or part in question when you click the Add Selected Change Documents button. Click the Relate/Unrelate button to update relationships according to the change document check boxes you have checked or unchecked. Click the Re-Query button to refresh the list from Dimensions. Click the Add Selected Change Documents button to add the selected change documents to the Change Document ID field as a comma-separated, quoted list. Development Interface Implementation Guide

72 Chapter 4 Using Dimensions with IDE Projects The Change Document ID field displays the change documents added from the list box. You may type in the change document IDs explicitly; entries must be quoted and comma separated. NOTE User entered values are not checked for validity. Click the OK button; the check out/create command proceeds using the change documents listed in the Change Document ID field. If rules are on and no change documents are specified, the user is warned. If this dialog was invoked with multiple files selected, click the OK to All button to apply the selected change documents to all operations without displaying the dialog again. If rules are on, a warning message appears. Dimensions maintains a default list of change documents for the duration of a session. Click the Set as Default button to set the default list to those change documents currently listed in the Change Document ID field. Click the Clear List button to clear the Change Document ID field. Click the Cancel button to quit the dialog. Viewing Source Control Information The Dimensions Development Interface allows you to access file attributes, history, and relationships information through a single dialog. You can also use this dialog to perform source control operations upon specific revisions of files. Serena ChangeMan Dimensions

Viewing Source Control Information 73 Procedure To view source control information: 1 Launch the Dimensions History or Properties function from your IDE. For the IDE specific menu command, see Part 2: IDE Reference, on page 89. T I P To allow for the selection of specific revisions, you can invoke the History tab by pressing CTRL + SHIFT when initiating a get or check out operation from an IDE. See Specifying Revisions during Source Control Operations on page 77. 2 Depending on your IDE and the menu item you selected, the dialog will open to one of the following tabs: File Detail History Relationships Merge - Diff Customize See the following sections for information about each tab. Development Interface Implementation Guide

74 Chapter 4 Using Dimensions with IDE Projects File Detail Tab The File Detail tab shows both system and user-defined attributes for the latest non-extracted revision of the file you selected in the IDE. Do any of the following: Click the Get button to obtain a read-only copy of this revision. Click the Check Out button to check out (extract) this revision. Click the Pedigree button to display the file s pedigree. For more information, see the next section. Serena ChangeMan Dimensions

Viewing Source Control Information 75 Viewing a File s Pedigree The Pedigree dialog box illustrates how the revisions of a file are related in terms of time and origin. To better view complex pedigrees containing many revisions and/or many branchings and mergings of revisions, you can adjust the display of the graph as follows: Click this button... To... Size the graph to fit the dialog box Zoom in or zoom out Show/hide the background image Change the text color Change the line color Show/hide the axis titles Development Interface Implementation Guide

76 Chapter 4 Using Dimensions with IDE Projects Click this button... To... Flip the orientation of the axis Change the type of line that connects the revision icons Select/deselect all revisions. NOTE When invoked from an IDE, this feature has no use. From the desktop client, right-clicking selected revisions opens a pop-up menu of source control operations. You can have multiple Pedigree dialogs open at the same time. History Tab The History tab shows information about each revision of which ever file you selected in the IDE. You may also use the History tab to get or check out a specific revision of a file. Serena ChangeMan Dimensions

Viewing Source Control Information 77 Do any of the following: Select the Only show Item Revision history contained in the current workset check box, to limit the display. Select a revision and do any of the following: Click the Relationships tab to view relationship information about the revision. Click the Get button to obtain a read-only copy of the revision. Click the Check Out button to check out (extract) the revision. Click the Check In button to check in (return) the revision. Click the Cancel Check button to undo a check out of the revision. Click the Action Item button to advance the revision to the next level in its lifecycle. Click the Pedigree button to display the file s pedigree. For more information, see Viewing a File s Pedigree on page 75. Specifying Revisions during Source Control Operations To allow for the selection of specific revisions, you can invoke the History tab by pressing CTRL + SHIFT when initiating a get or check out operation from within an IDE. When invoked in this way, the Close button is replaced by a Select button and the buttons for source control operations are disabled. To specify a revision during a source control operation: 1 Press CTRL + SHIFT while initiating a get, check out, undo check out, or check in operation from an IDE. The History tab appears. Development Interface Implementation Guide

78 Chapter 4 Using Dimensions with IDE Projects NOTE For most IDEs with get or check out dialogs, press CTRL + SHIFT while clicking the dialog button that initiates the source control operation (OK, Get, Check Out). For IDEs without intervening dialogs, press CTRL + SHIFT while invoking the operation from the IDE s menu. 2 Select the revision you want from the list. NOTE Click the other tabs to view details specific to the selected revision. 3 Click the Select button. NOTE The History tab will appear for each file in turn. The source control operation now proceeds as usual but with the selected revision of the file instead of the latest revision. Serena ChangeMan Dimensions

Viewing Source Control Information 79 Relationships Tab The Relationships tab shows the relationships recorded in Dimensions for the revision you selected in the History tab or the default latest item revision of the file you selected in the IDE. Use the following tabs to view specific relationship information: Items: All items related to the selected revision by userdefined Dimensions Item to Item relationships. Design Parts: Owning and Using design parts. Change Documents: All related change documents and their relationship to the selected file revision. Click the Action Change Document button to advance a change document to the next level of its lifecycle. Secondary Change Documents: All related change documents in the secondary catalog and their relationships to the selected file revision. Click the Action Change Document button to advance a change document to the next level of its lifecycle. Development Interface Implementation Guide

80 Chapter 4 Using Dimensions with IDE Projects Built Items: All Dimensions items built from and used to build the selected file revision. The build process must have been carried out using Dimensions Make or Dimensions IP Build for items to appear in this list. Environment Items: All items in Dimensions related by the system-defined environment relationship to the selected file revision. Work Sets: All Dimensions worksets in which the selected file revision appears. Baselines: All Dimensions baselines that contain the selected file revision. Releases: All Dimensions releases that contain the selected file revision. Customers: All Dimensions customers that have been forwarded a release containing the selected file revision. Serena ChangeMan Dimensions

Viewing Source Control Information 81 Merge - Diff Tab The Merge - Diff tab allows you to load selected revisions into the Merge Tool. To perform a merge or difference on revisions: 1 Do any of the following: Select the Display only conflicting revisions check box to limit the display to conflicting revisions. Select the Include current Work File check box to include the current workfile in the list. Click the Add File button to include other files accessible from your computer in the list. Click the Remove File button to remove a file that you added from the list. Click the Pedigree button to display the pedigree of the file you selected in the IDE. For more information, see Viewing a File s Pedigree on page 75. Development Interface Implementation Guide

82 Chapter 4 Using Dimensions with IDE Projects 2 Select the revisions and/or files you want to difference or merge. 3 Do one of the following: Click the Merge button to invoke the Merge Tool for merging. Click the Diff button to invoke the Merge Tool for differencing. For more information The Merge Tool opens. See the Serena ChangeMan Dimensions User s Guide or the Merge Tool s online help. NOTE You can configure the Merge Tool to launch during check in if the tip revision is newer than the revision you started with. For more information, see Configuring Source Control Options on page 32. Serena ChangeMan Dimensions

Viewing Source Control Information 83 Customize Tab The Customize tab allows you to customize which information is displayed by the other tabs. The right pane shows the current configuration. The left pane lists the attributes available for the object selected in the right pane. To customize the display: 1 Select an object in the right pane. 2 Do any of the following: To add an attribute to the selected object: a) Select an attribute in the left pane. b) Click the Add button. To remove an attribute from the selected object: a) Select an attribute in the right pane. Development Interface Implementation Guide

84 Chapter 4 Using Dimensions with IDE Projects b) Click the Remove button. To change the order in which attributes are displayed: a) Select an attribute in the right pane. b) Click either the Up or the Down button. Display customizations for each user are recorded in the Windows Registry. Viewing File or Project Differences Difference types The Dimensions Development Interface enables you to view: File Differences: The line-by-line differences between the file open in the IDE and its ancestor Project Differences: The differences between the files in the IDE project directory and the files in the corresponding Dimensions workset directory Revision Differences: The line-by-line differences between specific revisions of a file. For more information, see Merge - Diff Tab on page 81. Special Considerations The Project Difference mode is not applicable to repository based IDEs such as PowerBuilder and VisualAge for Java. You can bypass the choice dialog by making File Difference mode the default. To do so, add the following entry to the dm.cfg file: DM_SCC_USEPROJDIFF N Serena ChangeMan Dimensions

Viewing File or Project Differences 85 Procedure To view file or project differences: 1 Invoke Dimensions differencing from your IDE. For the IDE specific menu command, see Part 2: IDE Reference, on page 89. The following dialog box appears. 2 Do one of the following: Click the File Differences button and continue to the next section. Click the Project Differences button and continue to Viewing Project Differences, on page 86. Development Interface Implementation Guide

86 Chapter 4 Using Dimensions with IDE Projects Viewing File Differences After you click the File Differences button, the Merge Tool opens and displays the line-by-line differences between the file open in the IDE and its ancestor in the Dimensions repository. For more information See the Serena ChangeMan Dimensions User s Guide or the Merge Tool s online help. Viewing Project Differences After you click the Project Differences button, the Project Merge Tool opens and displays the differences between the files in the IDE project directory and the files in the corresponding Dimensions workset directory. The scope of the comparison is defined by the directory containing the SCC project marker file; any Dimensions out of project directory references are not displayed by this operation. Serena ChangeMan Dimensions

Viewing File or Project Differences 87 Interpret the display of the Project Merge Tool as follows: This icon... Means... The file was added. The file was modified. The file was deleted. The file was not modified. T I P To view a line-by-line listing of the changes to one of the listed files, double-click on the file to open it in the Merge Tool. For more information See the Serena ChangeMan Dimensions User s Guide or the Project Merge Tool s online help. Development Interface Implementation Guide

88 Chapter 4 Using Dimensions with IDE Projects Serena ChangeMan Dimensions

89 Part 2: IDE Reference This chapter Starts on page DOORS 91 FrontPage 117 PowerBuilder 147 Rational Rose 167 TestDirector 181 Visual Basic 237 Visual C++ 259 Visual InterDev 275 Visual Studio.NET 303 WebSphere Studio Application 321 Developer 5 (Eclipse 2 & 3) Development Interface Implementation Guide

90 Part 2 IDE Reference Introduction Contents and purpose Additional information This part of the manual contains chapters specific to setting up and using the Dimensions Development Interface with each supported IDE. The purpose of this part of the manual is to help you set up and use the Dimensions Development Interface with your IDE. Use this part of the manual in conjunction with these additional sources of information: For more information about... Source control concepts Setting up and configuring the Dimensions Development Interface to work with SCC compliant IDEs Setting up and configuring the Dimensions Development Interface to work with COM compliant IDEs Default and advanced options Setting up and using your IDE with source control See... Chapter 1, Overview of Dimensions Source Control, on page 23 Chapter 2, Integrating SCC Projects with Dimensions, on page 31 Chapter 3, Integrating COM Projects with Dimensions, on page 47 Chapter 4, Using Dimensions with IDE Projects, on page 61 The documentation provided by the vendor of your IDE Serena ChangeMan Dimensions

91 5 DOORS In this Chapter For this section... See page... Introduction 92 Accessing Supported Features 92 Setting Up the Integration 94 Using the Integration 105 Development Interface Implementation Guide

92 Chapter 5 DOORS Introduction Purpose This chapter has four purposes: List the Dimensions features available through Telelogic DOORS 6, 7 and 7.1, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up the integration to Dimensions source control and issue management For more information Help you use the integration to Dimensions source control and issue management See Part 1: The Dimensions Development Interface, on page 21. Accessing Supported Features What is supported? The integration to DOORS enables you to: Export DOORS baselines into Dimensions as Dimensions items Export DOORS objects into Dimensions as Dimensions change documents and relate them to the appropriate Dimensions item Create Dimensions relationships that represent the links between DOORS objects Use change management rules to require that there be an approved DOORS requirement before code/documents can be checked out of Dimensions for work, thus ensuring traceability of all work Serena ChangeMan Dimensions

Accessing Supported Features 93 Track project status with reports that show the status of approved requirements as they relate to project milestones The DOORS integration does not support the Dimensions features used with traditional IDEs: differencing, merging, and operations on previous revisions. See the following table for information on accessing supported features. To... Select... For more information see... Configure the DOORS/Dimensions integration Configure Dimensions to open DOORS requirements from Dimensions change documents Export a DOORS baseline to Dimensions Lock an item (exported baseline) in Dimensions Unlock an item (exported baseline) in Dimensions Export a DOORS object to a Dimensions change document View the Dimensions change document associated with a DOORS object Dimensions Configure (See the text.) Dimensions Check In Baseline Archive Dimensions Lock Baseline Item Dimensions Unlock Baseline Item Dimensions Export Object to Change Document Dimensions Browse Object Associated Change Document Configuring the DOORS- Dimensions Integration on page 96 Configuring Dimensions to Open DOORS Requirements from Dimensions Change Documents on page 104 Checking In a DOORS Baseline on page 106 Locking a Baseline Item on page 108 Unlocking a Baseline Item on page 108 Exporting DOORS Objects to Dimensions Change Documents on page 109 Browsing Change Documents Associated with DOORS Objects on page 110 Development Interface Implementation Guide

94 Chapter 5 DOORS To... Select... For more information see... Update DOORS with current Dimensions change document status View Dimensions change document status from DOORS Log the integration into Dimensions Launch Dimensions desktop client Open DOORS requirements from Dimensions change documents Dimensions Update Object Change Document Statuses Edit Object Properties Attributes Dimensions Login Dimensions Open Dimensions (See the text.) Updating DOORS with Change Document Status from Dimensions on page 110 Viewing Dimensions Change Document Status from within DOORS on page 111 Logging the Integration into Dimensions on page 105 Serena ChangeMan Dimensions User s Guide Opening a DOORS Requirement from a Dimensions Change Document on page 111 Run reports (See the text.) Running Reports on page 113 NOTE The Dimensions menu is available only from the Formal module window. You must open a formal module in order to access the menu. Setting Up the Integration Contents For more information This section contains information about setting up the integration between Dimensions and DOORS. This entails using the Dimensions Administration Console. See the Serena ChangeMan Dimensions Process Modeling User s Guide. Serena ChangeMan Dimensions

Setting Up the Integration 95 Installing the Integration Install the following to your system: DOORS 6.0, 7.0, or 7.1 The Dimensions client The Doors-Dimensions Custom Integration Configuring User IDs Your Dimensions user ID must have the Dimensions roles necessary to create, extract, and return Dimensions items of the type associated with DOORS objects. Configuring Dimensions You must configure a Dimensions product to work with the integration to DOORS. This entails the following: Choose the Dimensions product that will serve as the repository for DOORS objects. Configure a Dimensions item type to associate with DOORS objects. IMPORTANT! You must deselect the When creating a new item type, generate an item identifier automatically if one is not supplied option of the item type. Configure a Dimensions change document type to associate with DOORS objects. This change document type must include: An attribute named TITLE of data type Char A relationship named Next of the relationship class type of Info Development Interface Implementation Guide

96 Chapter 5 DOORS Valid relationships to the item type configured above and the change document type itself Special Considerations You can use existing types as long as they have the required characteristics. However, DOORS objects will be easier to track in Dimensions if you create unique types for that purpose. You must configure these types with lifecycles, templates, etc. according to what makes sense for your own processes. The integration does not impose specific requirements in this area, except that these things must be configured. For more information You can require that there be an approved DOORS requirement before code can be checked out of Dimensions for work, by turning on change management rules for the change document type associated with DOORS requirements and relating those change documents to your code/ document items. See the Serena ChangeMan Dimensions Process Modeling User s Guide for procedures on creating and modifying Dimensions object types. Configuring the DOORS-Dimensions Integration Once you have configured a Dimensions product for use with the integration, you must configure the integration to access that Dimensions product and enable the features of the integration that you wish to use. Serena ChangeMan Dimensions

Setting Up the Integration 97 To configure the integration: 1 Open a formal module. The Formal module window appears. Development Interface Implementation Guide

98 Chapter 5 DOORS 2 Select Dimensions Configure. The Configuration dialog box appears. Dimensions configuration values 3 Using the Current and Default lists, select the Dimensions configuration values to use with the current module and/or select default values. a Product ID: Select the Dimensions product to use. Serena ChangeMan Dimensions

Setting Up the Integration 99 b Workset ID: Select the Dimensions workset to use. c Design Part Specification: Click the Browse button to select the Dimensions design part to use. d DOORS Baseline Archive Item Type: Select the Dimensions item type to use. Check In Baseline Archive Options e DOORS Object Change Document Type: Select the Dimensions change document type to use. 4 Do any of the following to configure how DOORS baselines are exported to Dimensions items: To export DOORS objects to Dimensions before checking in a DOORS baseline, select the Export contained objects before check in Baseline Archive option. To create relationships in Dimensions between items and change documents, select the On export, create relationship between Item associated with Baseline and Change Documents associated with exported objects option. NOTE The preceding check box must be selected in order to enable this check box. Development Interface Implementation Guide

100 Chapter 5 DOORS To map DOORS module attributes to Dimensions item attributes, click the Map Attributes button. The Check In Attributes Configuration dialog box appears. a) Select a DOORS attribute in the DOORS Module Attributes list. b) Do one of the following: To map to an existing Dimension item attribute, select one from the Item Attributes list. To map to a new Dimensions item attribute, select <new> from the Item Attributes list. c) Click the Add Mapping button. Serena ChangeMan Dimensions

Setting Up the Integration 101 d) If you selected <new> above, the Auto Create Dimensions Attribute dialog box appears. Modify the fields as needed and click OK. e) The new mapping appears in the Mapped Attributes for Baseline Archive Check In list. f) To remove a mapping, select it in the Mapped Attributes for Baseline Archive Check In list and click the Remove Mapping button. Export Object Options g) Click OK. 8 Do any of the following to configure how DOORS objects are exported to Dimensions change documents: To export only those DOORS objects that have changed since the last baseline, select the Do not export Objects if they have not changed since the last Baseline option. To create relationships between existing change documents and any new ones created during export, select the Create relationship between new Change Document created on export and existing Change Document option. To create relationships between new change documents created during export and any already associated with Development Interface Implementation Guide

102 Chapter 5 DOORS linked objects, select the Create relationship between new Change Document created on export and Change Documents associated with linked Objects option. To map DOORS object attributes to Dimensions change document attributes, click the Map Attributes button. The Export Attributes Configuration dialog box appears. a) Select a DOORS attribute in the DOORS Object Attributes list. b) To map to an existing Dimension change document attribute, select one from the Change Document Attributes list. c) To map to a new Dimensions change document attribute, select <new> from the Change Document Attributes list. d) Click the Add Mapping button. Serena ChangeMan Dimensions

Setting Up the Integration 103 e) If you selected <new> above, the Auto Create Dimensions Attribute dialog box appears. Modify the fields as needed and click OK. f) The new mapping appears in the Mapped Attributes for Object Export list. g) To remove a mapping, select it in the Mapped Attributes for Object Export list and click the Remove Mapping button. h) Click OK. Preferences 9 Preferred Editor: Enter the path to the program with which you want to view change documents. 10 Preferred File Extension: Enter the file extension to use when viewing change documents. NOTE Regardless of the file extension you choose, the content of change documents is always formatted according to the template associated with the change document type in the process model. 11 If you have selected one or more requirements in the current module, you can specify which Dimensions design part the Development Interface Implementation Guide

104 Chapter 5 DOORS change documents associated with those requirements will be related to. a Click the Requirements Part Specs button. The Design Part Selection dialog box appears. NOTE If the button is not enabled, no requirements are selected in the current module. b Select a design part and click OK. NOTE If a different design part is already assigned, a prompt appears to confirm the change. 12 Click OK. Configuring Dimensions to Open DOORS Requirements from Dimensions Change Documents From within Dimensions, you can select a change document and cause DOORS to open to the associated DOORS requirement. The following procedure adds a menu item to the Dimensions desktop client for this purpose. To enable the launching of DOORS from within Dimensions: 1 From the Dimensions desktop client, select Tools Customize Menu Sets/Tools. The Customize dialog box appears. 2 Select the Tools tab. 3 Click the New button. A new item appears in the Menu text of user-modifiable tools list. 4 Change the item s text to the following: DOORS!Go to DOORS Requirement for selected Change Document Serena ChangeMan Dimensions

Using the Integration 105 5 In the Command field, enter the full path to the DmRunCmd executable. In a default install of Doors 6, the path would be: "C:\Program Files\Telelogic\DOORS 6\lib\dxl\addins\Dimensions\DmRunCmd.exe" 6 Enter the following in the Arguments field: -e "C:\Program Files\Telelogic\DOORS 6\bin\doors.exe" -d $[Description] NOTE The above example assumes a default DOORS installation. Modify it as necessary to reflect the actual path to your doors.exe file. 7 Click the OK button. The desktop client now has a new menu item: Tools Doors Go to DOORS Requirement for selected Change Document. Using the Integration Logging the Integration into Dimensions The Dimensions Login dialog box will appear when ever the integration needs to establish a connection with Dimensions. Or, you can invoke the Login dialog box at any time to connect the integration to Dimensions. To invoke the Dimensions Login dialog box, select Dimensions Login from the Module window. For more information about logging into Dimensions, see Connecting to Dimensions on page 35. Development Interface Implementation Guide

106 Chapter 5 DOORS Checking In a DOORS Baseline Checking in a DOORS baseline creates items and change documents in Dimensions according to the settings you made in the Configuration dialog box. For information on configuring the integration, see Configuring the DOORS-Dimensions Integration on page 96. To check in a baseline: 1 Open a formal module. The Formal module window appears. 2 Select Dimensions Check In Baseline Archive. The Check In Baseline Archive dialog box appears. Serena ChangeMan Dimensions

Using the Integration 107 3 Dimensions Item Revision: The value shown here will be used as the revision number for the item you are checking in. This value cannot be edited during check in. 4 Next Version: Select an option to determine what the revision number of the next revision will be. 5 Suffix: Select a Dimensions named branch from the Suffix list. The item revision number then takes the form of: NamedBranch#RevisionNumber For example: PlanB#4.3 NOTE This field is enabled only if named branches have been defined for the workset. For information on creating named branches, see the Serena ChangeMan Dimensions Process Modeling User s Guide. 6 Change Document ID: Enter the ID of the Dimensions change document that called for the changes you are now checking in. NOTE This field is required if change management rules are in effect. Otherwise, it is disabled. 7 Comments: Enter a description of the baseline you are checking in. 8 Click OK. You are prompted to confirm the check in. 9 Click Yes. The Export Objects dialog box appears with a list of any objects that are unchanged since the last baseline or which have a header but no associated text. 10 Click Yes. A results dialog box appears. Development Interface Implementation Guide

108 Chapter 5 DOORS Special Considerations You will be prompted to save changes to the DOORS module, if you have not already. If the dialog includes the message: "Checkin Failed, but new DOORS baseline was created." See Fixing a Failed Baseline Check In on page 112 for information on resolving the problem. 11 Click Close to dismiss the results dialog box. Locking a Baseline Item Locking a baseline item locks the Dimensions item that represents the DOORS module. This keeps other users from creating a new revision of the DOORS module in Dimensions. To lock a baseline: 1 Open a formal module. The Formal module window appears. 2 Select Dimensions Lock Baseline Item. A confirmation dialog box appears. 3 Click Confirm. A results dialog box appears. NOTE If change management rules are on, you will be prompted for the ID of the Dimensions change document that called for the changes you are now checking the module out to make. 4 Click Close. Unlocking a Baseline Item Unlocking a baseline item unlocks the Dimensions item that represents the DOORS module. This allows other users to create a new revision of the DOORS module in Dimensions. Serena ChangeMan Dimensions

Using the Integration 109 To lock a baseline: 1 Open a formal module. The Formal module window appears. 2 Select Dimensions Unlock Baseline Item. The Check In Baseline Archive dialog box appears. 3 Select Dimensions Unlock Baseline Item. A confirmation dialog box appears. 4 Click Confirm. A results dialog box appears. 5 Click Close. Exporting DOORS Objects to Dimensions Change Documents Exporting DOORS objects creates change documents in Dimensions according to the settings you made in the Configuration dialog. See Export Object Options on page 101. To export objects to change documents: 1 Open a formal module. The Formal module window appears. 2 Select objects in the module (shift-click). 3 Select Dimensions Export Object Options. A confirmation dialog box appears. NOTE If you selected the Do not export Objects if they have not changed since the last Baseline option in the Configuration dialog box, the confirmation dialog box will include a list of any unchanged objects that are currently selected. These objects will not be exported. 4 Click Yes. Development Interface Implementation Guide

110 Chapter 5 DOORS Browsing Change Documents Associated with DOORS Objects You can browse the Dimensions change documents associated with DOORS objects from within DOORS. To browse change documents: 1 Open a formal module. The Formal module window appears. 2 Select an object in the module (shift-click). 3 Select Browse Object Associated Change Document. The Dimensions change document associated with the DOORS object opens. NOTE The change document opens in the application you specified in the Preferred Editor field of the Configuration dialog box. See Configuring the DOORS-Dimensions Integration on page 96. Updating DOORS with Change Document Status from Dimensions You can update DOORS with the current status of Dimensions change documents. To update change document status: 1 Open a formal module. The Formal module window appears. 2 Select Dimensions Update Object Change Document Statuses. A completion message appears. 3 Click OK. Serena ChangeMan Dimensions

Using the Integration 111 Viewing Dimensions Change Document Status from within DOORS You can view the status of Dimensions change documents from within DOORS. NOTE See the previous procedure to ensure the status is current. To view change document status: 1 Open a formal module. The Formal module window appears. 2 Select an object (shift-click). 3 Select Edit Object Properties. The Object properties dialog box appears. 4 Select the Attributes tab. The Dimensions change document status is stored in the PVCS Chdoc Status attribute. Opening a DOORS Requirement from a Dimensions Change Document From within Dimensions, you can select a change document and cause DOORS to open to the associated DOORS requirement. You must configure this feature before it can be used. See Configuring Dimensions to Open DOORS Requirements from Dimensions Change Documents on page 104. To open a requirement from a change document: 1 Select a change document in Dimensions desktop client. 2 Select Tools DOORS Go to DOORS Requirement for selected Change Document. 3 The DOORS login dialog box appears. Login to DOORS. Development Interface Implementation Guide

112 Chapter 5 DOORS 4 DOORS opens to the requirement associated with the selected change document. Fixing a Failed Baseline Check In If you receive an error like the one above during a baseline check in, you must: 1 Resolve the underlying problem. 2 Check in the DOORS baseline that was created during the failed attempt to check in. Resolving the Underlying Problem Before you can export the DOORS baseline to Dimensions, you must resolve the underlying problem that caused the check in to fail. Possible causes include: Your Dimensions user ID does not have the roles necessary to create, modify, and check in items in the Dimensions product. An item already exists with the same name as would be used for the new item for the DOORS baseline. Serena ChangeMan Dimensions

Using the Integration 113 Checking In a Baseline that Failed to Check In Once you have resolved the underlying problem, you can check in the baseline. 1 Open the formal module that failed to check in. The Formal module window appears. 2 Select File Baseline Open. The Open Baseline Archive dialog box appears. 3 Select the baseline that failed to check in. 4 Click OK. The baseline opens in a Module window. 5 Select Dimensions Check In Baseline Archive. The Check In Baseline dialog box appears. 6 Complete the dialog box as needed and click OK. The check proceeds as per the normal check in process. Running Reports The integration to DOORS includes two sqlplus reports which can be run against the Dimensions database. These reports can list all items that are: Related directly or indirectly to DOORS change documents NOT related directly or indirectly to DOORS change documents This allows you to track those code or document files that you have placed under Dimensions source control and related to change documents derived from DOORS requirements. NOTE These reports are Oracle specific. They cannot be used with a DB2 database. Development Interface Implementation Guide

114 Chapter 5 DOORS To run a report: 1 Open a command prompt. 2 Log in to sqlplus. 3 Change to the reports directory of the Dimensions plug-in for DOORS. By default, the path would be: C:\Program Files\Telelogic\DOORS 6\lib\dxl\addins\Dimensions\reports 4 Enter the following on the command line and press ENTER: sqlplus DatabaseUserID/DatabasePW@NetServiceName @DOORSRels.sql ReportType Database Product Workset Part ItemType ChangeDocType Where: DatabaseUserID is a user ID with the reporting role in Dimensions DatabasePW is the password for the user ID NetServiceName is a valid Oracle net service name ReportType is one of the following: DOORSRELS - Lists all items that are related directly or indirectly to DOORS change documents. NODOORSRELS - Lists all items that are NOT related directly or indirectly to DOORS change documents. Database is the Dimensions base database used with the DOORS inetgration Product is the Dimensions product used with the DOORS inetgration Workset is the Dimensions workset used with the DOORS integration Part is the Dimensions part used with the DOORS inetgration Serena ChangeMan Dimensions

Using the Integration 115 ItemType is the Dimensions item type used with the DOORS integration ChangeDocType is the Dimensions change document type used with the DOORS integration 5 The output is written to a file named DOORSRelsReport.txt in the directory in which the report was run. NOTE Reports on larger databases will require more time. Doors-specific Usability Notes Checking In Linked Modules NOTE Under certain circumstances, when checking in modules with links from another module, the following dialog may appear "Error: Unlock Module failed: no such file or directory... lock.dtc". Investigation shows this error can be safely ignored. This occurs when the linked object has been changed prior to the checkin. If Doors is restarted before changing the module the error does not occur. Checking In Modules with Outgoing Links When checking in a module with outgoing links, the target modules in the link (the link is "FROM" the module being checked in ) must also be opened in Doors in order for the source module's baseline item to be created in Dimensions. Having the target module open allows the source module's item to be created and all expected relationships to be formed. Development Interface Implementation Guide

116 Chapter 5 DOORS Serena ChangeMan Dimensions

117 6 FrontPage In this Chapter For this section... See page... Introduction 118 Accessing Supported Features 118 Setting Up Source Control Projects 119 Using Source Control 122 Development Interface Implementation Guide

118 Chapter 6 FrontPage Introduction Purpose This chapter has four purposes: List the Dimensions features available through Microsoft FrontPage 2000 and 2002, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within the IDE See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Accessing Supported Features What is supported? FrontPage supports a subset of the source control features available through the Dimensions Development Interface. Specific limitations include: Previous revisions cannot be checked out from within FrontPage. See Checking Out a Previous Revision on page 125. Get is not supported by this IDE. Serena ChangeMan Dimensions

Setting Up Source Control Projects 119 Dimensions merge and differencing tools cannot be invoked from this IDE. To... Select... For more information see... Check out files Edit Check Out Checking Out Files on page 123 Undo check out of files Edit Undo Check Out Undoing a Check Out on page 123 Check in files Edit Check In Checking In Files on page 124 Add webs to source control Remove webs from source control (Use the Microsoft Management Console) (Use the Microsoft Management Console) Adding Web Projects to Source Control on page 120 Disconnecting Web Projects from Source Control on page 122 Setting Up Source Control Projects Contents Prerequisites This section contains information about setting up the Dimensions Development Interface to work with FrontPage. Before proceeding, you must do the following: Install Dimensions, FrontPage Server Extensions, and the Dimensions Development Interface to your web server. See the Serena ChangeMan Dimensions Installation Guide. Configure web server security. See Configuring Web Server Security on page 50. For more information Configure default settings for new source control projects. See Configuring Source Control Defaults on page 52. See Chapter 3, Integrating COM Projects with Dimensions, on page 47. Development Interface Implementation Guide

120 Chapter 6 FrontPage Adding Web Projects to Source Control To place a web project under source control: 1 Create a web project in FrontPage. 2 Close FrontPage. 3 From the web server, launch the Microsoft Management Console. IMPORTANT! Your Windows user account must have the rights needed to launch the Microsoft Management Console. This user must also have the Dimensions roles necessary to create projects and add files. All FrontPage expanded webs appear in the Console root view in the left pane of the Microsoft Management Console. Web server Webs NOTE The appearance of this dialog varies depending on how you launch it. 4 Right click on the web you want to add to source control, and select Properties from the menu that appears. The Properties dialog box appears. Serena ChangeMan Dimensions

Setting Up Source Control Projects 121 5 Select the Server Extensions tab. 6 Select Use external from the Version control drop-down list. 7 Click OK. The Source Control Project dialog box appears. 8 By default, the source control project is named after the web project. You can enter a new name in the Source control project name field. You must precede the name with a dollar sign ($) and a forward slash (/). 9 Click OK. The file icons in the Folders, All Files, and Navigation views change to indicate that the files are under source control: No source control Under source control Green dots Development Interface Implementation Guide

122 Chapter 6 FrontPage Disconnecting Web Projects from Source Control Disconnecting a project from source control does not delete the source control files; it only removes the association with the Dimensions project. You can always reconnect the project to source control later. To disconnect a web project from source control: 1 Launch the Microsoft Management Console. 2 Right-click on the FrontPage directory, and select Properties from the contextual menu that appears. 3 Select the Server extensions tab. 4 Select None from the Version control drop-down list. 5 Click the Apply button. Using Source Control Contents For more information This section contains procedural information about viewing and editing files that are under source control. See the Help and documentation that came with your IDE for more information on using source control with your IDE. Serena ChangeMan Dimensions

Using Source Control 123 Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. FrontPage provides three ways to check out a file: You can Select the file and select Edit Check Out Right-click on the file and select Check Out Double-click on the file Then The file is checked out. The file is checked out. You are prompted with a message to check out the file. Click YES. The file is checked out and the application associated with the file is launched. The icons in the Folders, All Files, and Navigation views change to indicate that the files are checked out. When you check out files, this is What you would see: What others would see: Red check mark Locks A lock next to the file icon indicates that the file is currently locked by another user and cannot be checked out. To see who locked the file, right-click on the locked file icon. Undoing a Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number Development Interface Implementation Guide

124 Chapter 6 FrontPage that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 Do one of the following: Select the file and select Edit Undo Check Out. Right-click on the file and select Undo Check Out. A confirmation dialog box appears. 2 Click YES. The file is unlocked and any changes that were saved since the file was checked out are discarded. Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. To check in files: 1 Select the files and do one of the following: Select Edit Check In Right-click and select Check In The Check In dialog box appears. 2 Enter a description of the changes made to the files in the Comments on version field. 3 If you want to check in your changes but continue to work on the files, select the Keep files checked out check box. 4 Click OK. The files are checked in. Serena ChangeMan Dimensions

Using Source Control 125 Checking Out a Previous Revision By design, FrontPage allows you to check out only the latest revision of a file. However, you can get a previous revision using the Dimensions desktop client, then update the latest revision with it. The previous revision is then available to check out from within your IDE as the latest revision. See Checking Out a Previous Revision on page 58. Adding New Files If a web project is under source control and you add a file to it, the file is automatically added to source control. Development Interface Implementation Guide

126 Chapter 6 FrontPage Serena ChangeMan Dimensions

127 7 JBuilder In this Chapter For this section... See page... Introduction 128 Accessing Supported Features 128 Setting Up Source Control Projects 130 Using Source Control 139 Development Interface Implementation Guide

128 Chapter 7 JBuilder Introduction Purpose This chapter has four purposes: List the Dimensions features available through Borland JBuilder X, 9, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within the IDE See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Accessing Supported Features What is supported? JBuilder supports the full set of source control features available through the Dimensions Development Interface. See the following table. To... Select... For more information see... Get files Team Get Getting Files on page 139 Check out files Team Checkout Checking Out Files on page 140 Serena ChangeMan Dimensions

Accessing Supported Features 129 To... Select... For more information see... Undo check out of files Check in files View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships View file or projectlevel differences Select source control provider for project Connect project to source control Disconnect project from source control Add files to source control Remove files from source control Connect workstation to existing source control projects Set options for source control integration Team Uncheckout Team Checkin Or Team Commit Browser Team Properties Team Serena ChangeMan Dimensions Diff Team Select Project VCS Team Connect Project to Serena ChangeMan Dimensions repository project Team Disconnect Project from Serena ChangeMan Dimensions repository project Team Add Or Team Commit Browser Team Remove Team Pull Project from Serena ChangeMan Dimensions repository Team Configure Serena ChangeMan Dimensions Undoing Check Out on page 141 Checking In Files on page 142 Viewing Source Control Information on page 72 Viewing File or Project Differences on page 84 Selecting the Source Control Provider for a Project on page 130 Connecting JBuilder Projects to Source Control on page 131 Disconnecting Workstation Projects from Source Control on page 137 Adding Files to Source Control on page 132 Removing Files from Source Control on page 136 Connecting Additional Workstations to a Source Control Project on page 135 Configuring Integration Options on page 137 Development Interface Implementation Guide

130 Chapter 7 JBuilder To... Select... For more information see... Launch Dimensions desktop client Team Run Serena ChangeMan Dimensions The Serena ChangeMan Dimensions User s Guide Setting Up Source Control Projects Contents For more information This section contains information about setting up the Dimensions Development Interface to work with JBuilder. See Chapter 2, Integrating SCC Projects with Dimensions, on page 31. Selecting the Source Control Provider for a Project To set Dimensions as the source control provider: 1 Save the JBuilder project if you have not already. 2 Select Team Select Project VCS. NOTE If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. Serena ChangeMan Dimensions

Setting Up Source Control Projects 131 The Select Project VCS dialog box appears. 3 Select Serena ChangeMan Dimensions from the Version control system list. What s next? 4 Click OK. You must now connect the JBuilder project to source control. See the next section. Connecting JBuilder Projects to Source Control To connect a project to source control: 1 Select Team Connect Project to Serena ChangeMan Dimensions repository project. NOTE If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. 2 The Select workset directory for project dialog box appears. By default, your default workset and its top design part are Development Interface Implementation Guide

132 Chapter 7 JBuilder selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. 3 A Dimensions SCC dialog box appears stating that the operation completed. Click OK. 4 A second Dimensions SCC dialog box states that the project is being opened in the workset. Click OK. 5 A dialog box appears stating that the project is now connected to the Serena ChangeMan Dimensions repository. Click OK. What s next? You must now add the JBuilder source files to source control. See the next section. Adding Files to Source Control Using the methods described below, you can add entire projects to source control for the first time or add new files to existing source controlled projects. There are two ways to add files to source control: The Add files to Serena ChangeMan Dimensions repository dialog box. This dialog box allows you to keep the files checked out after they are added to source control. See The Add files to Serena ChangeMan Dimensions repository Dialog Box on page 133. The Commit Browser. The Commit Browser allows you to enter a unique description for each file and view the file source. See The Commit Browser on page 134. Use which ever method best meets your needs. Serena ChangeMan Dimensions

Setting Up Source Control Projects 133 The Add files to Serena ChangeMan Dimensions repository Dialog Box To add files to source control: 1 Select a file that is not under source control. 2 Select Team Add. The Add files to Serena repository dialog box appears. 3 Select or deselect files as needed. IMPORTANT! If you are adding a project to source control, you must include the *.jpx file. 4 To check out the files immediately after adding them to source control, select the Keep checked out check box. 5 Enter a comment in the Comment field. 6 Click the Add button. The files are now under source control. Development Interface Implementation Guide

134 Chapter 7 JBuilder The Commit Browser To add files to source control: 1 Select Team Commit Browser. The Commit Browser appears. 2 Do any of the following: To deselect a file so it will not be added to source control, select No action in the Action column. IMPORTANT! If you are adding a project to source control, you must include the *.jpx file. Serena ChangeMan Dimensions

Setting Up Source Control Projects 135 To view the source code of a file, select the file and click on the Workspace Source tab. To enter a comment specific to an individual file, select the file and then enter the comment in the Individual Comment tab. To enter a comment to be applied to all of the files, use the Summary comment field. 3 Click the Commit button. The Version Control Operations dialog box appears with the results of the operation. Click Close to dismiss it. The files are now under source control. Connecting Additional Workstations to a Source Control Project After an IDE project has been created and added to source control, each developer can access it by opening it from source control, which creates a copy of the project on the developer s system. Once a developer has a local copy of a project, he can perform normal source control operations on it. To connect a workstation: 1 Select Team Pull Project from Serena ChangeMan Dimensions repository. The New Project from Serena repository dialog box appears. 2 Click OK. The Select SCC Project dialog box appears. (For a screen shot, see page 42.) 3 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Development Interface Implementation Guide

136 Chapter 7 JBuilder Select an existing workset from the Workset drop-down list. By default, your default workset is used. 4 Select the project you want to get from the Project dropdown list. 5 Click OK. The Browse for Folder dialog box appears. 6 Navigate to the parent directory to copy the project subdirectory and files to and click OK. The project opens in JBuilder. Removing Files from Source Control When you remove a file from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain in your workspace. To remove a file from source control: 1 Select the file. NOTE The file must be checked in. 2 Select Team Remove. The Remove files from Serena ChangeMan Dimensions repository dialog box appears. Serena ChangeMan Dimensions

Setting Up Source Control Projects 137 3 Select or deselect files as needed. 4 Click the Remove button. The files are no longer under source control. Disconnecting Workstation Projects from Source Control When you disconnect a workstation project from source control, the files remain in Dimensions for other workstations to access. You can reconnect the workstation to the source control project at a later time, if needed (see, Connecting Additional Workstations to a Source Control Project on page 135). To disconnect a workstation project: Select Team Disconnect Project from Serena ChangeMan Dimensions repository project. The workstation project is now disconnected from Dimensions. Configuring Integration Options You can configure the behavior of the integration regarding messages and the population of dialogs. Development Interface Implementation Guide

138 Chapter 7 JBuilder To configure options: 1 Select Team Configure Serena ChangeMan Dimensions. The Serena ChangeMan Dimensions Properties dialog box appears. 2 To specify where integration messages are displayed, choose one of the following from the Output Messages to list: Messages: Displays messages in the JBuilder Message pane. This is the default. Dialogs: Displays each message in its own dialog. Status Bar: Displays messages in the JBuilder Status bar. 3 By default, when you select files to operate on, all project files are displayed in the resulting dialog box (Checkin, Checkout, etc.), but only the files you select in JBuilder are selected for action. You can then manually select or deselect files in the dialog box list. To automatically select all source controlled files in the project, select the Allow auto-check files check box. Serena ChangeMan Dimensions

Using Source Control 139 Using Source Control Contents For more information This section contains procedural information about viewing and editing files that are under source control. See Chapter 4, Using Dimensions with IDE Projects, on page 61. Getting Files When you get a file, a read-only copy of the latest revision is placed in the workfile location. To get files: 1 Select at least one file you want to get. 2 Select Team Get. The Get files from Serena ChangeMan Dimensions repository dialog box appears. 3 Select or deselect files as needed. 4 To override the default get options, select the Show options check box. See Overriding Get Options on page 63. 5 Click Get. Development Interface Implementation Guide

140 Chapter 7 JBuilder Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. To check out files: 1 Select at least one file you want to check out. 2 Select Team Checkout. The Checkout files from Serena ChangeMan Dimensions repository dialog box appears. 3 Select or deselect files as needed. IMPORTANT! Check out the project file (*.jpx) if your changes will affect the project structure. Serena ChangeMan Dimensions

Using Source Control 141 4 To override the default check out options, select the Show options check box. See Overriding Check Out Options on page 64. 5 Click Checkout. Undoing Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 Select at least one file you want to release. 2 Select Team Uncheckout. The Uncheckout files from Serena ChangeMan Dimensions repository dialog box appears. 3 Select or deselect files as needed. 4 To override the default undo check out options, select the Show options button. See Overriding Undo Check Out Options on page 65. 5 Click Uncheckout. Development Interface Implementation Guide

142 Chapter 7 JBuilder Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. There are two ways to check in files: The Checkin files to Serena ChangeMan Dimensions repository dialog box. This dialog box allows you to keep the files checked out after checking in the new revisions. See The Checkin files to Serena ChangeMan Dimensions repository Dialog Box on page 142. The Commit Browser. The Commit Browser allows you to enter a unique description for each file and view the file source. See The Commit Browser on page 144. Use which ever method best meets your needs. The Checkin files to Serena ChangeMan Dimensions repository Dialog Box To check in files: 1 Select at least one file you want to check in. Serena ChangeMan Dimensions

Using Source Control 143 2 Select Team Checkin. The Checkin files to Serena ChangeMan Dimensions repository dialog box appears. 3 Do any of the following: Select or deselect files as needed. Select the Keep checked out check box to keep the files checked out. To override the default check in options, select the Show option check box. See Overriding Check In Options on page 66. Enter a description of the files in the Comment field. 4 Click Checkin. Development Interface Implementation Guide

144 Chapter 7 JBuilder The Commit Browser To check in files: 1 Select Team Commit Browser. The Commit Browser appears. 2 Do any of the following: To deselect a file so it will not be checked in, select No action or Undo Checkout in the Action column. To view the source code of the workspace revision, select the file and click on the Workspace Source tab. To view the source code of the current repository revision, select the file and click the Repository Source tab. Serena ChangeMan Dimensions

Using Source Control 145 To enter a comment specific to an individual file, select the file and then enter the comment in the Individual Comment tab. To enter a comment to be applied to all of the files, use the Summary comment field. 3 Click the Commit button. The Version Control Operations dialog box appears with the results of the operation. Click Close to dismiss it. Accessing Specific Revisions To get, check out, check in, or undo a check out on a specific revision of a file, rather than the latest revision, select the file and then select Team History. You can then select the revision you want from the History tab of the resulting dialog box. You can also invoke the History tab during get and check out operations by pressing CTRL + SHIFT while clicking the Get/ Checkout button in the get or check out dialog box. For more information, see History Tab on page 76. Development Interface Implementation Guide

146 Chapter 7 JBuilder Serena ChangeMan Dimensions

147 8 PowerBuilder In this Chapter For this section... See page... Introduction 148 Accessing Supported Features in PowerBuilder 148 Setting Up Source Control Projects in 149 PowerBuilder Using Source Control with PowerBuilder 157 PowerBuilder Specific Usability Notes 163 Development Interface Implementation Guide

148 Chapter 8 PowerBuilder Introduction Purpose This chapter has four purposes: List the Dimensions features available through Sybase PowerBuilder 8 and 9, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within PowerBuilder See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Accessing Supported Features in PowerBuilder What is supported? PowerBuilder supports all the source control features available through the Dimensions Development Interface except that previous revisions cannot be retrieved from the History tab unless it is invoked during a check out or get operation. See Accessing Specific Revisions on page 161. To... Select... For more information see... Get revisions Right-click Get Latest Revision Getting Objects on page 157 Serena ChangeMan Dimensions

Setting Up Source Control Projects in PowerBuilder 149 To... Select... For more information see... Check out revisions Right-click Check Out Checking Out Objects on page 158 Undo check out of revisions Right-click Undo Check Out Undoing Check Out on page 159 Check in revisions Right-click Check In Checking In Objects on page 160 View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships Connect workspaces to source control Add objects to source control Disconnect workspaces from source control Remove objects from source control Launch Dimensions desktop client (Enabled Menu depends on displayed painter and context) Right-click Show History Right-click Properties Right-click Add to Source Control Right-click Properties Entry Source Control Remove from Source Control Select Workspace Context Menu Run Source Control Management Tool or Entry Source Control Run Serena Dimensions Viewing Source Control Information on page 72 Accessing Specific Revisions on page 161 Connecting PowerBuilder Workspaces to Source Control on page 150 Adding Objects to Source Control on page 153 Disconnecting Workspaces from Source Control on page 157 Removing Objects from Source Control on page 156 The Serena ChangeMan Dimensions User s Guide Setting Up Source Control Projects in PowerBuilder For best results, you should create a hierarchy of directories so each target is located in its own directory beneath the Development Interface Implementation Guide

150 Chapter 8 PowerBuilder workspace directory. Dimensions will then create nested source control directories that reflect the structure of your workspace. This avoids problems associated with having identically named files in several targets and imposes a logical hierarchy on the otherwise flat file structure of PowerBuilder projects. Connecting PowerBuilder Workspaces to Source Control To connect a PowerBuilder Workspace to source control: 1 Right-click on the Workspace object in the System Tree pane. A pop-up menu appears. Serena ChangeMan Dimensions

Setting Up Source Control Projects in PowerBuilder 151 2 Select Properties. The Properties of Workspace dialog box opens to the Source Control tab. 3 Select Serena Dimensions from the Source Control System drop-down list. 4 Enter the path to the root directory for this PowerBuilder workspace in the Local Root Directory field or click the Browse button to select it. IMPORTANT! All objects that are part of the PowerBuilder workspace must be located in the local root directory or in a subdirectory beneath it. Development Interface Implementation Guide

152 Chapter 8 PowerBuilder 5 Click the Browse button to the right of the Project field. 6 If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. NOTE If the Login dialog box is displaced by an error message before you are able to log in, repeat Step 5 to bring up a fresh Login dialog box. 7 The Select workset directory for project dialog box appears. By default, your default workset and its top design part are selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. 8 A Dimensions SCC dialog box appears stating that the operation completed. Click OK. 9 A second Dimensions SCC dialog box states that the project is being opened in the workset. Click OK. 10 Click the Connect button. The Login dialog box appears again. 11 Login to Dimensions. A green plus sign ( ) appears to the left of each object icon to indicate that the workspace is connected to source control but that the objects are not yet under source control. 12 Optionally, complete the other fields on the Properties of Workspace dialog box to configure how PowerBuilder interacts with source control. For more information on how to use these settings, see the PowerBuilder documentation. 13 Click OK. Serena ChangeMan Dimensions

Setting Up Source Control Projects in PowerBuilder 153 Adding Objects to Source Control To add objects to source control: 1 Right-click on the Workspace object in the System Tree pane. A pop-up menu appears. 2 Select Add to Source Control. The Add to Source Control dialog box appears. 3 Do any of the following: Change which objects to add to source control by unchecking or checking the checkboxes next to each object name. Enter a comment in the Comment field. 4 Click OK. A green dot ( ) appears to the left of each object icon to indicate the that object is under source control and is not checked out. Development Interface Implementation Guide

154 Chapter 8 PowerBuilder Configuring Workstations in a Multi-User Environment After connecting a PowerBuilder workspace to source control and adding the objects within it to source control, you can make it available to multiple users. To do so, you must complete the following steps: 1 Copy the directory structure of the PowerBuilder workspace to the workstation. Include only the workspace and target directories, the PowerBuilder Library (.PBL) files, and the PowerBuilder Target (.PBT) files. Special Considerations Do not include the workspace (.PBW) file. The.PBW file contains absolute paths. The directory structure of the PowerBuilder workspace must be the same on each system. 2 Create a new PowerBuilder workspace in the workspace directory you copied to the workstation. 3 Add the copied target (.PBT) files to the new workspace. 4 Connect the new workspace to the existing source control project. See the next section for more information on this step. Connecting Workstations to the Existing Source Control Project To connect a workstation to source control: 1 Right-click on the Workspace object in the System Tree pane. A pop-up menu appears. 2 Select Properties. The Properties of Workspace dialog box opens to the Source Control tab. Serena ChangeMan Dimensions

Setting Up Source Control Projects in PowerBuilder 155 3 Select Serena Dimensions from the Source Control System drop-down list. 4 Click the Browse button to the right of the Project field. 5 If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. NOTE If the Login dialog box is displaced by an error message before you are able to log in, repeat Step 4 to bring up a fresh Login dialog box. 6 The Select workset directory for project dialog box appears. Click the Select Project button. 7 The Select SCC Project dialog box appears. 8 Select the correct product and workset from the Product and Workset drop-down lists, as needed. Development Interface Implementation Guide

156 Chapter 8 PowerBuilder 9 Select the correct project from the Project drop-down list. 10 Click OK. The Properties of Workspace dialog box reappears. 11 Enter the path to the root directory for this workspace in the Local Root Directory field or click the browse button to select it. 12 Click the Connect button. The Login dialog box appears again. 13 Log in to Dimensions. Symbols appear to the left of each object icon to indicate that the objects are under source control: A green dot ( ) indicates that the object is checked in. A red check mark ( ) indicates that the object is checked out by another user. 14 Optionally, configure how PowerBuilder interacts with source control. For more information on how to use these settings, see the PowerBuilder documentation. 15 Click OK. Removing Objects from Source Control When you remove an object from source control, you will no longer be able to access the previous revisions of the object. Only the latest revision will remain. To remove objects from source control: 1 In the Library Painter, select the object or objects you wish to remove from source control. 2 Select Entry Source Control Remove from Source Control. The Remove from Source Control dialog box appears with a list of objects to remove from source control. Serena ChangeMan Dimensions

Using Source Control with PowerBuilder 157 3 Make sure the correct objects are selected and click OK. The selected objects are removed from source control. Disconnecting Workspaces from Source Control Disconnecting a PowerBuilder workspace from source control does not affect the Dimensions repository. You can always reconnect the workspace to source control later. To disconnect a workspace from source control: 1 Right-click the workspace object in the System Tree. A popup menu appears. 2 Select Properties. The Properties of Workspace dialog box appears. 3 Select None from the Source Control System field. 4 Click OK. The workspace is disconnected from source control. Using Source Control with PowerBuilder Contents For more information This section contains procedural information about viewing and editing files that are under source control. See Chapter 4, Using Dimensions with IDE Projects, on page 61. Getting Objects When you get an object, a read-only copy of the latest revision is placed in the target PBL. Development Interface Implementation Guide

158 Chapter 8 PowerBuilder To get a revision: 1 Right-click the object and select Get Latest Version from the resulting pop-up menu. The Get Latest Version dialog box appears with a list of objects. 2 Select or deselect objects from the list as needed. 3 To override the default get options, click the Advanced button. See Overriding Get Options on page 63. 4 Click OK. Checking Out Objects When you check out an object, the revision is locked and a writable object is created in the target PBL and assigned the next revision number. Serena ChangeMan Dimensions

Using Source Control with PowerBuilder 159 To check out an object: 1 Right-click the object and select Check Out from the resulting pop-up menu. The Check Out dialog box appears with a list of objects. 2 Select or deselect objects from the list as needed. 3 To override the default check out options, click the Advanced button. See Overriding Check Out Options on page 64. 4 Click OK. A green check mark ( ) appears to the left of each object icon to indicate that the objects are checked out by you. NOTE A red check mark ( ) indicates that the object is checked out by another user. Undoing Check Out When you undo a check out, the revision number that was created during check out is released and the object is unlocked without updating the Dimensions repository with changes. Development Interface Implementation Guide

160 Chapter 8 PowerBuilder To undo a check out: 1 Right-click the object and select Undo Check Out from the resulting pop-up menu. The Undo Check Out dialog box appears with a list of objects. 2 Select or deselect objects from the list as needed. 3 To override the default undo check out options, click the Advanced button. See Overriding Undo Check Out Options on page 65. 4 Click OK. A green dot ( ) appears to the left of each object icon to indicate that the objects are no longer checked out. Checking In Objects When you check in an object, the object is unlocked and the new revision created during check out is saved in the Dimensions repository. Serena ChangeMan Dimensions

Using Source Control with PowerBuilder 161 To check in an object: 1 Right-click the object and select Check In from the resulting pop-up menu. The Check In dialog box appears with a list of objects. 2 Select or deselect objects from the list as needed. 3 To override the default check in options, click the Advanced button. See Overriding Check In Options on page 66. 4 In the Comment field, enter comments describing the changes you made to the object or objects. 5 Click OK. A green dot ( ) appears to the left of each object icon to indicate that the objects are checked in. Accessing Specific Revisions To get or check out a specific revision of an object, rather than the latest revision, you can invoke the History tab and then select the revision you want. Development Interface Implementation Guide

162 Chapter 8 PowerBuilder NOTE Previous revisions are not accessible from the History tab unless it was invoked with the CTRL + SHIFT keys. To specify a revision during a get or check out operation: 1 Press CTRL + SHIFT while doing one of the following: Check out: Clicking the OK button on the Check Out dialog box Get: Clicking the OK button on the Get Latest Version dialog box 2 The History tab appears listing the revisions of the object. Select the revision you want from the list. 3 Click the Select button. The get or check out operation now proceeds as usual but with the selected revision of the objects instead of the latest revision. Adding New Objects When you create new objects in a source controlled workspace, a green plus sign ( ) appears to the left of each object icon to indicate that the objects are not yet under source control. To add new objects to source control, follow the procedure Adding Objects to Source Control on page 153. Once the objects are added to source control, other users can access them by getting or checking out the target that contains them. Serena ChangeMan Dimensions

PowerBuilder Specific Usability Notes 163 Adding New Targets or PBLs If you add a new target (.PBT) or library (.PBL) to a source controlled workspace, you must: 1 Add it to source control. See Adding Objects to Source Control on page 153. 2 Distribute it to each workstation, as was done when the workspace was first set up for use by multiple users. See Configuring Workstations in a Multi-User Environment on page 154. PowerBuilder Specific Usability Notes This section describes several unexpected or undesired behaviors exhibited by the SCC integration to PowerBuilder and how to avoid or manage them. Behavior Solution Doing a Merge - Diff on the Working Copy of an Object The Merge - Diff tool works with the ASCII representation of the PowerBuilder objects not the objects themselves. To perform a difference operation with the working copy of an object, it must be exported from the PowerBuilder Library and the exported file added to the selection list for Merge - Diff operations. Development Interface Implementation Guide

164 Chapter 8 PowerBuilder Behavior Unable to Read Registry Value: Software\Serena\Dimensions \9.1\PcmsScc\SccServerName Users on Windows may receive the following error message while connecting to Dimensions SCC: "Unable to Read Registry Value: Software\Serena\Dimensions\9.1\PcmsScc \SccServerName" This happens even though the registry value is present in HKEY_LOCAL_MACHINE and can be read through the registry editor. Solution This is a generic problem for all PowerBuilder SCC interfaces. Do one of the following: Make any user that receives this error a member of the Administrators Group using the Windows User Manager. Update the security permissions on the registry key using REGEDT32. See the following procedure. To update security permissions on the registry key: 1 As the administrator, launch REGEDT32. 2 Select the HKEY_LOCAL_MACHINE window and navigate to HKEY_LOCAL_MACHINE\Software\Serena\Dimensions \9.1\PcmsScc. 3 Select Security Permissions. The Registry Key Permissions dialog box appears. 4 Select Special Access... from the Type of Access drop-down list. The Special Access dialog box appears. 5 Select the following check boxes: Create Link Serena ChangeMan Dimensions

PowerBuilder Specific Usability Notes 165 Write DAC Write Owner Read Control 6 Click OK. 7 Click OK. Behavior Solution Selecting a Different Application May Not Change the Active SCC Project When you use the Library Painter to select a different application as the active application, PowerBuilder may stay connected to the previous Dimensions project instead of connecting to the source control project associated with the newly selected application. Close and then reopen the Library Painter to break the connection to the previously selected project and establish one with the current project. Development Interface Implementation Guide

166 Chapter 8 PowerBuilder Serena ChangeMan Dimensions

167 9 Rational Rose In this Chapter For this section... See page... Introduction 168 Accessing Supported Features 168 Setting Up Source Control Projects 169 Using Source Control 174 Development Interface Implementation Guide

168 Chapter 9 Rational Rose Introduction Purpose This chapter has four purposes: List the Dimensions features available through Rational Rose Enterprise 2003, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within Rational Rose See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Accessing Supported Features What is supported? Rational Rose supports most of the source control features available through the Dimensions Development Interface. Specific limitations include: The Project Merge Tool cannot be invoked for this IDE. Operations on specific revisions are not completed if the History tab is invoked from the menu rather than with the CTRL + SHIFT keys. Serena ChangeMan Dimensions

Setting Up Source Control Projects 169 Rational Rose supports only a remote connection to the Dimensions database. (You can still connect to a local Dimensions database through the Remote Login dialog box.) To... Select... For more information see... Get files Tools Version Control Get Latest Getting Files on page 175 Check out files Tools Version Control Check Out Checking Out Files on page 176 Undo check out of files Tools Version Control Undo Check Out Undoing Check Out on page 177 Check in files Tools Version Control Check In Checking In Files on page 178 View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships Add files to source control Remove files from source control Launch Dimensions desktop client 1 Tools Version Control File History 2 Click the History button. Tools Version Control Add to Version Control Tools Version Control Remove From Version Control Tools Version Control Start Version Control Explorer Viewing Source Control Information on page 72 Accessing Specific Revisions on page 180 Adding Files to Source Control on page 171 Removing Files from Source Control on page 173 The Serena ChangeMan Dimensions User s Guide Setting Up Source Control Projects Contents For more information This section contains information about setting up the Dimensions Development Interface to work with Rational Rose. See Chapter 2, Integrating SCC Projects with Dimensions, on page 31. Development Interface Implementation Guide

170 Chapter 9 Rational Rose Before Adding Files to Source Control The Rational Rose Version Control Add-In must be installed before you can add files to source control. Is the Version Control Add-In Installed? To see if the version control add-in is installed: 1 Select Add-Ins Add-In Manager. The Add-In Manager dialog box appears. 2 If the Version Control Add-In: Appears in the Name field with a check mark next to it, it is installed and active. You do not need to do anything. Appears in the Name field but there is not a check mark next to it, it is installed but inactive. Select Version Control and click OK. Serena ChangeMan Dimensions

Setting Up Source Control Projects 171 Does not appear in the Name field, it is not installed. You must exit Rational Rose and install the Version Control Add-In from the Rational CD ROM using setup.exe. Adding Files to Source Control Before you can perform source control operations on your Rational Rose files, you must add them to source control. To add files/units to source control: 1 Check out the model that the files or units are a part of, unless it is the model file (.mdl) that you are adding. 2 Select Tools Version Control Add to Version Control. The Add to or Associate with Dimensions SCC dialog box appears. Development Interface Implementation Guide

172 Chapter 9 Rational Rose 3 If the model (.mdl) file appears in the dialog box, it is not yet under source control; you must connect it to source control before adding any sub-units to source control. a Click the Browse button. b If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. c The Select workset directory for project dialog box appears. You must specify a value in the Project path field. This value will be used to create a file named value.rr in the workset directory. Do not include drive letters or subdirectories. IMPORTANT! The *.mdl and *.rr files are placed at the root of the Dimensions workset as are any subunits that are saved to the directory containing the model file. To avoid filename conflicts, use a separate workset for each Rational Rose model and save subunits in subdirectories below the directory containing the model file. d By default, your default workset and its top design part are selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. e A Dimensions SCC dialog box appears stating that the operation completed. Click OK. Serena ChangeMan Dimensions

Setting Up Source Control Projects 173 f A second Dimensions SCC dialog box states that the project is being opened in the workset. Click OK. 4 Check the boxes next to the units/files you wish to add. Files located outside of the root project working directory (the directory containing the.mdl file) or its subdirectories will not be added to source control. 5 Enter a description in the Comment field. The description will be applied to all selected files. 6 Click OK. 7 If you selected elements of the model in Step 4 that have yet to be partitioned into controlled units, the Save As dialog box appears. Name each element and save it in the directory that contains the model (.mdl) file or in a subdirectory below that directory. You can now perform source control operations on your files. Removing Files from Source Control When you remove a file from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain. To remove files/units from source control: 1 Select the files/units you want to remove. Development Interface Implementation Guide

174 Chapter 9 Rational Rose 2 Select Tools Version Control Remove From Version Control. The Remove from Dimensions SCC dialog box appears with a list of files. You can change which files to remove by selecting or deselecting the files in this list. 3 Click OK. Using Source Control Contents For more information This section contains procedural information about viewing and editing files that are under source control. See Chapter 4, Using Dimensions with IDE Projects, on page 61. Serena ChangeMan Dimensions

Using Source Control 175 Getting Files When you get a file, a read-only copy of the latest revision is placed in the workfile location. To get files/units from source control: 1 Select Tools Version Control Get Latest. The Get Latest from Dimensions SCC dialog box appears. 2 Select the files/units you want to get from the Unit Name list. 3 To override the default get options, click the Advanced button. See Overriding Get Options on page 63. 4 Click the Get button. 5 Click OK. The selected revisions are copied and read-only workfiles are placed in the workfile location. Development Interface Implementation Guide

176 Chapter 9 Rational Rose Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. To check out files/units: 1 Select Tools Version Control Check Out. The Check-out from Dimensions SCC dialog box appears with a list of available files/units. You can change your selection by selecting and deselecting the files/units in this list. 2 To override the default check out options, click the Advanced button. See Overriding Check Out Options on page 64. 3 Click OK. Red check marks ( ) appear on the file icons to indicate that the files are checked out. Serena ChangeMan Dimensions

Using Source Control 177 Undoing Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 Select Tools Version Control Undo Check Out. The Undo Check Out dialog box appears with a list of available files/ units. You can change your selection by selecting and deselecting the files/units in this list. 2 To override the default undo check out options, click the Advanced button. See Overriding Undo Check Out Options on page 65. Development Interface Implementation Guide

178 Chapter 9 Rational Rose 3 Click OK. The red check marks ( ) are removed from the file icons to indicate that the files are no longer checked out. NOTE If you undo a check out of the model (.mdl) file, the workfile is not refreshed from source control. Get the model file to refresh it. Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. Serena ChangeMan Dimensions

Using Source Control 179 To check in files/units: 1 Select Tools Version Control Check In. The Check-in to Dimensions SCC dialog box appears with a list of available files. You can change your selection by selecting and deselecting the files in this list. 2 Enter a description of the changes you made in the Comment field. The description will be applied to all selected files/units. 3 To override the default check in options, click the Advanced button. See Overriding Check In Options on page 66. 4 Click OK. The red check marks ( ) are removed from the file icons to indicate that the files are no longer checked out. Development Interface Implementation Guide

180 Chapter 9 Rational Rose Accessing Specific Revisions To specify a specific revision of a file, rather than the latest revision, press CTRL + SHIFT while clicking the OK button in the get, check out, undo check out, or check in dialog box. You can then select the revision you want from the History tab of the resulting dialog box. For more information, see Specifying Revisions during Source Control Operations on page 77. IMPORTANT! If you invoke the History tab from the menu (Tools Version Control File History) and use it to apply revision specific actions, you must reload any files you acted upon. Otherwise the files displayed by Rational Rose will not reflect your source control actions. Right-click the file and select Units Reload from the pop-menu. Click the Save button on the resulting dialog box. Serena ChangeMan Dimensions

181 10 TestDirector In this Chapter For this section... See page... Introduction 182 About the Dimensions Integrations to 182 TestDirector Accessing Supported Features 184 Setting Up Source Control Projects 187 Using Source Control 195 Setting Up Issue Management 202 Using Issue Management 231 Development Interface Implementation Guide

182 Chapter 10 TestDirector Introduction Purpose This chapter has the following purposes: List the Dimensions features available through Mercury Interactive TestDirector 7.6 and 8.0, and provide a quick reference to accessing those features NOTE The source control integration is supported on TestDirector 7.6 and 8.0. The issue management integration is supported on TestDirector 8.0. Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control Help you access files that are under source control from within this IDE For more information Help you synchronize issue management between Dimensions change documents and TestDirector defects See Part 1: The Dimensions Development Interface, on page 21 for information about source control concepts and defaults. About the Dimensions Integrations to TestDirector Taken together, the source control and issue management integrations to TestDirector enable you to implement an integrated change management solution for your testing and development processes. Serena ChangeMan Dimensions

About the Dimensions Integrations to TestDirector 183 The source control integration enables you to: Apply change control to test scripts Approve test scripts to indicate readiness for use Associate test scripts with requirements, design, and code Create baselines, including test scripts, to represent project milestones The issue management integration enables you to: Create defects in TestDirector that spawn change documents in Dimensions. Create change documents in Dimensions that spawn defects in TestDirector. Synchronize the data in TestDirector defects with that in Dimensions change documents, and vice versa. Synchronize the status of TestDirector defects with the lifecycle state of Dimensions change documents, and vice versa. See the next section. About TestDirector Defect Status and Dimensions Lifecycle States You can map the status states of TestDirector defects to the lifecycle states of Dimensions change documents in order to enable a synchronized progression through both. At each step, either TestDirector or Dimensions controls (owns) the progression to the next state. Development Interface Implementation Guide

184 Chapter 10 TestDirector The following is an example of a defect passing through such a progression. User Action Interface Action TD Status Dm Status Tester submits defect Defect is replicated to a New Raised change document Developer investigates then actions change document to Change Required Developer completes the code changes then actions the change document to Retest Tester verifies the fix then actions defect to Passed Defect is actioned to Open Open Change Required Defect is actioned to Fixed Fixed Retest Change document is actioned to Closed Passed Closed Defect is actioned to Closed Closed Closed Accessing Supported Features What is supported? TestDirector supports a subset of the source control features available through the Dimensions Development Interface in addition to issue management. There is no support for differencing or merging. Source Control Features The following source control features can be accessed from the main menu in TestDirector: To... Select... For more information see... Get latest revision Versions Get Latest Version Getting the Latest Revision on page 195 Serena ChangeMan Dimensions

Accessing Supported Features 185 To... Select... For more information see... Get previous revision Check out latest revision Check out previous revision Undo check out of revision Versions Versions Get version Versions Check Out Versions Versions Check out Versions Undo Check Out Getting a Previous Revision on page 195 Checking Out the Latest Revision on page 197 Checking Out a Previous Revision on page 197 Undoing Check Out on page 199 Check in revision Versions Check In Checking In Files on page 199 View version history Versions Versions Viewing Version History on page 201 Add projects to source control Remove projects from source control Refresh source control status (See the text.) (See the text.) Versions Refresh Adding Projects to Source Control on page 192 Removing Projects from Source Control on page 194 n/a Issue Management Features The following issue management features can be accessed from the main window of the issue management integration: To... Select... For more information see... Configure a connection to a Dimensions database Configure a connection to a TestDirector project Action Configure Dimensions Connection(s) Action Configure TestDirector Connection(s) Configuring a Connection to a Dimensions Database on page 205 Configuring a Connection to a TestDirector Project on page 207 Development Interface Implementation Guide

186 Chapter 10 TestDirector To... Select... For more information see... Map a TestDirector project to a Dimensions product Edit existing attribute mappings and synchronization settings Edit existing attribute mappings and synchronization settings Edit TestDirector restrictions Edit Dimensions restrictions Submit a defect from TestDirector Submit a change document from Dimensions Resolve synchronization conflicts Launch the integration Send the integration window to the Windows Taskbar Restore the integration window Action New Link Action Edit Links Edit Attributes Mapping button Action Edit Links Edit Status Mapping button Action Edit Links Edit TD Restriction button Action Edit Links Edit DM Restriction button (See the text.) (See the text.) Action Edit Links View Conflict button (From the Windows Start menu) Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer Mapping a TestDirector Project to a Dimensions Product on page 209 Editing Existing Attribute Mappings on page 219 Editing Existing Status Mappings on page 223 Editing Existing TestDirector Restrictions on page 226 Editing Existing Dimensions Restrictions on page 226 Replicating Defects to Dimensions on page 232 Replicating Change Documents to TestDirector on page 233 Resolving Conflicts on page 234 n/a Click the minimize button ( ) n/a Double-click the Dimensions icon ( ) in the Windows Taskbar n/a Serena ChangeMan Dimensions

Setting Up Source Control Projects 187 Setting Up Source Control Projects Contents For more information This section contains information about setting up the Dimensions Development Interface to work with TestDirector. See the TestDirector documentation and Chapter 3, Integrating COM Projects with Dimensions, on page 47. NOTE For information about setting up the issue management integration, see Setting Up Issue Management on page 202. Installing and Configuring the Software Configuring TestDirector Servers You must perform the following steps to configure a TestDirector server for use with Dimensions. 1 Install the following to a system: a TestDirector Enterprise 7.6 and Service Pack 4 or TestDirector Enterprise 8.0 and Service Pack 2 NOTE Run the TestDirector Checker utility and resolve any problems with the server. b Dimensions server and client, including: The Dimensions Development Interface The Dimensions TDVCPlugin Development Interface Implementation Guide

188 Chapter 10 TestDirector IMPORTANT! By default, both Dimensions and TestDirector try to use port 8080. You can specify a different port when installing Dimensions. See the Dimensions Installation Guide for Windows Servers. NOTE You can locate the Dimensions database on a separate system by setting the LOCAL system environment variable to the database alias for the remote server. 2 Update the dm.cfg file: a From the Windows Start menu, select Serena ChangeMan Dimensions 9.1 Administration Tools Configuration Parameters. The dm.cfg file opens in your default text file editor. b Add the following line to the file: DIMENSIONS_COM_BASEDB BaseDatabase@DSN Where BaseDatabase equals the name of the Dimensions base database you are using with COM IDEs and DSN equals the Data Source Name. IMPORTANT! If at some point you designate a new base database, you must restart your COM server application. Example To work with the intermediate database and a Data Source Name of DIM8, you would add the following line: DIMENSIONS_COM_BASEDB intermediate@dim8 NOTE The Data Source Name is the same as the DB Connection field on the Dimensions Login dialog box. For more information, see the Serena ChangeMan Dimensions Getting Started Guide. Serena ChangeMan Dimensions

Setting Up Source Control Projects 189 c You must define a default workset. One way to do so is to add the following line to the dm.cfg file: DIMENSIONS_COM_WORKSET Product:Workset Where Product equals the name of the Dimensions product you are using with TestDirector and Workset equals the name of the Dimensions workset you are using with TestDirector. IMPORTANT! You must ensure that the default workset is the same for all users who work on the same projects; it cannot be the global workset. For more information, see Defining the Default Workset on page 54. d Save the dm.cfg file. 3 Set the COM identity for TestDIrector: a Select Run from the Windows Start menu. The Run dialog box appears. b Enter dcomcnfg in the Open field and click OK. The Distributed COM Configuration Properties dialog box appears with the Applications tab active. c Select Mercury Domain Server from the Applications list and click the Properties button. The Properties dialog box appears. d Select the Identity tab. e f Select the The launching user option. Click OK. The Distributed COM Configuration Properties dialog box reappears. g Select Mercury OTAServer Server from the Applications list and click the Properties button. The Properties dialog box appears. h Select the Identity tab. Development Interface Implementation Guide

190 Chapter 10 TestDirector i j k Select the The launching user option. Click OK. Click OK. 4 Set the TestDirector service to manual startup: a From the Windows Start menu, select Settings Control Panel Administrative Tools Services. The Services dialog box appears. b Right-click on the Advanced Test DIrector Start and Stop Service and select Properties from the resulting pop-up menu. The Properties dialog box appears with the General tab active. c Select Manual from the Startup type drop-down list. d Click the Stop button. e Click OK. 5 Disable anonymous access: a From the Windows Start menu, select Programs Administrative Tools Internet Services Manager. b In the Tree pane, right-click on TDBIN under Default Web Site and select Properties from the resulting pop-up menu. The Properties dialog box appears. c Select the Directory Security tab. d Click the Edit button in the Anonymous access and authentication control group. The Authentication Methods dialog box appears. e f Deselect the Anonymous access check box. Click OK. g Click OK. Serena ChangeMan Dimensions

Setting Up Source Control Projects 191 Configuring TestDirector Clients See the TestDirector documentation. No Dimensions components need to be installed on TestDirector clients. General users TestDirector Site Administrator Setting Up User Accounts For each Windows/TestDirector login account that is to have access to the COM integration, you must create an identically named Dimensions user. See Setting Up User Accounts on page 54. You must also define a Dimensions user ID for the integration to use on behalf of the TestDirector Site Administrator. This user ID must exist in Dimensions and have all roles necessary to create, extract, and return items in the default workset. NOTE Once defined, the integration will pass this user ID to Dimensions when ever the TestDirector Site Administrator accesses Dimensions. You do not need to create this user ID within TestDirector itself. To define an administrator ID: 1 Open a command prompt and change to the prog directory of your Dimensions installation. For a default installation, the path would be: C:\Serena\ChangeMan\Dimensions\9.1\prog 2 Enter the following command and press ENTER: tdadmin.exe AdminID Where AdminID is the Dimensions user ID you want the integration to pass to Dimensions on behalf of the TestDirector Site Administrator. Development Interface Implementation Guide

192 Chapter 10 TestDirector Enabling Source Control Before you can place projects under source control, you must enable the TestDirector Version Control Add-in. To enable source control: 1 Launch the TestDirector Site Administrator (Start TestDirector Site Administrator). 2 Log in as a site administrator. 3 Select the Site Config tab. 4 Select the VC parameter. 5 Click the Edit button. The Edit Parameter dialog box appears. 6 Enter Y in the Value field and click OK. Adding Projects to Source Control Once source control is enabled, there are two ways to place TestDirector projects under source control: Add an existing TestDirector project to source control. Create a new TestDirector project and add it to source control. Adding an Existing Project to Source Control To add an existing project to source control: 1 Launch the TestDirector Site Administrator (Start TestDirector Site Administrator). 2 Log in as a site administrator. 3 From the Projects tab, select a project in the left pane. Serena ChangeMan Dimensions

Setting Up Source Control Projects 193 4 If the project is active, click the Deactivate button and then click Yes to confirm the action. 5 Click the Enable VC button (padlock icon). One of the following occurs: TestDIrector 7.6: A confirmation dialog box appears. Click the Yes button. TestDirector 8.0: The Enable Version Control for Project dialog box appears: a b c Select the Yes option to add your existing tests to source control. Select the No option to create an empty version control database for the project. Click the Next button. The second page of the dialog box appears. Click the Finish button. NOTE This step may take a moment or two. 6 Click the Activate button. Adding a New Project to Source Control To create and add a new project to source control: 1 Launch the TestDirector Site Administrator (Start TestDirector Site Administrator). 2 Log in as a site administrator. 3 From the Projects tab, click the Create Project button. The Create Project wizard appears. 4 Specify a project name, domain, and database type then click the Next button. The second page of the Create Project wizard appears. Development Interface Implementation Guide

194 Chapter 10 TestDirector 5 Select the Create A Version Control DataBase check box and click the Create button. 6 A message appears stating that version control has been enabled. Click OK to dismiss it. 7 A second message appears stating that the project has been created. Click OK to dismiss it. Removing Projects from Source Control When you remove a TestDirector project from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain. To remove a project from source control: 1 Launch the TestDirector Site Administrator (Start TestDirector Site Administrator). 2 Log in as a site administrator. 3 From the Projects tab, select a project in the left pane. 4 If the project is active, click the Deactivate button and then click Yes to confirm the action. 5 Click the Disable VC button. 6 Click OK at the Warning dialog box. 7 Click Yes at the Confirmation dialog box. 8 A success message appears. Click OK to dismiss it. Serena ChangeMan Dimensions

Using Source Control 195 Using Source Control Contents This section contains procedural information about viewing and editing files that are under source control. Getting Tests When you get a test, a read-only copy of the test is placed in the workfile location. You can get the latest revision or a previous revision. Getting the Latest Revision To get a test: 1 From the TEST PLAN tab of the TestDirector client, right-click a plan. A pop-up menu appears. 2 Select Versions Get Latest Version. Getting a Previous Revision To get a test: 1 From the TEST PLAN tab of the TestDirector client, right-click a plan. A pop-up menu appears. Development Interface Implementation Guide

196 Chapter 10 TestDirector 2 Select Versions Versions. The Version History dialog box appears. 3 Select the version you wish to get. 4 Click the Get version button. A file cabinet appears next to the test s icon to indicate that this is not the latest revision. NOTE If you get a previous revision of a test, you must get the latest revision before you are allowed to check out the test. Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision Serena ChangeMan Dimensions

Using Source Control 197 number. You can check out the latest revision or a previous revision. Checking Out the Latest Revision To check out a test: 1 From the TEST PLAN tab of the TestDirector client, right-click a plan. A pop-up menu appears. 2 Select Versions Check Out. The Check Out dialog box appears. 3 Click the OK button. A padlock appears next to the test s icon. Checking Out a Previous Revision To check out a test: 1 From the TEST PLAN tab of the TestDirector client, right-click a plan. A pop-up menu appears. Development Interface Implementation Guide

198 Chapter 10 TestDirector 2 Select Versions Versions. The Version History dialog box appears. 3 Select the version you wish to check out. 4 Click the Check out button. A confirmation dialog box appears. 5 Click the OK button. The Check Out dialog box appears. 6 Click the OK button. A padlock appears next to the test s icon. Serena ChangeMan Dimensions

Using Source Control 199 Undoing Check Out When you undo a check out, the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 From the TEST PLAN tab of the TestDirector client, right-click a plan. A pop-up menu appears. 2 Select Versions Undo Check Out. A confirmation dialog box appears. 3 Click OK. Checking In Files When you check in a file, the revision is checked into the Dimensions repository. To check in a test: 1 From the TEST PLAN tab of the TestDirector client, right-click a plan. A pop-up menu appears. 2 Select Versions Check In. The Check In dialog box appears. Development Interface Implementation Guide

200 Chapter 10 TestDirector 3 Do any of the following: To override the value shown in the Version field, click the browse button. Another Check In dialog box appears. a b Change the values as need. Click the OK button. NOTE In TestDirector, this value is referred to as the Vc Version. Dimensions uses this value to apply an attribute named VCS Tags to the revision. The Dimensions revision numbering scheme is unaffected by this field. Enter a description of the changes you made in the Comments field. To retain the lock on the test after it is checked in, select the Keep checked out check box. 4 Click the OK button. Adding New Tests If a TestDirector project is under source control, any new test you create within the project is automatically added to source control. Serena ChangeMan Dimensions

Using Source Control 201 Viewing Version History The TestDirector Version History dialog box displays the following information: Version: A number TestDirector uses to uniquely identify each version of a test. Dimensions uses this value to assign an attribute named VCS Tags to each revision, but this value is not related to the Dimensions revision number. User: The ID of the user who created the version. Date: The date the version was created. Time: The time the version was created. Comment: The description that was associated with the version when it was created. To view history information: 1 From the TEST PLAN tab of the TestDirector client, right-click a plan. A pop-up menu appears. 2 Select Versions Versions. The Version History dialog box appears. NOTE If check in is to be used from the "Versions" dialog, a refresh operation must be performed in the TD project to ensure changes are saved. TestDirector does not automatically save when the "Versions" dialog appears, causing potential loss of information. Development Interface Implementation Guide

202 Chapter 10 TestDirector Setting Up Issue Management Contents Purpose This section contains information about setting up Dimensions issue management to work with TestDirector. This integration enables you to: Create defects in TestDirector that spawn change documents in Dimensions. Create change documents in Dimensions that spawn defects in TestDirector. Synchronize data in TestDirector defects with that in Dimensions change documents, and vice versa. Synchronize the status of TestDirector defects with the lifecycle state of Dimensions change documents, and vice versa. Installing the Software Install the following to your client systems: 1 The client applet for TestDirector Enterprise 8.0. The applet must be present before you install the Serena ChangeMan Dimensions - TestDirector Synchronizer. To install the applet, access the TestDirector server via a web browser. 2 Dimensions client, including the Serena ChangeMan Dimensions - TestDirector Synchronizer. Enabling History for Fields and Attributes You must ensure that the history option is enabled for any fields that you plan to map between TestDirector and Dimensions. Serena ChangeMan Dimensions

Setting Up Issue Management 203 Enabling History for Dimensions Attributes To enable history for Dimensions attributes: 1 Launch and log in to the Dimensions Administration Console (Start Programs Serena ChangeMan Dimensions 9.1 Administration Tools Administration Console). The Administration Console appears. 2 Click the Change Documents link under the Configuration Object Management group. The Object Types window appears. 3 In the left pane, click on the type of Dimensions change document you plan to map to TestDirector defects. 4 In the right pane, click the Attributes tab. 5 Click the name of the attribute you want to modify. The Edit Attribute dialog box appears. 6 Select the Keep History check box. 7 Click OK. 8 Repeat steps 5 through 7 for each Dimensions attribute you plan to map to a TestDirector field. Enabling History for TestDirector Fields To enable history for TestDirector Fields: 1 Launch the TestDirector General Access page. 2 Click the CUSTOMIZE button. The Login dialog box appears. 3 Select a domain and project from the lists. 4 Enter your login information and click OK. The Project Customization page appears. Development Interface Implementation Guide

204 Chapter 10 TestDirector 5 Click Customize Project Entities. The Customize Project Entities dialog box appears. 6 In the Project Entities pane, expand Defect so you can see System Fields and User Fields. Expand both of these so you can see the individual fields they contain. 7 Click the name of the field you want to modify. 8 In the Field Settings pane, select the History check box. 9 Repeat steps 7 and 8 for each TestDirector field you plan to map to a Dimensions attribute. 10 Click OK. Overview of Setting Up the Issue Management Integration 1 Configure a connection to a Dimensions database. See Configuring a Connection to a Dimensions Database on page 205. 2 Configure a connection to a TestDirector project. See Configuring a Connection to a TestDirector Project on page 207. 3 Map a TestDirector project to a Dimensions product. See Mapping a TestDirector Project to a Dimensions Product on page 209. 4 You can edit the link configuration and mapping of attribute data between a TestDirector project and a Dimensions product. See Editing Existing Attribute Mappings on page 219. 5 You can edit the mapping of status/lifecycle states between TestDirector and Dimensions. See Editing Existing Status Mappings on page 223. Serena ChangeMan Dimensions

Setting Up Issue Management 205 Configuring a Connection to a Dimensions Database To create a connection to a Dimensions database: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 3 Select Action Configure Dimensions Connection(s). The New Dimensions Connection dialog box appears. 4 Enter a Dimensions user ID in the User ID field. Development Interface Implementation Guide

206 Chapter 10 TestDirector Special Considerations The user ID must have the roles necessary to create and modify change documents of the type you will later define for use with TestDirector projects. The user ID should be reserved for use with the integration and should not be used for manual changes. Manual changes made with this user ID will not be picked up by the integration. 5 Enter the password for the Dimensions user ID in the User Password field. 6 Enter a Dimensions database login ID in the Enter Database Login ID field. 7 Enter a password for the Dimensions database in the Enter Database Password field, if needed. 8 Enter the remote connection string for the Dimensions database in the Database Setup - Remote Connection String field. 9 Enter the name of the host computer for the Dimensions database in the Server Host Name field. 10 Click the Test Product Connection button. 11 One of the following occurs: An error message appears. Review the steps above and reenter any invalid entries. A success message appears. Click OK to dismiss it. 12 Click the Save Connection button. 13 A save complete message appears. Click OK to dismiss it. 14 Click the Exit button to close the New Dimensions Connection dialog box. Serena ChangeMan Dimensions

Setting Up Issue Management 207 NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Configuring a Connection to a TestDirector Project To create a connection to a TestDirector project: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 3 Select Action Configure TestDirector Connections. The New TestDirector Connection dialog box appears. Development Interface Implementation Guide

208 Chapter 10 TestDirector 4 Enter the URL of the TestDirector host in the Host URL field. IMPORTANT! The URL should specify a directory. Do not include a file name. 5 Click the Connect button. The Domain and Project lists are populated. 6 Select a TestDirector domain from the Domain list. 7 Select a TestDirector project from the Project list. 8 Enter a TestDirector user ID in the User ID field. Special Considerations The user ID must have Administrator rights in TestDirector. The user ID should be reserved for use with the integration and should not be used for manual changes. Manual changes made with this user ID will not be picked up by the integration. 9 Enter the password for the user ID in the User Password field. 10 Click the Test Project Connection button. 11 One of the following occurs: An error message appears. Review the steps above and reenter any invalid entries. A success message appears. Click OK to dismiss it. 12 Click the Save Connection button. 13 A save complete message appears. Click OK to dismiss it. 14 Click the Exit button to close the New TestDirector Connection dialog box. Serena ChangeMan Dimensions

Setting Up Issue Management 209 NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Mapping a TestDirector Project to a Dimensions Product To link a TestDirector project to Dimensions: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). Development Interface Implementation Guide

210 Chapter 10 TestDirector 3 Select Action New Link. The Link Setup Wizard appears. 4 Select a TestDirector project from the TestDirector Project list. Serena ChangeMan Dimensions

Setting Up Issue Management 211 NOTE To add a TestDirector project to this list, see Configuring a Connection to a TestDirector Project on page 207. 5 Select a Dimensions product from the Dimensions Product list. NOTE To add a Dimensions product to this list, see Configuring a Connection to a Dimensions Database on page 205. 6 In the Change Document Type list, select the Dimensions change document type to map to TestDirector defects. 7 Select a design part from the Design Part tree, and check the check box below if you want include all design parts within the subtree below the selected design part. Leave the check box unchecked if you only want to synchronize change documents from the selected design part. If you choose to use the whole tree below the selected design part, no other link can use either the selected design part or any of the design parts in the subtree below without any further restriction. 8 To restrict which TestDirector defects spawn Dimensions change documents, specify a specific value for a specific field. If you specify a value, only those defects that match it will spawn change documents. IMPORTANT! If you create links between a TestDirector project and multiple Dimensions products, you must specify the same Field Name but a different Field Value for each link. This ensures that only one change document is spawned from each defect. Development Interface Implementation Guide

212 Chapter 10 TestDirector a Click the Edit button under TestDirector Field. The TestDirector Field Restriction dialog box appears. b Select a field from the Field Name list. c Select a value from the Field Value list. d Click OK. 9 To restrict which Dimensions change documents spawn TestDirector defects, specify a specific value for a specific attribute. If you specify a value, only those change documents that match it will spawn defects. IMPORTANT! If you create links between a Dimensions product and multiple TestDirector projects, you must specify the same Attribute Name but a different Attribute Value for each link. This ensures that only one defect is spawned from each change document. a Click the Edit button under Dimensions Attribute. The Dimensions Attribute Restriction dialog box appears. b Select an attribute from the Attribute Name list. c Select a value from the Attribute Value list. d Click OK. Serena ChangeMan Dimensions

Setting Up Issue Management 213 10 Click the Next button. Page Two of the Link Setup Wizard appears. Development Interface Implementation Guide

214 Chapter 10 TestDirector 11 To map defect/change document statuses between TestDirector and Dimensions: NOTE For more information, see About TestDirector Defect Status and Dimensions Lifecycle States on page 183. a Select a Dimensions lifecycle state from the Dimensions Status list. b Select the corresponding TestDirector defect status from the TestDirector Status list. c To determine which application controls the next change in status, select one of the following from the Owner list: TestDirector Dimensions Both: Either application can change the status. NOTE If you intend to submit defects/change documents from both TestDirector and Dimensions, you must set the owner of the initial status state to Both. d Click the Map button. The new mapping appears in the Existing Status Mapping list. 12 To remove an existing status mapping, select the mapping in the Existing Status Mapping list and click the Remove button. 13 To remove all mappings displayed in the Existing Status Mapping list, click the Remove All button. Serena ChangeMan Dimensions

Setting Up Issue Management 215 14 Click the Next button. Page Three of the Link Setup Wizard appears. Development Interface Implementation Guide

216 Chapter 10 TestDirector IMPORTANT! You must enable the history option for any fields you map between TestDirector and Dimensions. For more information, see Enabling History for Fields and Attributes on page 202. 15 To map TestDirector fields to Dimensions fields: Special Considerations You must map all Dimensions fields that represent mandatory attributes of the Dimensions change document type. IMPORTANT! Dimensions attributes that will be mapped must not require Electronic Signature Support, (i.e. they must not be defined as sensitive). a If both the TestDirector field and the Dimensions attribute have a list of valid values but the lists are different, the Dimensions list will replace the TestDirector list. To refresh the TestDirector Field list and the Dimensions Field list with the latest TestDirector and Dimensions fields, click the Refresh button. b Select a TestDirector field from the TestDirector Field list. c Select a Dimensions field from the Dimensions Field list. IMPORTANT! The Dimensions field you choose must be of a type compatible with the selected TestDirector field or Dimensions change documents will not be created. d Click the Map button. The new field mapping appears in the Existing Mapped Fields list. e Repeat the above listed steps for each TestDirector field you wish to map. Serena ChangeMan Dimensions

Setting Up Issue Management 217 16 To verify that all Dimensions fields that represent mandatory attributes in the Dimensions change document type are mapped, click the Verify button. IMPORTANT! It is possible to exit this screen without all mandatory attributes mapped. This allows for saving partial configurations while setting up the integration. All mandatory attributes must be mapped and verified before the link can be successfully synchronized. 17 To remove a field mapping, select a mapped link in the Existing Mapped Fields list and click the Remove button. 18 To remove all field mappings, click the Remove All button. 19 To receive e-mail notification of synchronization conflicts, complete the following fields: a SMTP Server: Enter the name, or IP address, of the e-mail server the integration will send e-mail through. b Account Name: Enter the e-mail account name the integration will use. c Password: Enter the e-mail password the integration will use. d Email Address: Enter the e-mail address to which the integration will send conflict notifications. 20 To automatically synchronize the TestDirector and Dimensions data, complete the following fields: a Auto-Sync Setting: Enter the desired synchronization interval in minutes. Development Interface Implementation Guide

218 Chapter 10 TestDirector b Merge To Field Level: Determines when fields are synchronized automatically versus when you are notified of a field level conflict. To raise a synchronization conflict: Only when the same field changes in both TestDirector and Dimensions, select the Yes option. When ever mapped fields change in both TestDirector and Dimensions, whether the fields are mapped to each other or not, select the No option. The following table illustrates various scenarios where TD Field-1 is mapped to Dm Field-1 and TD Field-2 is mapped to Dm Field-2. Option TD Field-1 TD Field-2 Dm Field-1 Dm Field-2 Result Yes Changed Changed Conflict. An e-mail notification is sent. Yes Changed Changed No conflict. No e-mail is sent. Dm Field-1 is updated with the new content of TD Field-1. TD Field-2 is updated with the new content of Dm Field-2 Yes Changed No conflict. No e-mail is sent. Dm Field-1 is updated with the new content of TD Field-1. No Changed Changed Conflict. An e-mail notification is sent. No Changed Changed Conflict. An e-mail notification is sent. No Changed No conflict. No e-mail is sent. Dm Field-1 is updated with the new content of TD Field-1. Serena ChangeMan Dimensions

Setting Up Issue Management 219 21 Click the Finish button. NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Editing Existing Attribute Mappings IMPORTANT! You must enable the history option for any fields you map between TestDirector and Dimensions. For more information, see Enabling History for Fields and Attributes on page 202. To edit the attribute mapping of existing links: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 3 Select Action Edit Links. The Links dialog box appears. Development Interface Implementation Guide

220 Chapter 10 TestDirector 4 Select a link and click the Edit Attributes Mapping button. The Attributes Mapping dialog box appears. 5 To map TestDirector fields to Dimensions fields: Special Considerations You must map all Dimensions fields that represent mandatory attributes of the Dimensions change document type. Serena ChangeMan Dimensions

Setting Up Issue Management 221 a If both the TestDirector field and the Dimensions attribute have a list of valid values but the lists are different, the Dimensions list will replace the TestDirector list. To refresh the TestDirector Field list and the Dimensions Field list with the latest TestDirector and Dimensions fields, click the Refresh button. b Select a TestDirector field from the TestDirector Field list. c Select a Dimensions field from the Dimensions Field list. IMPORTANT! The Dimensions field you choose must be of a type compatible with the selected TestDirector field or Dimensions change documents will not be created. d Click the Map button. The new field mapping appears in the Existing Mapped Fields list. e Repeat the above listed steps for each TestDirector field you wish to map. 6 To verify that all Dimensions fields that represent mandatory attributes in the Dimensions change document type are mapped, click the Verify button. 7 To remove a field mapping, select a mapped link in the Existing Mapped Fields list and click the Remove button. 8 To remove all field mappings, click the Remove All button. 9 To receive e-mail notification of synchronization conflicts, complete the following fields: a SMTP Server: Enter the name, or IP address, of the e-mail server the integration will send e-mail through. b Account Name: Enter the e-mail account name the integration will use. Development Interface Implementation Guide

222 Chapter 10 TestDirector c Password: Enter the e-mail password the integration will use. d Email Address: Enter the e-mail address to which the integration will send conflict notifications. 10 To automatically synchronize the TestDirector and Dimensions data, complete the following fields: a Auto-Sync Setting: Enter the desired synchronization interval in minutes. b Merge To Field Level: Determines when fields are synchronized automatically versus when you are notified of a field level conflict. To raise a synchronization conflict: Only when the same field changes in both TestDirector and Dimensions, select the Yes option. When ever mapped fields change in both TestDirector and Dimensions, whether the fields are mapped to each other or not, select the No option. The following table illustrates various scenarios where TD Field-1 is mapped to Dm Field-1 and TD Field-2 is mapped to Dm Field-2. Option TD Field-1 TD Field-2 Dm Field-1 Dm Field-2 Result Yes Changed Changed Conflict. An e-mail notification is sent. Yes Changed Changed No conflict. No e-mail is sent. Dm Field-1 is updated with the new content of TD Field-1. TD Field-2 is updated with the new content of Dm Field-2 Serena ChangeMan Dimensions

Setting Up Issue Management 223 Option TD Field-1 TD Field-2 Dm Field-1 Dm Field-2 Result Yes Changed No conflict. No e-mail is sent. Dm Field-1 is updated with the new content of TD Field-1. No Changed Changed Conflict. An e-mail notification is sent. No Changed Changed Conflict. An e-mail notification is sent. No Changed No conflict. No e-mail is sent. Dm Field-1 is updated with the new content of TD Field-1. 11 Click the OK button. NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Editing Existing Status Mappings To edit the status mapping of existing links: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 3 Select Action Edit Links. The Links dialog box appears. Development Interface Implementation Guide

224 Chapter 10 TestDirector 4 Select a link and click the Edit Status Mapping button. Page 2 of the New Link Wizard Attributes Mapping dialog box appears. Serena ChangeMan Dimensions

Setting Up Issue Management 225 5 To map defect/change document statuses between TestDirector and Dimensions: NOTE For more information, see About TestDirector Defect Status and Dimensions Lifecycle States on page 183. a Select a Dimensions lifecycle state from the Dimensions Status list. b Select the corresponding TestDirector defect status from the TestDirector Status list. c To determine which application controls the next change in status, select one of the following from the Owner list: TestDirector Dimensions Both: Either application can change the status. NOTE If you intend to submit defects/change documents from both TestDirector and Dimensions, you must set the owner of the initial status state to Both. d Click the Map button. The new mapping appears in the Existing Status Mapping list. 6 To remove an existing status mapping, select the mapping in the Existing Status Mapping list and click the Remove button. 7 To remove all mappings displayed in the Existing Status Mapping list, click the Remove All button. 8 Click the OK button. NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Development Interface Implementation Guide

226 Chapter 10 TestDirector Editing Existing TestDirector Restrictions You can restrict which TestDirector defects spawn Dimensions change documents by specifying a specific value for a specific field. If you specify a value, only those defects that match it will spawn change documents. IMPORTANT! If you create links between a TestDirector project and multiple Dimensions products, you must specify the same Field Name but a different Field Value for each link. This ensures that only one change document is spawned from each defect. To edit TestDirector restrictions: 1 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 2 Select Action Edit Links. The Links dialog box appears. 3 Select a link to edit. 4 Click the Edit TD Restriction button. The TestDirector Field Restriction dialog box appears. 5 Select a field from the Field Name list. 6 Select a value from the Field Value list. 7 Click OK. Editing Existing Dimensions Restrictions You can restrict which Dimensions change documents spawn TestDirector defects by specifying a specific value for a specific attribute. If you specify a value, only those change documents that match it will spawn defects. Serena ChangeMan Dimensions

Setting Up Issue Management 227 IMPORTANT! If you create links between a Dimensions product and multiple TestDirector projects, you must specify the same Attribute Name but a different Attribute Value for each link. This ensures that only one defect is spawned from each change document. To edit Dimensions restrictions: 1 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 2 Select Action Edit Links. The Links dialog box appears. 3 Select a link to edit. 4 Click the Edit DM Restriction button. The Dimensions Attribute Restriction dialog box appears. 5 Select an attribute from the Attribute Name list. 6 Select a value from the Attribute Value list. 7 Click OK. Deleting Connections You can delete TestDirector and Dimensions connections from the main window of the integration. Deleting TestDirector Connections To delete TestDirector connections: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector Development Interface Implementation Guide

228 Chapter 10 TestDirector TestDirectorSynchronizer). All defined connections appear in the TestDirector Connections list. 3 Do one of the following: To delete a connection: a) Select a connection in the TestDirector Connections list. b) Click the Delete Current TD Project button. To delete all TestDirector connections, click the Delete All TD Projects button. NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Deleting Dimensions Connections To delete Dimensions connections: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). All defined connections appear in the Mapped Dimensions Connections list. 3 Do one of the following: To delete a connection: a) Select a connection in the Mapped Dimensions Connections list. b) Click the Delete Current Product button. To delete all Dimensions connections, click the Delete All Dimensions Products button. Serena ChangeMan Dimensions

Setting Up Issue Management 229 NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Deleting Links You can delete existing links between TestDirector projects and Dimensions products from the Links dialog box. To delete links: 1 Stop the TDDmSyncService service, if it is running. (Use the Windows Services utility.) 2 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 3 Select Action Edit Links. The Links dialog box appears. 4 Do one of the following: To remove a specific link, select the link and click the Remove button. To remove all links, click the Remove All button. 5 Click OK to close the dialog box. NOTE Restart the TDDmSyncService service, if you are done editing the configuration. (Use the Windows Services utility.) Troubleshooting Links If a link does not work correctly, review this section for help in determining what has gone wrong. Development Interface Implementation Guide

230 Chapter 10 TestDirector Automatically Created Attributes and Fields The following Dimensions attributes and TestDirector fields should be created automatically when you create a link between Dimensions and TestDirector. If a link does not work correctly, verify that these attributes and fields were properly created. Dimensions attributes (maxlength): PROJECT_ID (500) DEFECT_ID (10) SYNC_USER (256) SYNC_TIME (50) REPLICATE_DEFECT (1) NOTE In order to replicate a change document to a TestDirector defect, you must set this attribute to Y when creating the change document. See Replicating Change Documents to TestDirector on page 233. We recommend that you create a rule making this a mandatory attribute on change document creation. It should have a valid list consisting of Y and N. See the Serena ChangeMan Dimensions Process Modeling User s Guide. DEFECT_STATUS (50) TestDirector fields: Replicate To Dim NOTE In order to replicate a defect to a Dimensions change document, you must set this attribute to Y when creating the defect. See Replicating Defects to Dimensions on page 232. DimensionsID Serena ChangeMan Dimensions

Using Issue Management 231 Sync Time Dim Design Part ChangeDoc Status Dim Link Name Synchronization Log Files Location Name The synchronization service creates a log file for each link it synchronizes. These log files may help you determine the cause of any synchronization failures. The log files are located in the Integrations\TestDirector- Synchronizer subdirectory of your Dimensions installation. The log file for each link is named as follows: TD-URL_TD-Domain_TD-Project_TD-RestrictionFieldName_ TD-RestrictionFieldValue.log Using Issue Management Contents This section contains information about using Dimensions issue management with TestDirector. Development Interface Implementation Guide

232 Chapter 10 TestDirector Replicating Defects to Dimensions To submit a defect: 1 From the Defects tab of TestDirector, click the Add Defect button. The Add Defect dialog box appears. 2 Do one of the following: To create a change document in Dimensions based on this defect, select Y from the Replicate To Dim field. To exclude this defect from the integration with Dimensions, select N from the Replicate To Dim field. 3 Complete the rest of the dialog as you would normally. NOTE If a defect has attachments at the time it is replicated to Dimensions, the attachments will be replicated also. However, any future changes to the attachments will not be replicated. Serena ChangeMan Dimensions

Using Issue Management 233 Replicating Change Documents to TestDirector To submit a change document: 1 From the New Change Document dialog box of the Dimensions desktop client, select the Attributes tab. 2 Do one of the following: To create a defect in TestDirector based on this change document, change the value of the Replicate Defect attribute to Y. To exclude this change document from the integration with TestDirector, ensure that the value of the Replicate Defect attribute is N. Development Interface Implementation Guide

234 Chapter 10 TestDirector NOTE We recommend that you create a rule making REPLICATE_DEFECT a mandatory attribute on change document creation. It should have a valid list consisting of Y and N. See the Serena ChangeMan Dimensions Process Modeling User s Guide. 3 Complete the rest of the dialog as you would normally. NOTE Attachments to Dimensions change documents are not replicated to TestDirector. Resolving Conflicts To resolve conflicts between TestDirector and Dimensions data: 1 Launch the issue management integration (Start Programs Serena ChangeMan Dimensions Integrations TestDirector TestDirectorSynchronizer). 2 Select Action Edit Links. The Links dialog box appears. Serena ChangeMan Dimensions

Using Issue Management 235 3 Select a link and click the View Conflict button. The Link Conflicts dialog box appears. The Link Conflicts List contains the following information: TD Bug ID: The TestDirector defect ID number of the defect that contains data in conflict with Dimensions. TD Field Name: The name of the TestDirector field that contains data in conflict with Dimensions. TD Field Value: The TestDirector data that is in conflict with Dimensions. Change ID: The Dimensions ID of the change document that contains data in conflict with TestDirector. Attribute Name: The name of the Dimensions attribute that contains data in conflict with TestDirector. Attribute Value: The Dimensions data that is in conflict with TestDirector. Development Interface Implementation Guide

236 Chapter 10 TestDirector 4 Select a conflict in the Link Conflicts List and do one of the following: To remove the conflict from the list without affecting the data in TestDirector or Dimensions, click the Remove Conflict button. To synchronize the data in TestDirector and Dimensions: a b Select which data source to use from the Synchronize by group, TestDirector or Dimensions. Click the Resolve Conflict button. 5 Click the Exit button to close the dialog box. Viewing Change Document and Defect Status Each TestDirector defect contains a field that displays the status of its associated Dimensions change document. Each Dimensions change document contains an attribute that displays the status of its associated TestDirector defect. The information displayed in these fields is accurate as of the time of the last synchronization. Serena ChangeMan Dimensions

237 11 Visual Basic In this Chapter For this section... See page... Introduction 238 Accessing Supported Features 238 About Visual Basic Files 239 Setting Up Source Control Projects 240 Using Source Control 248 Visual Basic Specific Usability Notes 257 Development Interface Implementation Guide

238 Chapter 11 Visual Basic Introduction Purpose This chapter has four purposes: List the Dimensions features available through Microsoft Visual Basic 6.0, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within Visual Basic See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Accessing Supported Features What is supported? Visual Basic supports the full set of source control features available through the Dimensions Development Interface. See the following table. To... Select... For more information see... Get files Tools Serena ChangeMan Accessing Supported Dimensions Get Latest Version Features on page 238 Check out files Tools Dimensions Check Out Checking Out Files on page 250 Serena ChangeMan Dimensions

About Visual Basic Files 239 To... Select... For more information see... Undo check out of files Check in files View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships View project-level differences Add projects to source control Add files to an existing source control project Remove files from source control Set SCC options for Visual Basic Launch Dimensions desktop client Tools Serena ChangeMan Dimensions Undo Check Out Tools Serena ChangeMan Dimensions Check In Tools Serena ChangeMan Dimensions Show History Tools Serena ChangeMan Dimensions Show Differences (See text.) Tools Serena ChangeMan Dimensions Add Files to Dimensions (See text.) Tools Serena ChangeMan Dimensions Options Tools Serena ChangeMan Dimensions Run Dimensions Undoing Check Out on page 251 Checking In Files on page 253 Viewing Source Control Information on page 72 Viewing File or Project Differences on page 84 Adding Visual Basic Projects to Source Control on page 244 Adding New Files to Source Control on page 256 Removing Files from Source Control on page 247 Configuring Source Control Behavior on page 243 The Serena ChangeMan Dimensions User s Guide About Visual Basic Files Binary and text files Visual Basic pairs certain text files with binary files, but the Visual Basic interface does not display the binary files. Though the binary files remain unseen while you work in the Visual Basic interface, they are kept in sync with the source control actions you apply to the visible files. Development Interface Implementation Guide

240 Chapter 11 Visual Basic For example, if you check out a text file named my_project.frm, the binary file my_project.frx is also checked out. Files out of sync To keep files in sync Paired files However, it is possible to get the text and binary files out of sync if you check out only one or the other using the desktop client or the History tab. If you check out Visual Basic files via the desktop client or the History tab, be sure to check out both the text and the binary file of any file pairs. See Accessing Specific Revisions on page 255. Visual Basic pairs the following files: These text files... *.ctl *.dob *.dsr *.frm *.pag Are paired with these binary files... *.ctx *.dox *.dsx *.frx *.pgx Setting Up Source Control Projects Contents For more information This section contains information about setting up the Dimensions Development Interface to work with Visual Basic. See Chapter 2, Integrating SCC Projects with Dimensions, on page 31. Enabling SCC Integration Visual Basic requires a Visual Basic IDE Add-in to enable SCC functionality. If your installation of Visual Basic does not include the add-in, you must manually enable SCC. Serena ChangeMan Dimensions

Setting Up Source Control Projects 241 Is the Visual Basic SCC IDE Add-In Installed? To see if the Visual Basic SCC IDE Add-In is installed: 1 Launch Visual Basic. 2 Select Add-Ins Add-In Manager. The Add-In Manager dialog box appears. 3 Under Available Add-Ins, look for the string Source Code Control. If the string is listed, the SCC add-in is installed and you do not need to manually enable SCC. If the string is not listed, you must manually enable SCC. Proceed to the next section. Manually Enabling SCC To manually enable SCC: 1 Login to Windows as a user with administrative rights. 2 Open an MSDOS prompt and navigate to the directory that contains the Visual Basic install. 3 Enter the command regsvr32 /c vbscc.dll and press ENTER. NOTE If regsvr32.exe is not in your path, locate it using the Windows Find utility (Start Find Files or Folders) and invoke it explicitly. 4 Search the directory in which Windows is installed for a file named vbaddin.ini. Development Interface Implementation Guide

242 Chapter 11 Visual Basic 5 Open the file in a text editor. If the file does not exist, create it. 6 Add both of the following lines if they do not already exist: [Add-Ins32] vbscc=3 7 Save the file. Supporting Files Outside the Project Directory When you get an entire project from source control (Tools Serena ChangeMan Dimensions Create Project from Serena ChangeMan Dimensions) Visual Basic does not refer to the project (.vbp) file to determine which files to get. Instead, Visual Basic gets all the files in the project directory. This presents two potential problems: Non-project files that are located in the project directory will be included in the get operation. Project files that are located outside of the project directory will not be included in the get operation. To avoid these behaviors: 1 From the Windows Start menu, select Serena ChangeMan Dimensions 9.1 Administration Tools Configuration Parameters. The dm.cfg file opens in your default text file editor. 2 Add the following line to the file: PCMS_SCC_ADD_ENV Y 3 Save the dm.cfg file. Serena ChangeMan Dimensions

Setting Up Source Control Projects 243 This creates an Environment-Item relationship between the files in the Visual Basic project and the Dimensions project marker file. This change takes effect the next time you start Visual Basic. NOTE Binary files will not be included when you get the project unless you first use the desktop client to create an Environment- Item relationship from the project marker file to the binary files. For information on Visual Basic file pairs, see About Visual Basic Files on page 239. Configuring Source Control Behavior You can configure Visual Basic so that actions you take in Visual Basic: Automatically invoke source control operations Do not invoke source control operations Prompt for permission to invoke source control operations To configure the source control behavior of Visual Basic: 1 Select Tools Serena Dimensions Options. The Source Code Control dialog box appears. Development Interface Implementation Guide

244 Chapter 11 Visual Basic 2 Set the value of any of the drop-down lists to one of the following: Ask: To be prompted to invoke source control when you perform the listed Visual Basic operation. This is the default. Yes: To automatically invoke source control when you perform the listed Visual Basic operation. No: To not invoke or be prompted to invoke source control when you perform the listed Visual Basic operation. 3 Click OK. Adding Visual Basic Projects to Source Control To add a project to source control: 1 Do one of the following: When saving a new Visual Basic project, click Yes when prompted to add it to source control. To add an already saved project to source control, select Tools Serena ChangeMan Dimensions Add Project to Serena ChangeMan Dimensions. 2 If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. 3 The Select workset directory for project dialog box appears. By default, your default workset and its top design part are selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. Serena ChangeMan Dimensions

Setting Up Source Control Projects 245 4 A Dimensions SCC dialog box appears stating that the operation completed. Click OK. 5 A second Dimensions SCC dialog box states that the project is being opened in the workset. Click OK. 6 The Add Files to Serena ChangeMan Dimensions dialog box appears. Do any of the following: Filter the list of files to be added by selecting a filter from the File Type drop-down menu. Select or deselect files in the Files to be added field. Enter a description of the files in the Comment field. 7 Click the OK button. Development Interface Implementation Guide

246 Chapter 11 Visual Basic 8 A Source Code Control Results dialog box appears. Click the Close button to dismiss it or leave it open for future source control operations. A padlock ( ) appears next to each file icon in the Project pane to indicate that the files are under source control. Connecting Additional Workstations to a Source Control Project After a project has been created and added to source control, each developer can access it by opening it from source control, which creates a copy of the project on the developer s system. Once a developer has a local copy of a project, he can perform normal source control operations on it. NOTE If any of the Visual Basic files are outside of the project directory, see Supporting Files Outside the Project Directory on page 242. To connect a workstation: 1 Select Tools Serena ChangeMan Dimensions Create Project from Serena ChangeMan Dimensions. The Select SCC Project dialog box appears. (For a screen shot, see page 42.) 2 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Select an existing workset from the Workset drop-down list. By default, your default workset is used. 3 Select the project you want to get from the Project dropdown list. Serena ChangeMan Dimensions

Setting Up Source Control Projects 247 4 Click OK. The Browse for Folder dialog box appears. 5 Navigate to the parent directory to copy the project subdirectory and files to and click OK. An operation completed message appears. Removing Files from Source Control When you remove a file from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain. IMPORTANT! You can configure Visual Basic to automatically remove files or to prompt you to remove files from source control when you remove them from the Visual Basic project. One of these options must be enabled for you to remove a file from source control through Visual Basic. See Configuring Source Control Behavior on page 243. Development Interface Implementation Guide

248 Chapter 11 Visual Basic To remove a file from source control: 1 Select the file in the Project pane. 2 Do one of the following: Select Project Remove. Right-click the file and select Remove from the resulting pop-up menu. 3 If you have configured Visual Basic to prompt you before removing a file from source control, a prompt will appear. Click Yes. 4 An operation completed message appears. Using Source Control Contents For more information This section contains procedural information about viewing and editing files that are under source control. See Chapter 4, Using Dimensions with IDE Projects, on page 61. Getting Files When you get a file, a read-only copy of the latest revision is placed in the workfile location. Serena ChangeMan Dimensions

Using Source Control 249 To get files: 1 Select Tools Serena ChangeMan Dimensions Get Latest Revision. The Get Files from Serena ChangeMan Dimensions dialog box appears. 2 Do any of the following: Filter the list of files by selecting a filter from the File Type drop-down menu. Select or deselect files in the Files to Get field. To override the default get options, click the Advanced button. See Overriding Get Options on page 63. 3 Click OK. An operation completed message appears. T I P To quickly get a single file, right-click on the file and select Get Latest Version from the resulting pop-up menu. Development Interface Implementation Guide

250 Chapter 11 Visual Basic Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. To check out files: 1 Select Tools Serena ChangeMan Dimensions Check Out. The Check Out Files from Serena ChangeMan Dimensions dialog box appears. 2 Do any of the following: Filter the list of files by selecting a filter from the File Type drop-down menu. Select or deselect files in the Files to be Checked Out field. Serena ChangeMan Dimensions

Using Source Control 251 IMPORTANT! Select the project (.vbp) file if it is not already checked out. To override the default check out options, click the Advanced button. See Overriding Check Out Options on page 64. 3 Click OK. An operation completed message appears and the padlock icons are replaced with red check marks ( ). T I P To quickly check out a single file, right-click on the file and select Check Out from the resulting pop-up menu. Undoing Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. Development Interface Implementation Guide

252 Chapter 11 Visual Basic To undo a check out: 1 Select Tools Serena ChangeMan Dimensions Undo Check Out. The Undo Checkout of Files from Serena ChangeMan Dimensions dialog box appears. 2 Do any of the following: Filter the list of files by selecting a filter from the File Type drop-down list. Select or deselect files in the Files to undo checked out of field. To override the default undo check out options, click the Advanced button. See Overriding Undo Check Out Options on page 65. 3 Click OK. An operation completed message appears and the red check marks ( ) are removed from the file icons in the Project pane. Serena ChangeMan Dimensions

Using Source Control 253 T I P To quickly undo the check out of a single file, right-click on the file and select Undo Check Out from the resulting pop-up menu. Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. To check in files: 1 Save any changes to the Visual Basic files you wish to check in. Development Interface Implementation Guide

254 Chapter 11 Visual Basic 2 Select Tools Serena ChangeMan Dimensions Check In. The Check In Files to Serena ChangeMan Dimensions dialog box appears. 3 Do any of the following: Filter the list of files by selecting a filter from the File Type drop-down list. Select or deselect files in the Files to be Checked In field. Select the Keep checked out check box to keep the files checked out. Enter a description of the files in the Comment field. Click the Differences button to invoke the Merge Tool. For information on differencing, see Viewing File or Project Differences on page 84. Serena ChangeMan Dimensions

Using Source Control 255 To override the default check in options, click the Advanced button. See Overriding Check In Options on page 66. 4 Click OK. An operation completed message appears and the red check marks ( ) are removed from the file icons in the Project pane. T I P To quickly check in a single file, right-click on the file and select Check In from the resulting pop-up menu. Accessing Specific Revisions To get or check out a specific revision of a file, rather than the latest revision, you can invoke the History tab and then select the revision you want. IMPORTANT! Do not get or check out a revision from the History tab if you invoked the History tab from the menu (Tools Serena Dimensions Show History). Visual Basic uses text and binary file pairs but displays only the text file. When invoked from the menu, the History tab does not include the binary file in the source control operation. See About Visual Basic Files on page 239. To specify a revision during a get or check out operation: 1 Press CTRL + SHIFT while doing one of the following: Clicking the OK button on the Check Out Files from Serena Dimensions dialog box. Right-clicking on a file in the Project pane and selecting Get Latest Version or Check Out from the resulting pop-up menu. Development Interface Implementation Guide

256 Chapter 11 Visual Basic 2 The History tab appears listing the revisions of the text file. Select the revision you want from the list. IMPORTANT! The binary and text files may not have the same revision numbers. Note the values of the Date/Time and Comment fields to ensure that you can match the text revision to the correct binary revision. 3 Click the Select button. 4 The History tab re-appears listing the revisions of the binary file. Select the revision you want from the list. 5 Click the Select button. NOTE If the History tab does not re-appear for the binary file, the Visual Basic object does not yet contain a control that necessitates a binary file. The get or check out operation now proceeds as usual but with the selected revision of the files instead of the latest revision. Adding New Files to Source Control As your IDE project develops, you may add new files to it. The following procedure explains how to add new files to the existing Dimensions project. To add new files to an existing Dimensions project: 1 Check out the project (.vbp) file. 2 Do one of the following: When saving a new Visual Basic file, click Yes when prompted to add it to source control. Serena ChangeMan Dimensions

Visual Basic Specific Usability Notes 257 To add an already saved file to source control, select Tools Serena ChangeMan Dimensions Add Files to Serena ChangeMan Dimensions. 3 Follow the procedure for adding projects to source control starting with Step 6 on page 245. Visual Basic Specific Usability Notes The following is a list of unexpected or undesired behaviors exhibited by the SCC integration to Visual Basic and recommendations on how to avoid or manage them. Visual Basic does not check if files are saved to disk before invoking source control operations. Save your files before performing source control operations. If you open (get) a project from SCC into a Visual Basic Project Group, the new project will overwrite the entries for one of the existing projects in the group. Add the missing project back into the group. If you cancel the Dimensions Login dialog, Visual Basic will mark the current IDE project file as 'not under source control'. Reconnect to the existing Dimensions project by selecting Tools Source Control Add to Serena ChangeMan Dimensions and following the procedure Specifying an Existing Project on page 41. When saving a new project do not save to a location where there are already SCC project(s). Create a new subdirectory in the save dialog and place files there. Development Interface Implementation Guide

258 Chapter 11 Visual Basic Serena ChangeMan Dimensions

259 12 Visual C++ In this Chapter For this section... See page... Introduction 260 Accessing Supported Features 260 Setting Up Source Control Projects 261 Using Source Control 269 Development Interface Implementation Guide

260 Chapter 12 Visual C++ Introduction Purpose This chapter has four purposes: List the Dimensions features available through Microsoft Visual C++ 6.0, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within the IDE See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Accessing Supported Features What is supported? Visual C++ supports the full set of source control features available through the Dimensions Development Interface. See the following table. To... Select... For more information see... Get files Project Source Control Get Getting Files on page 270 Latest Version Serena ChangeMan Dimensions

Setting Up Source Control Projects 261 To... Select... For more information see... Get an entire project Check out files Undo check out of files Projects Insert Project into Workspace Project Source Control Check Out Project Source Control Undo Check Out Connecting Additional Workstations to a Source Control Project on page 266 Checking Out Files on page 270 Undoing Check Out on page 271 Check in files Project Source Control Check In Checking In Files on page 272 View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships View project-level differences Add files to source control Remove files from source control Set SCC options for Visual C++ Launch Dimensions desktop client Project Source Control Show History Project Source Control Show Differences Project Source Control Add to Source Control Project Source Control Remove from Source Control Tools Options Project Source Control Dimensions SCC Viewing Source Control Information on page 72 Viewing File or Project Differences on page 84 Adding Visual C++ Files to Source Control on page 264 Removing Files from Source Control on page 268 Configuring Source Control Behavior on page 262 The Serena ChangeMan Dimensions User s Guide Setting Up Source Control Projects Contents For more information This section contains information about setting up the Dimensions Development Interface to work with Visual C++. See Chapter 2, Integrating SCC Projects with Dimensions, on page 31. Development Interface Implementation Guide

262 Chapter 12 Visual C++ Configuring Source Control Behavior You can configure Visual C++ so that actions you take in Visual C++: Automatically invoke source control operations Do not invoke source control operations Prompt for permission to invoke source control operations To configure the source control behavior of Visual C++: 1 Select Tools Options. The Options dialog box appears. 2 Select the Source Control tab. 3 Select or deselect the check boxes of the features you wish to activate or deactivate. For detailed information on each feature, see the Visual C++ documentation. 4 Click OK. Serena ChangeMan Dimensions

Setting Up Source Control Projects 263 Using a UNIX Based Dimensions Server with Visual C++ Microsoft Visual C++ can create file names with both upper and lower case characters even though Windows is case insensitive, e.g. Foo.c is the same as foo.c. However, UNIX is case sensitive and would see Foo.c and foo.c as unique file names. This in itself poses no problem. However, Visual C++ handles case inconsistently when it passes information for SCC operations: When the initial project is placed under source control, the project directory name passed by Visual C++ to Dimensions is always lowercase. The Dimensions project directory is then created as lowercase on UNIX. When the files within a project are placed under source control, the actual case is passed to Dimensions. Thus if the Visual C++ project includes uppercase characters, the UNIX directory for the project will not match the path for the files within the project. Dimensions attempts to recognize this situation and defaults to lowercase when it does. However, complexly organized workspaces may defeat this attempt and lead to the creation of a second Dimensions project directory that differs only by case. The following strategies can help you avoid case based conflicts: Do not create complexly organized Visual C++ workspaces and projects. Use only lowercase when naming Visual C++ projects and workspaces. Use a Windows system for your Dimensions server. Development Interface Implementation Guide

264 Chapter 12 Visual C++ Adding Visual C++ Files to Source Control To add files to source control: 1 Select the workspace, projects, and files you want to add to source control. To select a workspace, you must use the FileView pane. NOTE To add a project or file to an existing workspace or project that is already under source control, you must first check out the workspace or project. 2 Select Project Source Control Add to Source Control. 3 If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. 4 The Select workset directory for project dialog box appears. By default, your default workset and its top design part are selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. NOTE If a dialog box appears warning that the end of the project path does not match the project name, see Adding Projects with Files Outside the Project Directory on page 265. 5 A Dimensions SCC dialog box appears stating that the operation completed. Click OK. 6 A second Dimensions SCC dialog box states that the project is being opened in the workset. Click OK. Serena ChangeMan Dimensions

Setting Up Source Control Projects 265 7 The Add to Source Control dialog box appears. Do any of the following: Select or deselect files in the Files field. Deselect the Keep checked out check box so the files are not automatically checked out after they are added to source control. Enter a description of the files in the Comment field. 8 Click the OK button. The file icons turn gray ( ) to indicate that the files are under source control. NOTE The process repeats, starting with Step 4 on page 264, for each workspace and project you selected. Adding Projects with Files Outside the Project Directory If the IDE project you are adding contains files that are outside of the project directory, Visual C++ passes incorrect path Development Interface Implementation Guide

266 Chapter 12 Visual C++ information to Dimensions. Dimensions detects this and allows you to specify the correct path. To add a project with files outside the project directory: 1 Follow the procedure Adding Visual C++ Files to Source Control on page 264 until the following dialog box appears. 2 Click the Yes button. The Browse for Folder dialog box appears. 3 Select the directory that contains the Visual C++ project and click OK. IMPORTANT! All files must be within the scope of the Dimensions workset. For information on setting the scope of the workset, see About Workset Scope on page 40. 4 Continue where you left off with Adding Visual C++ Files to Source Control on page 264. Connecting Additional Workstations to a Source Control Project After an IDE project has been created and added to source control, each developer can access it by opening it from source control, which creates a copy of the project on the developer s Serena ChangeMan Dimensions

Setting Up Source Control Projects 267 system. Once a developer has a local copy of a project, he can perform normal source control operations on it. To connect a workstation: 1 Create a Visual C++ workspace into which to insert a copy of the project. 2 Select Projects Insert Project into Workspace. The Insert Projects into Workspace dialog box appears. 3 Click the Source Control button. The Select SCC Project dialog box appears. (For a screen shot, see page 42.) 4 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Select an existing workset from the Workset drop-down list. By default, your default workset is used. 5 Select the project you want to get from the Project dropdown list. Development Interface Implementation Guide

268 Chapter 12 Visual C++ 6 Click OK. The Browse for Folder dialog box appears. 7 Navigate to the parent directory to copy the project subdirectory and files to and click OK. 8 The Insert Projects into Workspace dialog reappears. Click OK. Removing Files from Source Control When you remove a file from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain. To remove a file from source control: 1 Select the file. Serena ChangeMan Dimensions

Using Source Control 269 2 Select Project Source Control Remove from Source Control. The Remove from Source Code Control dialog box appears. 3 Click OK to remove the selected files. The file icons change from gray to white to indicate that the files are no longer under source control. Using Source Control Contents For more information This section contains procedural information about viewing and editing files that are under source control. See Chapter 4, Using Dimensions with IDE Projects, on page 61. Development Interface Implementation Guide

270 Chapter 12 Visual C++ Getting Files When you get a file, a read-only copy of the latest revision is placed in the workfile location. To get files: 1 Select the files you want to get. 2 Select Project Source Control Get Latest Version. The Get Latest Version dialog box appears. 3 To override the default get options, click the Advanced button. See Overriding Get Options on page 63. 4 Click OK. Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. To check out files: 1 Select the files you want to check out. Serena ChangeMan Dimensions

Using Source Control 271 IMPORTANT! Check out the workspace and project files if they are under source control and your changes will affect them. 2 Select Project Source Control Check Out. The Check out file(s) dialog box appears. 3 To override the default check out options, click the Advanced button. See Overriding Check Out Options on page 64. 4 Click OK. A red check mark ( ) appears next to each file icon. Undoing Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 Select the files you want to release. Development Interface Implementation Guide

272 Chapter 12 Visual C++ 2 Select Project Source Control Undo Check Out. The Undo Check Out dialog box appears. 3 To override the default undo check out options, click the Advanced button. See Overriding Undo Check Out Options on page 65. 4 Click OK. The red check marks ( ) are removed from the file icons in the FileView pane. Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. To check in files: 1 Select the files you want to check in. Serena ChangeMan Dimensions

Using Source Control 273 2 Select Projects Source Control Check In. The Check in file(s) dialog box appears. 3 Do any of the following: Select or deselect files in the Files field. Select the Keep checked out check box to keep the files checked out. Enter a description of the files in the Comment field. Click the Differences button to invoke the Merge Tool. For information on differencing, see Viewing File or Project Differences on page 84. To override the default check in options, click the Advanced button. See Overriding Check In Options on page 66. NOTE The Differences button is enabled when only one file is highlighted in the Files field. Development Interface Implementation Guide

274 Chapter 12 Visual C++ 4 Click OK. The red check marks ( ) are removed from the file icons in the FileView pane. Accessing Specific Revisions To get, check out, check in, or undo a check out on a specific revision of a file, rather than the latest revision, select the file and then select Project Source Control Show History. You can then select the revision you want from the History tab of the resulting dialog box. You can also invoke the History tab during get and check out operations by pressing CTRL + SHIFT while clicking the OK button in the get or check out dialog box. For more information, see History Tab on page 76. Serena ChangeMan Dimensions

275 13 Visual InterDev In this Chapter For this section... See page... Introduction 276 About Web Projects 276 Accessing Supported Features from Web 277 Projects Setting Up Web Projects 278 Using Source Control with Web Projects 282 About Non-Web Projects 289 Accessing Supported Features from Non-Web 290 Projects Integrating Source Control with Non-Web 291 Projects Using Source Control with Non-Web Projects 295 Development Interface Implementation Guide

276 Chapter 13 Visual InterDev Introduction About Visual InterDev Purpose Visual InterDev connects to and functions with source control features in two different ways depending on which type of project you are working with, web-based or non-web. This chapter is divided into web and non-web sections. This chapter has four purposes: List the Dimensions features available through Microsoft Visual InterDev 6.0, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within this IDE See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features About Web Projects Visual InterDev stores web-based projects on a web server. These web projects access Dimensions features via the Component Object Model (COM) interface which supports a subset of the features available in Dimensions. See the next section for a quick reference of available features. Serena ChangeMan Dimensions

Accessing Supported Features from Web Projects 277 For more information See Chapter 3, Integrating COM Projects with Dimensions, on page 47. Accessing Supported Features from Web Projects What is supported? When working with web projects, Visual InterDev supports a subset of the source control features available through the Dimensions Development Interface. Specific limitations include: Previous revisions cannot be checked out from within Visual InterDev web projects. See Checking Out a Previous Revision on page 289. The Dimensions merge and differencing tools cannot be invoked for web projects. To... Select... For more information see... Get individual files Project Source Control Get Getting Files on page 282 Latest Version Refresh (get) all changed files in project Synchronize (get) copies of local project files that have changed Check out files Undo check out of files Project Web Project Refresh Project View Project Web Project Synchronize Files Project Source Control Check Out Project Source Control Undo Check Out Project-wide Get Options on page 284 Project-wide Get Options on page 284 Checking Out Files on page 285 Undoing a Check Out on page 286 Check in files Project Source Control Check In Checking In Files on page 287 Add web project to source control Project Source Control Add to Source Control Adding Web Projects to Source Control on page 279 Development Interface Implementation Guide

278 Chapter 13 Visual InterDev To... Select... For more information see... Disconnect web project from source control Remove files from source control Delete files from Visual InterDev and source control Access the Dimensions desktop client Project Source Control Disconnect Web Project Project Source Control Remove Edit Delete Project Source Control Serena ChangeMan Dimensions Disconnecting Web Projects from Source Control on page 280 Removing Files from Source Control on page 281 Deleting Files from Visual InterDev and Source Control on page 281 The Serena ChangeMan Dimensions User s Guide Setting Up Web Projects Contents Prerequisites This section contains information about setting up the Dimensions Development Interface to work with web-based Visual InterDev projects. Before proceeding, you must do the following: Install Dimensions, the FrontPage Server Extensions, and the Dimensions Development Interface to your web server. See the Serena ChangeMan Dimensions Installation Guide. Configure web server security. See Configuring Web Server Security on page 50. For more information Configure default settings for new source control projects. See Configuring Source Control Defaults on page 52. See Chapter 3, Integrating COM Projects with Dimensions, on page 47. Serena ChangeMan Dimensions

Setting Up Web Projects 279 About Visual InterDev Web Projects With Visual InterDev, developers may work with web files in one of two ways from their local workstations: Master Mode ( ): When working in Master Mode, developers directly modify files in the web application on the web server (the master application). Local Mode ( ): When working in Local Mode, developers modify local copies of the web application files. Saving changes to the files does not automatically update the master application. Developers can release the local copies to the server to update the master copies with changes. Single developer Multi-developer If your web project is maintained by a single developer, it may be unnecessary to maintain separate local copies of the master web application. In a multi-developer environment, Microsoft recommends that each developer create and maintain individual working copies of the web application. In this scenario, developers work in Local Mode only. The implementation of source control in a multideveloper web project ensures that only one developer can modify a file at a time. Adding Web Projects to Source Control To place a web project under source control: 1 Create or open a web project in Visual InterDev. You must locate the project on the web server. 2 Select the project icon in the Project Explorer ( ). Development Interface Implementation Guide

280 Chapter 13 Visual InterDev 3 Select Project Source Control Add to Source Control. The Enable Source Control dialog box appears. 4 By default, the source control project is named after the web project. You can enter a new name in the Source control project name field. You must precede the name with a dollar sign ($) and a forward slash (/). 5 Click OK. A lock symbol ( ) appears next to the project icon in the Visual InterDev Project Explorer to indicate that the project is under source control. Disconnecting Web Projects from Source Control Disconnecting a project from source control does not delete the source control files; it only removes the association with the Dimensions project. You can always reconnect the project to source control later. To disconnect a web project from source control: 1 Select the web project icon in the Project Explorer ( ). 2 Select Project Source Control Disconnect Web Project. 3 In the prompt that appears, click Yes. Serena ChangeMan Dimensions

Setting Up Web Projects 281 Removing Files from Source Control When you remove a file from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain. To remove files from source control: 1 Select the files you want to remove in the Project Explorer. 2 Select Project Source Control Remove. The Remove items from source control dialog box appears with a list of the files you selected. You can change your selection by selecting and deselecting files in the Items list. 3 Click OK. Deleting Files from Visual InterDev and Source Control Deleting a file removes it from the Visual InterDev project and from the Dimensions repository. This operation is permanent. To delete a file: 1 Select the file you want to delete in the Project Explorer. 2 Select Edit Delete. 3 You are prompted to confirm the delete operation. Click Yes. The Push Remove to Server dialog box appears. 4 Select one of the following options: Remove Now: To delete the file from the Dimensions repository. Remind later: To be prompted again the next time you work with this project. Development Interface Implementation Guide

282 Chapter 13 Visual InterDev Do nothing: The file is not deleted from the Dimensions repository and you are not reminded to do so again. 5 Click OK. Using Source Control with Web Projects Contents For more information This section contains procedural information about viewing and editing web-based files that are under source control. See the Help and documentation that came with your IDE for more information on using source control with your IDE. Getting Files When you get a file, Visual InterDev creates a copy of the master file in your local workfile directory. This updates your local copy with the most recent modifications to the master copy. Other users may still check out and edit the master file. To get the latest versions of individual files: 1 Select the file or files from the Project Explorer. Serena ChangeMan Dimensions

Using Source Control with Web Projects 283 2 Select Project Source Control Get Latest Version. The Get Latest Version dialog box appears with a list of the files you selected. 3 Do any of the following: To change your selection, select or deselect files in the Items list. To get all items in the project subdirectories, select the Directories check box, then select the Get items from subdirectories check box. T I P To bypass the display of the Get Latest Version dialog box in the future, select the Don t show any more get dialogs check box. 4 Click OK. The local copies of the web files are updated with the most recent changes to the files in the master web project. Development Interface Implementation Guide

284 Chapter 13 Visual InterDev Project-wide Get Options You must regularly update a local copy of a project to keep it synchronized with the master project. Visual InterDev allows you to automatically update your entire local project based on changes to the master project. You can either refresh or synchronize your project. Refreshing a Local Project Refresh copies all new and changed files in the master project to your local project, with the exception of any local files that are writable. To update writable files, synchronize your project. To refresh a local project: 1 In the Project Explorer, select the project. 2 Select Project Web Project Refresh Project View. All new files are copied to the local project. All local read-only files are updated to include changes to the master files. Synchronizing a Local Project Synchronize updates all local files with the changes that have been made to the master files. To get files not currently in your local project, refresh your project. To synchronize a local project: 1 In the Project Explorer, select the project you want to synchronize. 2 Select Project Web Project Synchronize Files. All local files are updated with changes to the master files. Serena ChangeMan Dimensions

Using Source Control with Web Projects 285 Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. NOTE To check out a previous revision of a file, you must modify the repository with the Dimensions desktop client. See Checking Out a Previous Revision on page 58. To check out files: 1 Select the files in the Project Explorer. 2 Select Project Source Control Check Out. The Check out item(s) dialog box appears with a list of the files you selected. You can change your selection by selecting and deselecting files in this list. T I P To bypass the display of the Check out item(s) dialog box in the future, select the Don t show any more check out dialogs check box. Development Interface Implementation Guide

286 Chapter 13 Visual InterDev 3 Click OK. A red check mark ( ) appears next to each file icon indicating that the files are checked out. Open the file To open a file you have checked out in an editor, select the file in the Project Explorer, then select View Open. Undoing a Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 Select the file in the Project Explorer. 2 Select Project Source Control Undo Check Out. The Undo Check Out dialog box appears with a list of the files you selected. You can change your selection by selecting and deselecting files in this list. Serena ChangeMan Dimensions

Using Source Control with Web Projects 287 T I P To bypass the display of the Undo Check Out dialog box in the future, select the Don t show this dialog again check box. 3 Click OK. A confirmation dialog box appears. 4 Click YES. The file is unlocked and any changes that were saved since the file was checked out are discarded. Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. To check in files: 1 Select the files in the Project Explorer. Development Interface Implementation Guide

288 Chapter 13 Visual InterDev 2 Select Project Source Control Check In. The Check in item(s) dialog box appears with a list of the files you selected. 3 Do any of the following: To change your selection, select or deselect files in the Items list. To compare the files you are checking in to the latest versions of the files in the master project, click the Differences button. To check in your changes but continue to work on the files, select the Keep checked out check box. T I P To bypass the display of the Check in item(s) dialog box in the future, select the Don t show any more check in dialogs check box. Serena ChangeMan Dimensions

About Non-Web Projects 289 4 In the Comment field, enter a description of the changes you made to the files. You can view change descriptions in the Dimensions desktop client. 5 Click OK. The red check mark ( ) is removed from each file icon indicating that the files are no longer checked out. Checking Out a Previous Revision By design, Visual InterDev allows you to check out only the latest revision of a file. However, you can get a previous revision using the Dimensions desktop client, then update the latest revision with it. The previous revision is then available to check out from within your IDE as the latest revision. See Checking Out a Previous Revision on page 58. Adding New Files If a master web project is under source control and you add a file to it, the file is automatically added to source control. If you add a file to your local project, add it to the master project to place it under source control. To add a file to the master project: 1 In Local Mode, select the file in the Project Explorer. 2 Select Project Web Files Add to Master Web. The file is copied to the master web and placed under source control. About Non-Web Projects Non-web Visual Studio projects, such as database and utility projects, integrate with Dimensions via the Source Code Control (SCC) interface. Through this interface you can access Dimensions Development Interface Implementation Guide

290 Chapter 13 Visual InterDev features that are not available with Visual InterDev web projects. See the next section for a quick reference of available features. Accessing Supported Features from Non-Web Projects What is supported? When working with non-web projects, Visual InterDev supports the full set of source control features available through the Dimensions Development Interface. See the following table. To... Select... For more information see... Get a project Project Source Control Open Project Getting Projects or Solutions on page 295 Get files Project Source Control Get Latest Version Getting Files on page 296 Check out files Undo check out of files Project Source Control Check Out Project Source Control Undo Check Out Checking Out Files on page 297 Undoing Check Out on page 298 Check in files Project Source Control Check In Checking In Files on page 299 View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships View project-level differences Add project to source control Project Source Control History Project Source Control Compare Versions Project Source Control Add Viewing Source Control Information on page 72 Viewing File or Project Differences on page 84 Adding Non-Web Projects to Source Control on page 291 Serena ChangeMan Dimensions

Integrating Source Control with Non-Web Projects 291 To... Select... For more information see... Disconnect project from source control Remove files from source control Delete files from source control Launch Dimensions desktop client Project Source Control Change Connection Project Source Control Remove Edit Delete Project Source Control Serena ChangeMan Dimensions Disconnecting Non-Web Projects from Source Control on page 293 Removing Files from Source Control on page 293 Deleting Files from Visual InterDev and Source Control on page 294 The Serena ChangeMan Dimensions User s Guide Integrating Source Control with Non-Web Projects Contents For more information This section contains information about setting up the Dimensions Development Interface to work with non-web Visual InterDev projects. See Chapter 2, Integrating SCC Projects with Dimensions, on page 31. Adding Non-Web Projects to Source Control To add a Visual InterDev project to source control: 1 Open or create the non-web project in Visual InterDev. 2 Select the project in the Project Explorer. 3 Select Project Source Control Add to source control. 4 If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. Development Interface Implementation Guide

292 Chapter 13 Visual InterDev Change selection 5 The Select workset directory for project dialog box appears. By default, your default workset and its top design part are selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. 6 A Dimensions SCC dialog box appears stating that the operation completed. Click OK. 7 A second Dimensions SCC dialog box states that the project is being opened in the workset. Click OK. 8 The Add to Source Control dialog box appears with a list of selected files. 9 Do any of the following: Change your selection of files to add to source control by selecting and deselecting files in the list. By default, every file in the project is selected. Retain lock If you do not want to automatically check out the files after you add them to source control, deselect the Keep checked out check box. Describe files Enter a description of the files in the Comment field. The description will be applied to all selected files. 10 Click OK. The selected files are added to source control. For each file added, the file icon in the FileView pane changes to indicate that the file is under source control: Checked in Checked out A blue lock indicates that a file is under source control and is currently checked in. A red check mark indicates that a file is under source control and is currently checked out. Serena ChangeMan Dimensions

Integrating Source Control with Non-Web Projects 293 Disconnecting Non-Web Projects from Source Control When you disconnect a project from source control, Dimensions does not delete the Dimensions project; it only removes the association between the IDE files and Dimensions. You can always reconnect the project to source control later. To disconnect a project from source control: 1 Select the project in the Project Explorer. 2 Select Project Source Control Change Connection. The Set Source Control Connection dialog box appears. 3 Select the Work offline option. 4 Click OK. The project is disconnected from source control. Removing Files from Source Control When you remove a file from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain. To remove files from source control: 1 Select the files you want to remove in the Project Explorer. Development Interface Implementation Guide

294 Chapter 13 Visual InterDev 2 Select Project Source Control Remove. The Remove items from source control dialog box appears with a list of the files you selected. You can change your selection by selecting and deselecting files in the Items list. 3 Click OK. Deleting Files from Visual InterDev and Source Control Deleting a file removes it from the Visual InterDev project and from the Dimensions repository. This operation is permanent. To delete a file: 1 Select the file you want to delete in the Project Explorer. 2 Select Edit Delete. 3 You are prompted to confirm the delete operation. Click Yes. The Push Remove to Server dialog box appears. 4 Select one of the following options: Remove Now: To delete the file from the Dimensions repository. Remind later: To be prompted again the next time you work with this project. Do nothing: The file is not deleted from the Dimensions repository and you are not reminded to do so again. 5 Click OK. Serena ChangeMan Dimensions

Using Source Control with Non-Web Projects 295 Using Source Control with Non-Web Projects Contents For more information This section contains procedural information about viewing and editing non-web files that are under source control. See Using Dimensions with IDE Projects on page 61. Getting Projects or Solutions When you get a Visual InterDev project or solution, read-only copies of all files within the project or solution are placed in the workfile location. To get a project from source control: 1 Select File Open Project. The Open Project dialog box appears. NOTE The Open Project dialog box may also appear when you first launch Visual InterDev. 2 Select the Existing tab. 3 Click the Source Control button. The Select SCC Project dialog box appears. 4 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Select an existing workset from the Workset drop-down list. By default, your default workset is used. 5 Select the project you want to get from the Project dropdown list. Development Interface Implementation Guide

296 Chapter 13 Visual InterDev 6 Click OK. The Browse for Folder dialog box appears. 7 Navigate to the parent directory to copy the project subdirectory and files to and click OK. 8 The Open Project dialog box reappears. Select the Visual InterDev project or solution you want to open. If you open a project, it will appear under a new solution. 9 Click OK. Getting Files When you get a file, a read-only copy of the latest revision is placed in the workfile location. To get files: 1 Select the file or files from the Project Explorer. Serena ChangeMan Dimensions

Using Source Control with Non-Web Projects 297 2 Select Project Source Control Get Latest Version. The Get Latest Version dialog box appears with a list of selected files. You can change your selection by selecting and deselecting files in this list. 3 Do any of the following: To get all items in the project, select the Directories check box, then select the Get items from subdirectories check box. To bypass the Get Latest Version dialog box in the future, select the Don t show any more get dialogs check box. To override the default get options, click the Advanced button. See Overriding Get Options on page 63. 4 Click OK. Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. To check out files: 1 Select the files you want to check out in the Project Explorer. 2 Select Project Source Control Check Out. The Check out items dialog box appears with a list of selected files. You can change your selection by selecting and deselecting files in this list. T I P To bypass the Check out item(s) dialog box in the future, select the Don t show any more check out dialogs check box. 3 To override the default check out options, click the Advanced button. See Overriding Check Out Options on page 64 Development Interface Implementation Guide

298 Chapter 13 Visual InterDev Edit the file 4 Click OK. A red check mark ( ) appears next to each file icon in the Project Explorer to indicate that the files are checked out. To edit a file that is checked out from source control, double click the file, or right-click the file and select Edit from the contextual menu. Undoing Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 Select the files you want to release in the Project Explorer. 2 Select Project Source Control Undo Check Out. The Undo Check Out dialog box appears with a list of selected files. You can change your selection by selecting and deselecting files in this list. T I P To bypass the Undo Check Out dialog box in the future, select the Don t show this dialog again check box. 3 To override the default undo check out options, click the Advanced button. See Overriding Undo Check Out Options on page 65. 4 Click OK. The red check mark ( ) is removed from each file icon in the Project Explorer to indicate that the files are unlocked. Serena ChangeMan Dimensions

Using Source Control with Non-Web Projects 299 Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. To check in files: 1 Select the files you wish to check in from the Project Explorer. 2 Select Project Source Control Check In. The Check in item(s) dialog box appears with a list of selected files. You can change your selection by selecting and deselecting files in this list. T I P To bypass the Check in item(s) dialog box in the future, select the Don t show any more check in dialogs check box. 3 Do any of the following: Retain lock To retain the lock on the files after they are checked in, select the Keep checked out check box. Compare files To compare the current workfile with the previous revision, click the Differences button. For more information see Viewing File or Project Differences on page 84. To override the default check in options, click the Advanced button. See Overriding Check In Options on page 66. 4 Enter a description of the changes you made in the Comment field. This description will be applied to all selected files. 5 Click OK. The red check mark ( ) is removed from each file icon in the Project Explorer to indicate that the files are checked in. Development Interface Implementation Guide

300 Chapter 13 Visual InterDev Accessing Specific Revisions To get, check out, check in, or undo a check out on a specific revision of a file, rather than the latest revision, select the file and then select Project Source Control History. You can then select the revision you want from the History tab of the resulting dialog box. You can also invoke the History tab during get and check out operations by pressing CTRL + SHIFT while clicking the OK button in the get or check out dialog box. For more information, see History Tab on page 76. Adding New Files When you add new files to a Visual InterDev project, the Push Add to Server dialog box appears. Serena ChangeMan Dimensions

Using Source Control with Non-Web Projects 301 Do one of the following: Add now To add the new files to source control, select Add now. Continue to the next section, Add to Source Control Now. Remind later To be reminded about the files next time you check in files or add files to source control, select Remind later and click OK. Do nothing To add the files to the Visual InterDev project without adding them to source control, select Do nothing and click OK. You will not be reminded later. Add to Source Control Now After you have selected the Add now option in the Push Add to Server dialog box, complete the following procedure to add the new files to source control. 1 Do any of the following: To change which files are selected, select or deselect files in the Items list. To retain a lock on the files after they are added, select the Keep checked out check box. 2 Enter a description of the files in the Comment field. The description will be applied to all selected files. 3 Click OK. Development Interface Implementation Guide

302 Chapter 13 Visual InterDev Serena ChangeMan Dimensions

303 14 Visual Studio.NET In this Chapter For this section... See page... Introduction 304 Accessing Supported Features 305 Setting Up Source Control Projects 306 Using Source Control 314 Development Interface Implementation Guide

304 Chapter 14 Visual Studio.NET Introduction Purpose This chapter has four purposes: List the Dimensions features available through Microsoft Visual Studio.NET 2003, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control Enhanced integration Help you access files that are under source control from within the IDE NOTE A separate enhanced integration, which includes change management, is available for Visual Studio.NET 2003. It is called the Dimensions for Visual Studio.NET Add-In. For more information, see the Serena ChangeMan Dimensions Dimensions for Visual Studio User s Guide or contact your Serena sales representative. For more information See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Serena ChangeMan Dimensions

Accessing Supported Features 305 Accessing Supported Features What is supported? Visual Studio.NET supports the full set of source control features available through the Dimensions Development Interface. See the following table. To... Select... For more information see... Get files File Source Control Get Getting Files on page 315 Open a project from source control File Source Control Open From Source Control Connecting Additional Workstations to a Source Control Project on page 312 Check out files File Source Control Check Out Checking Out Files on page 316 Undo check out of files File Source Control Undo Checkout Undoing Check Out on page 318 Check in files File Source Control Check In Checking In Files on page 318 View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships View project-level differences Add non-web solutions to source control Add web and nonweb projects to source control Remove or exclude files from source control Set SCC options for Visual Studio File Source Control History File Source Control Compare Versions File Source Control Add Solution to Source Control File Source Control Add Selected Projects to Source Control File Source Control Exclude Selection from Source Control Tools Options Viewing Source Control Information on page 72 Viewing File or Project Differences on page 84 Adding Visual Studio Files to Source Control on page 309 Adding Visual Studio Files to Source Control on page 309 Excluding or Removing Files from Source Control on page 308 Configuring Source Control Behavior on page 306 Development Interface Implementation Guide

306 Chapter 14 Visual Studio.NET To... Select... For more information see... Launch Dimensions desktop client File Source Control Dimensions SCC The Serena ChangeMan Dimensions User s Guide Setting Up Source Control Projects Contents For more information This section contains information about setting up the Dimensions Development Interface to work with Visual Studio.NET. See Chapter 2, Integrating SCC Projects with Dimensions, on page 31. Configuring Source Control Behavior You can configure Visual Studio so that actions you take in Visual Studio: Automatically invoke source control operations Do not invoke source control operations Prompt for permission to invoke source control operations Serena ChangeMan Dimensions

Setting Up Source Control Projects 307 To configure the source control behavior of Visual Studio: 1 Select Tools Options. The Options dialog box appears. 2 Select the Source Control folder in the left pane. 3 Select or deselect the features you wish to activate or deactivate. For detailed information on each feature, see the Visual Studio documentation. 4 Click OK. Configuring Web Projects By default, Visual Studio.NET is configured to use the SCC interface (File share) for both web and non-web projects. This is the recommended configuration, but may be unfamiliar to you since Visual InterDev 6 used the COM interface (FrontPage Extensions) for web projects. Development Interface Implementation Guide

308 Chapter 14 Visual Studio.NET To configure web project access: 1 Select Tools Options. The Options dialog box appears. 2 Open the Projects folder and select Web Settings. 3 Select the File share option. 4 Click OK. For more information on working with web projects, see the Visual Studio.NET documentation. Excluding or Removing Files from Source Control You can use the Exclude from Source Control feature in two ways: Used before a project is under source control, it will prevent Dimensions from creating repository files for the selected workspace files. Used after a project is under source control, it will retain the existing repository files but will prevent the addition of new revisions until the exclusion is removed. To exclude files from source control: 1 Select the files in the Project Explorer pane. 2 Select File Source Control Exclude Selection from Source Control. NOTE If the project file is not already checked out, you are prompted to check it out. A red circle ( ) appears to the left of each file icon, if the project is under source control. Serena ChangeMan Dimensions

Setting Up Source Control Projects 309 NOTE To remove an exclusion, repeat the procedure shown above. Adding Visual Studio Files to Source Control Use the following procedure to add files to source control. IMPORTANT! If working in a multi-developer environment, see Configuring a Multi-Developer Environment on page 311. To add files to source control: 1 Do one of the following: To add a web project to source control: a) Select the project in the Solution Explorer pane. b) Select Add Selected Projects to Source Control. IMPORTANT! Do not add web solutions to source control. Select the web project instead. To add a non-web solution and the projects within it to source control, select File Source Control Add Solution to Source Control. To add a project to source control without placing the solution under source control: a) Right-click the project in the Solution Explorer pane. A pop-up menu appears. b) Select Add Project to Source Control. Development Interface Implementation Guide

310 Chapter 14 Visual Studio.NET To add a new project to source control when the solution is already under source control: a) Create the new project in a directory below the initial project in the solution. The files of the new project appear in the Pending Checkins pane. b) Click the Check In button. IMPORTANT! To add a project or file to an existing solution or project that is already under source control, you must first check out the solution or project. 3 If you are adding a web project, the following dialog may appear. Click the Continue button. For more information, see Configuring Web Projects on page 307. 4 If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. 5 The Select workset directory for project dialog box appears. By default, your default workset and its top design part are selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. 6 A Dimensions SCC dialog box appears stating that the operation completed. Click OK. Serena ChangeMan Dimensions

Setting Up Source Control Projects 311 7 A second Dimensions SCC dialog box states that the project is being opened in the workset. Click OK. A blue padlock ( ) appears to the left of each file icon to indicate that the files are checked in to source control. Configuring a Multi-Developer Environment For best results, refer to the following steps when configuring source control in a multi-developer environment: 1 Place all files for the solution in question on one development system and ensure that you can successfully run a build. Ensure that you are satisfied with the directory structure of the workfiles before proceeding. This structure will be mirrored in source control. 2 From that system, individually add each project to source control. Do not add the solution file (.sln) to source control at this point. This ensures that you can open each project from source control individually, independent of the solution. If you add the solution file (.sln) and the projects below it to source control in a single operation, you will not be able to open the projects individually. 3 Add the solution file (.sln) to source control. 4 Create a baseline of the solution file (.sln). 5 Connect each developer s workstation to the source control project. See Connecting Additional Workstations to a Source Control Project on page 312. Individual developers should not check in changes to the solution file (.sln). If you must modify the solution file, as when adding new projects to the solution, see the next section, Modifying a Solution File. Development Interface Implementation Guide

312 Chapter 14 Visual Studio.NET Modifying a Solution File Individual developers should not check in changes to the solution file (.sln). If you must modify the solution file, as when adding new projects to the solution, follow the steps below: 1 Check out the solution file (.sln) to the development system from which the solution was originally placed under source control. 2 Create or copy the new IDE project or projects to that system. 3 Add the new IDE project or projects to the solution and save the solution. 4 Check in the solution file (.sln). 5 Create a baseline of the solution file (.sln). 6 Delete the solution and all of its associated workfiles from each developer s system. 7 Connect each developer s workstation to the source control project. See the next section, Connecting Additional Workstations to a Source Control Project. Connecting Additional Workstations to a Source Control Project After an IDE project has been created and added to source control, each developer can access it by opening it from source control, which creates a copy of the project on the developer s system. Once a developer has a local copy of a project, he can perform normal source control operations on it. Serena ChangeMan Dimensions

Setting Up Source Control Projects 313 To open a solution or project from source control: 1 Select File Source Control Open From Source Control. The Select SCC Project dialog box appears. 2 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Select an existing workset from the Workset drop-down list. By default, your default workset is used. 3 Select an existing project from the Project drop-down list. Development Interface Implementation Guide

314 Chapter 14 Visual Studio.NET 4 Click OK. The Browse for Folder dialog box appears. 5 Select a local directory into which to copy the solution or project and click OK. The Open Solution dialog box appears. 6 Select the solution or project file you want to open and click Open. Using Source Control Contents For more information This section contains procedural information about viewing and editing files that are under source control. See Chapter 4, Using Dimensions with IDE Projects, on page 61. Serena ChangeMan Dimensions

Using Source Control 315 Getting Files When you get a file, a read-only copy of the latest revision is placed in the workfile location. To get files: 1 Select the solution, project, or files you want to get in the Solution Explorer. 2 Select File Source Control Get. The Get dialog box appears. 3 Do any of the following: Select or deselect files in the Name list. To invoke the Merge Tool, select a file and click the Compare Versions button. For information on differencing, see Viewing File or Project Differences on page 84. Development Interface Implementation Guide

316 Chapter 14 Visual Studio.NET To override the default get options, click the Options button. See Overriding Get Options on page 63. 4 Click OK. NOTE To get files without invoking the Get dialog box, select File Source Control Get Latest Version. Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. To check out files: 1 In the Solution Explorer pane, select the files, projects, or solution you want to check out and right-click. A pop-up menu appears. IMPORTANT! Check out the solution and project files if they are under source control and your changes will affect them. Serena ChangeMan Dimensions

Using Source Control 317 2 Select Check Out. The Check Out dialog box appears. 3 Do any of the following: Select or deselect files in the Name list. To invoke the Merge Tool, select a file and click the Compare Versions button. For information on differencing, see Viewing File or Project Differences on page 84. To override the default check out options, click the Options button. See Overriding Check Out Options on page 64. 4 Click the Check Out button. A red check mark ( ) appears next to each file icon. Development Interface Implementation Guide

318 Chapter 14 Visual Studio.NET NOTE Ignore the Comments field during check out. You can add a comment during check in. Undoing Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 In the Solution Explorer pane, select the files, projects, or solution you want to undo a check out on and right-click. A pop-up menu appears. 2 Select Undo Checkout. The Undo Checkout dialog box appears. 3 Select or deselect files in the Name list as needed. 4 To override the default undo check out options, click the Options button. See Overriding Undo Check Out Options on page 65. 5 Click the Undo Checkout button. A blue padlock ( ) appears next to each file icon. Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. Serena ChangeMan Dimensions

Using Source Control 319 To check in files: 1 In the Solution Explorer pane, select the files, projects, or solution you want to check in and right-click. A pop-up menu appears. 2 Select Check In. The Check In dialog box appears. 3 Do any of the following: Select or deselect files in the Name list. Enter a description of the changes you made to the files in the Comments field. To invoke the Merge Tool, select a file and click the Compare Versions button. For information on differencing, see Viewing File or Project Differences on page 84. Development Interface Implementation Guide

320 Chapter 14 Visual Studio.NET To override the default check in options, click the Options button. See Overriding Check In Options on page 66. To automatically check the files out again after the check in operation, click the down-arrow next to the Options button and select Keep Checked Out from the resulting menu. 4 Click the Check In button. A blue padlock ( ) appears next to each file icon (unless you chose to keep the files checked out). Accessing Specific Revisions To get, check out, check in, or undo a check out on a specific revision of a file, rather than the latest revision, select the file in the Solution Explorer pane and then select File Source Control History. You can then select the revision you want from the History tab of the resulting dialog box. You can also invoke the History tab during get and check out operations by pressing CTRL + SHIFT while clicking the Get or Check Out button in the get or check out dialog box. For more information, see History Tab on page 76. Visual Basic IMPORTANT! Visual Basic files are sometimes paired with a binary file. In such cases, the History tab will appear twice, once for the text file and once for the binary file. Be sure to always act upon both files or the files could become out of sync. For more information about Visual Basic file pairs, see About Visual Basic Files on page 239. Serena ChangeMan Dimensions

15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 321 In this Chapter For this section... See page... Introduction 322 Accessing Supported Features 323 Setting Up Source Control Projects 324 Using Source Control 343 Development Interface Implementation Guide

322 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) Introduction Purpose This chapter has four purposes: List the Dimensions features available through Eclipse 2 & 3, IBM WebSphere Studio Application Developer (WSAD) 5.0 & 5.1 and IBM WebSphere Studio Enterprise Developer (WSED) 5.0, and provide a quick reference to accessing those features Note any features described in Part 1 of this manual that do not apply to this IDE Help you set up source control projects and add files to source control For more information Help you access files that are under source control from within the IDE See Part 1: The Dimensions Development Interface, on page 21 for information about: Source control concepts Source control defaults Advanced source control features Serena ChangeMan Dimensions

Accessing Supported Features 323 Accessing Supported Features What is supported? Eclipse and WebSphere Studio Application Developer support the full set of source control features available through the Dimensions Development Interface. See the following table. To... Select... For more information see... Get files Right-click Replace With Revision from Serena Team Provider Getting Files on page 345 Check out files Right-click Team Checkout Checking Out Files on page 345 Lock revisions without overwriting work files Right-click Team Lock Locking Files on page 346 Undo check out of files Right-click Team Undo Checkout Undoing Check Out on page 347 Check in files Right-click Team Checkin Checking In Files on page 348 View Information: - File Detail - History - Merge/Difference - Pedigree - Relationships View project-level differences Compare workspace with local history Replace workspace with local history Connect projects to source control Add new files to source control Right-click Team Show History Right-click Compare With Serena Team Provider Right-click Compare With Local History Right-click Replace With Local History Right-click Team Share Project Right-click Team Add Viewing Source Control Information on page 72 Viewing File or Project Differences on page 84 Comparing with Local History on page 359 Replacing with Local History on page 360 Connecting Projects to Source Control on page 326 Adding New Files to Source Control on page 333 Development Interface Implementation Guide

324 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) To... Select... For more information see... Move project elements Rename projects or project elements Disconnect projects from source control Remove files from source control Open project from source control Refresh source control status Synchronize your workspace with source control Launch Dimensions desktop client Refactor Move Refactor Rename Right-click Team Disconnect Project Right-click Team Remove Serena Open from Serena Team Provider Right-click Team Refresh Project Status Right-click Team Synchronize Project Serena Run Serena Client Moving Project Elements on page 335 Renaming Projects or Project Elements on page 339 Disconnecting Projects from Source Control on page 342 Removing Files from Source Control on page 342 Connecting Additional Workstations to a Source Control Project on page 330 Viewing Source Control Status on page 343 Synchronizing Your Workspace with Source Control on page 355 The Serena ChangeMan Dimensions User s Guide NOTE IBM WebSphere Studio Enterprise Developer (WSED) 5.0 support is provided for local Cobol and PL/I files only. Setting Up Source Control Projects Contents Prerequisites This section contains information about setting up the Dimensions Development Interface to work with Eclipse-based IDEs. IMPORTANT! Eclipse requires JRE 1.3 or 1.4, but it will attempt to use the first JRE found in the path. No JRE is included with Eclipse. Serena ChangeMan Dimensions

Setting Up Source Control Projects 325 For more information See Chapter 2, Integrating SCC Projects with Dimensions, on page 31. Configuring Merge Behavior When you check in files, a prompt appears for the Serena ChangeMan Merge Tool if the tip revision is newer than the revision you started with and the default behaviour of Dimensions SCC is enabled. We recommend that the default behaviour is not disabled to avoid unnecessary branching when working in Local Mode. For implementation details, see Configuring Source Control Options on page 32. Excluding Files and Directories from Source Control You can configure Eclipse-based IDEs to exclude specified files from source control. This can minimize the size of the project database. For example, you could exclude all files with a.tmp file extension. IMPORTANT! Specify any files you wish to exclude from source control before adding the project they are in to source control. To exclude specified files from source control: 1 Select Window Preferences. The Preferences dialog box appears. 2 Click the plus sign next to Team and select Ignore Resources. 3 Examine the Ignore Patterns list for the file type you wish to exclude form source control. If it is not listed, do the following: a Click the Add button. The Enter Ignore Pattern dialog box appears. Development Interface Implementation Guide

326 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) b Enter a pattern that defines a file type to ignore. Use wildcards if needed: Asterisks (*) represent one or more characters. Question marks (?) represent one character. c Click OK. 4 In the Ignore Patterns list, ensure that a check mark appears next to each file type you want to exclude from source control. 5 Click OK. Connecting Projects to Source Control Before you can place IDE files under source control, you must connect your IDE project to source control. IMPORTANT! Specify any files you wish to exclude from source control before adding the project they are in to source control. See Excluding Files and Directories from Source Control on page 325. To connect to a Dimensions repository: 1 Right-click the project icon in the Package Explorer or Navigator. A pop-up menu appears. Serena ChangeMan Dimensions

Setting Up Source Control Projects 327 2 Select Team Share Project. The Share Project dialog box appears. 3 Select Serena Team Provider from the Select a repository type list. Development Interface Implementation Guide

328 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 4 Click the Next button. The Create or Select a Serena Team Provider Project dialog box appears. 5 Click the Create/Select button. 6 If your current IDE session is not yet logged in to Dimensions, the Dimensions Login dialog box appears. Log in to Dimensions. For more information on logging in to Dimensions see Connecting to Dimensions on page 35. 7 The Select workset directory for project dialog box appears. By default, your default workset and its top design part are selected. Accept the defaults by clicking the OK button, or make different selections from the drop-down lists. For more information, see Registering IDE Projects with Dimensions on page 37. 8 A Dimensions SCC dialog box appears stating that the operation completed. Click OK. A second Dimensions SCC Serena ChangeMan Dimensions

Setting Up Source Control Projects 329 dialog box states that the project is being opened in the workset. 9 Click OK. The Create or Select a Serena Team Provider Project dialog box reappears. 10 Click Finish. The Add to Source Control dialog box appears with a list of selected files to be added. Development Interface Implementation Guide

330 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 11 Do any of the following: To change which files are selected, select and deselect files in the Files in list. NOTE You must add the.project file to source control. To check out and lock the files immediately after adding them to source control, select the Keep Checked Out check box. Enter a description of the files in the Comment field. 12 Click OK. A gold cylinder ( ) is added to the icon of each item to indicate that the item is under source control. Connecting Additional Workstations to a Source Control Project Once an Eclipse-based project is under source control, you can open it from any workstation that has access to the Dimensions repository. There are two ways to connect additional workstations to a source control project: Open the project from the Serena Team Provider. Export and import a Project Set file. Open from the Serena Team Provider To add existing repository projects to your workspace: 1 Select Serena Open from Serena Team Provider. The Select SCC Project dialog box appears. (For a screen shot, see page 42.) Serena ChangeMan Dimensions

Setting Up Source Control Projects 331 2 Do any of the following: Select an existing Dimensions product from the Product drop-down list. Select an existing workset from the Workset drop-down list. By default, your default workset is used. 3 Select the project you want to get from the Project dropdown list. 4 Click OK. The Browse for Folder dialog box appears. 5 Navigate to the parent directory you want to copy the project subdirectory and files to and click OK. 6 There is now an additional button on the "Advanced Options" dialog raised when opening a project from the Serena Team Provider. This button, labeled "No to All", has the same effect as the "No" option when opening a project from the Serena Team Provider. This is applicable to Development Interface Implementation Guide

332 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) importing Team Project Sets, which contains many projects as described in the next section. Export/Import a Project Set File A Project Set file contains the path information needed to connect other workstations to an existing source control project. To export a Project Set file: 1 Select File Export. The Export dialog box appears. 2 Select Team Project Set from the Select an export destination list. 3 Click the Next button. 4 Enter a path and file name in the File name field or browse to select a destination. 5 Click the Finish button. A *.PSF file is created in the selected directory. 6 Distribute the *.PSF file to each workstation or make it available from a network location. To import a Project Set file: 1 Select File Import. The Import dialog box appears. 2 Select Team Project Set from the Select an import source list. 3 Click the Next button. 4 Enter the path and file name of the *.PSF file in the File name field or browse to select it. 5 Click the Finish button. 6 There is now an additional button on the "Advanced Options" Dialog raised when importing Team Project Sets from the Serena Team Provider. This button, labeled "No to Serena ChangeMan Dimensions

Setting Up Source Control Projects 333 All", causes all subsequent invocations of the "Advanced Options" to be skipped. This is applicable where there are many projects in a Team Project Set. Adding New Files to Source Control Once you have connected an Eclipse project to source control, you can add new IDE files to source control at any time. (For details on connecting to project databases, see Connecting Projects to Source Control on page 326.) To add new files to an IDE project that is already under source control: 1 Right-click on the root of the IDE project in the Package Explorer or Navigator. A pop-up menu appears. Development Interface Implementation Guide

334 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 2 Select Team Add. The Add to Source Control dialog box appears with a list of selected files to be added. 3 Do any of the following: To change which files are selected, select and deselect files in the Files in list. To check out and lock the files immediately after adding them to source control, select the Keep Checked Out check box. Enter a description of the files in the Comment field. 4 Click OK. A gold cylinder ( ) is added to the icon of each item to indicate that the item is under source control. Serena ChangeMan Dimensions

Setting Up Source Control Projects 335 Refactoring: Moving or Renaming Projects or Project Elements For best results, keep the following in mind when performing refactoring operations: Before refactoring, all users should check in their changes. After refactoring, all users should get the updated project from source control. Moving Project Elements To move project elements: 1 Before moving project elements, all users should check in their changes. 2 Check out the elements to be moved. Special Considerations If moving to a different project: Make sure no one else has the source elements checked out. Select the Make Files Local check box. NOTE You can begin without checking out the source, but you must choose to check out the items when prompted to do so. 3 Select the items you wish to move. Development Interface Implementation Guide

336 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 4 Select Refactor Move. The Move dialog box appears. 5 Select a destination from the tree. 6 By default, the Update references to the moved element(s) option is selected. Deselect this option if you do not wish to updated references to the moved elements. 7 Do one of the following: Click the OK button. The operation completes. Serena ChangeMan Dimensions

Setting Up Source Control Projects 337 Click the Preview button. The Move page of the Refactoring wizard appears. 8 Review the changes associated with the move operation and deselect any you do not wish to perform. 9 Click the Finish button. If you are moving elements: Within a project, the elements appear as source controlled items in there new location. Development Interface Implementation Guide

338 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) To a different project, you are asked if you wish to remove the elements from source control. Click Yes. The elements appear as uncontrolled items in the destination project. You can now add the items to source control from their new location. 10 All users should now get the updated project from source control. See Getting Files on page 345 or Synchronizing Your Workspace with Source Control on page 355. Note About Refactoring When performing a move between projects as part of refactoring, it is strongly recommended that you choose the option to set the files to be updated as part of the refactoring in "Local Mode". If the files are checked out, then there is a conflict with the removal of the source file from source control as part of the cross-project move operation. The checked out revision will not be removed from source control, and you will receive a message to this effect in the console. The checked-out revision will remain in Dimensions and will be picked up by subsequent project structure synchronization operations. These revisions must have the checkout cancelled and be removed from the source project using the desktop client. A particular case of this is moving a file to a different package in the second project. The Eclipse/WSAD java tooling identifies that it needs to update the file with the new package name and initiates a checkout operation. If the file is checked out, then the subsequent attempt to remove form source control from the refactoring code will not remove the checked out revision as indicated above. Thus the recommendation to use local mode. This will make the file writable and the java refactoring code will be able to update the file as part of the move to the new package in the target project. As it is not checked out, the remove will succeed. Serena ChangeMan Dimensions

Setting Up Source Control Projects 339 The same will apply if files are checked out by another user prior to performing the refactoring. The revision checked out to the other user will not be removed and a warning will be issued in the console. These revisions must have the checkout cancelled and be removed from the source project using the desktop client as the appropriate user. We recommend using the "Team Refresh Project Status" to check that files which will be updated and moved are not checked out by another user(s) ( The "Lock" icon or layered "Lock" icon ) or are not checked out by you and other users (The layered "Check" icon) prior to performing the refactoring. Renaming Projects or Project Elements To rename a project or project element: 1 Before renaming projects or project elements, all users should check in their changes. 2 Check out the project or project elements to be renamed. NOTE You can begin without checking out the item to be renamed, but you must choose to check out the item when prompted to do so. 3 Select the item you wish to rename. Development Interface Implementation Guide

340 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 4 Select Refactor Rename. Page 1 of the Refactoring wizard appears. 5 Enter the new name for the item in the Enter new name field. 6 Select any of the following options: Update references to the renamed element Update references in Javadoc comments Serena ChangeMan Dimensions

Setting Up Source Control Projects 341 Update references in regular comments Update references in string literals 7 Click the Next button. Page 2 of the Refactoring wizard appears. 8 Review the changes associated with the rename operation and deselect any you do not wish to perform. 9 Click the Finish button. Development Interface Implementation Guide

342 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 10 All users should now get the updated project from source control. See Getting Files on page 345 or Synchronizing Your Workspace with Source Control on page 355. Disconnecting Projects from Source Control When you disconnect a project from source control, Dimensions does not delete revisions in the repository; it simply removes the association between the IDE project and the repository. To disconnect a project from source control: 1 Right-click the project icon in the Package Explorer or Navigator. A Pop-up menu appears. 2 Select Team Disconnect Project. A prompt appears to confirm that you wish to disconnect the project. 3 Click Yes. Removing Files from Source Control When you remove a file from source control, you will no longer be able to access previous revisions of the file. Only the latest revision will remain. To remove files from source control: 1 Select the files you want to remove in the Package Explorer and right-click. A pop-up menu appears. 2 Select Team Remove. The Remove from Serena Team Provider dialog box appears with a list of files to be removed. 3 Select or deselect files in the list as needed. 4 Click OK. Serena ChangeMan Dimensions

Using Source Control 343 Using Source Control Contents This section contains procedural information about viewing and editing files that are under source control. Viewing Source Control Status Dimensions indicates status and revision information by displaying graphics and text next to the object icons in the Package Explorer and Navigator, as in the following image. The following table lists the information that can be displayed. This graphic/text... Indicates... (Online) (Offline) Whether you are working in online or offline mode. (1.0) The revision you got or checked out from source control to your workspace. [1.2] The current tip revision in the source control repository if the tip is not the revision in your workspace. Development Interface Implementation Guide

344 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) This graphic/text... Indicates... The object is under source control and it is checked in. You have the object checked out. Someone else has the object checked out. Multiple users have the object checked out and you are not one of them. Multiple users have the object checked out and you are one of them. The file is locked exclusively--no other users can lock the file. The object is in local mode. The object contains objects that have been modified locally or for which there are newer revisions in the source control repository. The object has been modified locally and is out of synch with the repository. The repository contains a newer revision of this object. NOTE If you modify the local object, the graphic will change to a right-pointing arrow. To refresh status information, right-click on a project and select Team Refresh Project Status. Enabling Serena Icon Glyphs By default, Serena icon glyphs are enabled. Serena ChangeMan Dimensions

Using Source Control 345 To enable Serena Icon Glyphs: 1 Select Window Preferences. The Preferences dialog box appears. 2 Click the plus sign next to Workbench and select Label Decorations. 3 Select Serena in the Available label decorations list. 4 Click OK. Getting Files When you get a file, a read-only copy of the latest revision is placed in the workfile location. To get files: 1 In the Package Explorer or Navigator, select the files you want to get and right-click. A pop-up menu appears. 2 Select Replace With Revision from Serena Team Provider. The Get dialog box appears with a list of selected files. You can change your selection by selecting and deselecting the files in this list. 3 To override the default get options, click the Advanced button. See Overriding Get Options on page 63. 4 Click OK. Read-only copies of the selected revisions are placed in the workfile location. Checking Out Files When you check out a file, a writable copy of the latest revision is placed in the workfile location and assigned the next revision number. Development Interface Implementation Guide

346 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) To check out files: 1 In the Package Explorer or Navigator, select the files you want to check out and right-click. A pop-up menu appears. IMPORTANT! Check out the project files if your changes will affect them. 2 Select Team Checkout. The Check Out dialog box appears with a list of selected files. You can change your selection by selecting and deselecting the files in this list. 3 (Optional) To modify the files locally without first placing a source control lock on them, select the Make Files Local check box. NOTE Other users can still check out, modify, and check in changes to any files you use in local mode. You must resolve any resulting code conflicts if you decide to check in the changes you make while in local mode. See Using Local Mode on page 349. 4 To override the default check out options, click the Advanced button. See Overriding Check Out Options on page 64. 5 Click OK. A check mark ( ) appears next to each file icon to indicate that the files are checked out. Locking Files When you lock a file, the revision is locked in source control but no files are written to the workfile location so your existing workfile is not overwritten. Serena ChangeMan Dimensions

Using Source Control 347 To lock files: 1 In the Package Explorer or Navigator, select the files you want to lock and right-click. A pop-up menu appears. 2 Select Team Lock. The Check Out dialog box appears with a list of selected files. You can change your selection by selecting and deselecting the files in this list. 3 (Optional) To modify the files locally without first placing a source control lock on them, select the Make Files Local check box. NOTE Other users can still check out, modify, and check in changes to any files you use in local mode. You must resolve any resulting code conflicts if you decide to check in the changes you make while in local mode. See Using Local Mode on page 349. 4 Click OK. A check mark ( ) appears next to each file icon to indicate that the files are locked. Undoing Check Out When you undo a check out, a read-only copy of the latest revision is left in the workfile location and the revision number that was created during check out is released. No changes are checked into the Dimensions repository. To undo a check out: 1 In the Package Explorer or Navigator, select the files you want to unlock and right-click. A pop-up menu appears. 2 Select Team Undo Checkout. The Undo Check Out dialog box appears with a list of selected files. You can change your selection by selecting and deselecting the files in this list. Development Interface Implementation Guide

348 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 3 To override the default undo check out options, click the Advanced button. See Overriding Undo Check Out Options on page 65. 4 Click OK. The check mark is removed from each file icon to indicate that the files are unlocked. Checking In Files When you check in a file, a read-only workfile is left in the workfile location and the revision is checked into the Dimensions repository. NOTE The default Dimensions SCC configuration will automatically prompt for the Serena ChangeMan Merge Tool if you modified a file in local mode and the tip revision is newer than the revision you started with. For implementation details, see Configuring Source Control Options on page 32 To check in files: 1 In the Package Explorer or Navigator, select the files you want to check in and right-click. A pop-up menu appears. 2 Select Team Checkin. The Check In dialog box appears with a list of selected files. You can change your selection by selecting and deselecting the files in this list. 3 Do any of the following: Retain lock To retain the lock on the files after they are checked in, select the Keep Checked Out check box. Compare files To invoke the Merge Tool: a) Select a single file from the Files in list. b) Click the Differences button. For information on differencing, see Viewing File or Project Differences on page 84. Serena ChangeMan Dimensions

Using Source Control 349 Enter a description of the changes you made in the Comment field. To override the default check in options, click the Advanced button. See Overriding Check In Options on page 66. 3 Click OK. The check mark is removed from each file icon to indicate that the files are checked in. Accessing Specific Revisions To get, check out, check in, or undo a check out on a specific revision of a file, rather than the latest revision, select the file and then select Team Show History. You can then select the revision you want from the History tab of the resulting dialog box. You can also invoke the History tab during get and check out operations by pressing CTRL + SHIFT while clicking the OK button in the get or check out dialog box. For more information, see History Tab on page 76. Using Local Mode You can edit projects and/or files without checking them out from source control by working on them in local mode. Local mode can be enabled for individual projects or files, unlike offline mode which affects the entire IDE. Putting Files into Local Mode To put files into local mode: 1 In the Package Explorer or Navigator, select the project(s) or file(s) you want to work on in local mode and right-click. A pop-up menu appears. Development Interface Implementation Guide

350 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 2 Do one of the following: Select Team Local Mode. Select Team Checkout then select the Make Files Local check box on the Check Out dialog box. Complete the check out operation as normal. The local mode graphic ( selected files. ) appears on the icons of the Reverting Local Mode Files to Controlled Mode To revert files to controlled mode: 1 In the Package Explorer or Navigator, select the local mode project(s) or file(s) you want to revert to controlled mode and right-click. A pop-up menu appears. 2 Select Team Revert Controlled. Depending upon what changes are found, any of the following may occur: Serena ChangeMan Dimensions

Using Source Control 351 The Revert to Controlled dialog box appears with a list of files that have not changed while in local mode. Select or deselect files in this list as needed and click OK. The files are removed from local mode. Development Interface Implementation Guide

352 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) The Mark as Checked Out dialog box appears with a list of files that you have edited while in local mode. Select or deselect files in this list as needed and click OK. The selected files are removed from local mode and are shown as being checked out by you. To add your local mode edits to source control, check in the files. NOTE The default Dimensions SCC configuration will automatically prompt for the Serena ChangeMan Merge Tool if you modified a file in local mode and the tip revision is newer than the revision you started with. For implementation details, see Configuring Source Control Options on page 32 The deselected files are removed from local mode. To overwrite your local mode edits, do a get or check out. Serena ChangeMan Dimensions

Using Source Control 353 Working Offline You can configure the integration to give you the option of working in offline mode. This allows you to edit projects in your local workspace without checking the files out from source control. You may find this feature useful if you wish to: Experiment with code and not check in the resulting changes. Continue development while away from your network connection then synchronize your offline changes with source control when you can reconnect. NOTE You can refactor when in offline mode, but there are significant risks. If other users have refactored the code while you were offline, your offline refactoring will be unaware of the changes they made. This will result in errors which will require manual fixes. Enabling the Online/Offline Prompt You can enable a prompt that appears while the IDE is starting up that asks if you wish to work in online or offline mode. To enable the Online/Offline prompt: 1 Select Window Preferences. The Preferences dialog box appears. 2 Select Serena from under Team in the left pane. The Serena pane appears. 3 Select the Ask to go Offline at startup check box. 4 Click OK. Development Interface Implementation Guide

354 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) To Enter/Exit Offline Mode Once the Online/Offline prompt is enabled, you can enter or exit Offline mode when ever you start the IDE. To enter/exit offline mode: 1 Launch the IDE. A prompt appears as the IDE starts up. 2 Click Online to enter online or Offline to enter offline mode. The mode you select will remain in effect until you restart the IDE and make another selection. The current mode is displayed next to each project in the Package Explorer and Navigator as (Online) or (Offline). 3 From this release of the Integration, it is now possible to enter/exit offline mode from the Serena pull-down menu. This is a toggle that indicates that the integration is in online mode when checked. Selecting the option will take the integration into offline mode and the check mark will be removed. Selecting the option again will return to online mode and you will have to login to Dimensions again. This option is intended for Eclipse based IDEs with significant startup times where the use of the startup online/offline mode dialog mechanism is not appropriate. Serena ChangeMan Dimensions

Using Source Control 355 NOTE If you wish to check in the changes you made while working in offline mode, you must enter online mode then synchronize your local workspace with source control (see the next section). Synchronizing Your Workspace with Source Control In a multi-user environment, you should synchronize your workspace with source control to: Remove files from your local workspace that other users have removed from the source control project. Add files to your local workspace that other users have added to the source control project. Add files to the source control project that you have added to your local workspace. Update the content of files in your local workspace that other users have modified and checked into the source control project. Update the content of files in the source control project that you have modified in your local workspace. To synchronize your workspace with source control: 1 In the Package Explorer or Navigator, select the project(s) you want to synchronize and right-click. A pop-up menu appears. Development Interface Implementation Guide

356 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 2 Select Team Synchronize Project. The Synchronize dialog box appears. 3 Select the type of synchronization operations you want to perform: Revert files to controlled: Reverts local mode files in your local workspace to active source control status. If the files have been modified, they will be marked as checked out. If you also select Refresh project files, the modified files will be checked in. Refresh project structure: Updates you workspace and the source control project by adding or deleting projects and files. Refresh project files: Updates the contents of files in your local workspace and the source control project. 4 Click OK. Depending upon the type of synchronization you selected and what changes are found, any of the following may occur: Revert files to controlled The Revert to Controlled dialog box appears with a list of files that have not changed while in local mode. a) Select or deselect files in the list as needed. Serena ChangeMan Dimensions

Using Source Control 357 b) Click OK. The files are removed from local mode. The Mark as Checked Out dialog box appears with a list of files that you have edited while in local mode. Refresh project structure a) Select or deselect files in the list as needed. b) Click OK. The files are removed from local mode and are shown as being checked out by you. To add your local mode edits to source control, check in the files. If you selected Refresh project files in the Synchronize dialog box, the files will be checked in by a subsequent dialog box; see below. The Refresh Project Structure - New Repository Files dialog box appears with a list of files that are in the source control project but not in your local workspace. You can select and deselect files in this list. a) Select or deselect files in the list as needed. b) Click OK. Read-only copies of the files are placed in the workfile location. The Refresh Project Structure - New Local Files dialog box appears with a list of files that are in your local workspace but not in the source control project. a) Do any of the following: To change which files are selected, select and deselect files in the Files in list. To check out and lock the files immediately after adding them to source control, select the Keep Checked Out check box. To add any empty folders to source control, select the Add Empty Folders check box. b) Enter a description of the files in the Comment field. The description will be applied to all selected files. Development Interface Implementation Guide

358 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) T I P To use a unique description for each file, leave the Comment field blank. After you complete the Add to Source Control dialog box, the Change Description dialog box will appear. Enter a description for each file in turn. c) Click OK. A gold cylinder ( ) is added to the icon of each item to indicate that the item is under source control. The Refresh Project Structure - Remove from Workspace dialog box appears with a list of files that have been removed from source control but still exist in your local workspace. Refresh project files a) Select or deselect files in the list as needed. b) Click OK. The Check in Edited Files dialog box appears. a) Select or deselect files in the list as needed. b) To check out and lock the files immediately after checking them in, select the Keep Checked Out check box. c) Enter a description of the edits you made in the Comment field. d) Click OK. The check mark is removed from each file icon to indicate that the files are checked in. The Get Changed Files dialog box appears. a) Select or deselect files in the list as needed. b) Click OK. Read-only copies of the files are placed in the workfile location. Serena ChangeMan Dimensions

Using Source Control 359 Comparing with Local History You can compare a workfile with a local history of the changes made to that workfile. A new entry is made in the local history each time you save changes to a file. NOTE To configure how many entries are retained and for how long, select Window Preferences then select Local History from under Workbench. For more information, see the WebSphere Studio help. To compare with local history: 1 In the Package Explorer or Navigator, select the file you want to compare and right-click. A pop-up menu appears. Development Interface Implementation Guide

360 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 2 Select Compare With Local History. The Compare with Local History dialog box appears. 3 Select a local history entry from the Local History of filename pane. 4 Use the Select Next Change ( ) and Select Previous Change ( ) buttons to step through the changes. 5 Click OK to exit the compare. Replacing with Local History You can replace a workfile with an entry from the local history of changes made to that workfile. A new entry is made in the local history each time you save changes to a file. Serena ChangeMan Dimensions

Using Source Control 361 NOTE To configure how many entries are retained and for how long, select Window Preferences then select Local History from under Workbench. For more information, see the WebSphere Studio help. To replace with local history: 1 In the Package Explorer or Navigator, select the file you want to replace and right-click. A pop-up menu appears. NOTE The file must be checked out. 2 Select Replace With Local History. The Replace from Local History dialog box appears. Development Interface Implementation Guide

362 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) 3 Select a local history entry from the Local History of filename pane. 4 Use the Select Next Change ( ) and Select Previous Change ( ) buttons to step through the changes. 5 Do one of the following: To replace the workfile with the selected history entry, click the Replace button. To close the dialog box without replacing the workfile, click the Cancel button. Notes for WebSphere Studio Enterprise Developer Upload Rules Additional default upload rules for the file types in WebSphere Studio Enterprise Developer 5.0 are provided in this release. These are applied to any newly created base database and will be applied on upgrade of pre-dimensions 9.1 base databases. The addition of these default rules will remove any previous default definition for the "Eclipse" IDE. If you have made any customizations to the original default rule set for "Eclipse" these will have to be reapplied. WebSphere Studio Enterprise Developer 5.0 LPEX Editor Editing of controlled source files using the LPEX editor in WebSphere Studio Enterprise Developer 5.0 requires that either the files are checked out or made local prior to invoking the editor, or that the editor is taken out of Browse mode if it was invoked while the file was checked in. The LPEX editor does not Serena ChangeMan Dimensions

Notes for WebSphere Studio Enterprise Developer 363 fire the Eclipse Team core Validate Edit hook that allows the standard Java editor to check out files that are being edited. To take the LPEX editor out of Browse mode, issue the following command in the editor command line: set readonly off The file can then be edited and will prompt for check out of the file when the editor is saved. WebSphere Studio Enterprise Developer 5.0 eglbld Editor Editing.eglbld files in WebSphere Studio Enterprise Developer 5.0 requires that they are checked out or Made Local prior to editing. The editor does not fire the Eclipse Team core Validate Edit hook to allow a checked in read-only file to be checked out or made local prior to editing. This causes a warning to be raised by the "eglbld" editor, indicating that the file cannot be saved and must be saved to a different name. Making the file writable, by either setting Local Mode, or performing an explicit check out prior to editing, will make the operation perform as expected. Development Interface Implementation Guide

364 Chapter 15 WebSphere Studio Application Developer 5 (Eclipse 2 & 3) Serena ChangeMan Dimensions

365 Index A access, web server 50 accessing files from source control 62 actioning change documents 79 items 77 adding projects to source control 37 Administration Console, upload rules 44 advanced options 63 C change documents, actioning 79 change management about 68 enabling 69 using 69 check in files 63 check out files 62 COM and remote UNIX nodes 56 COM compliant IDEs 28 configuring defaults for web projects 52 web server security 50 configuring source control options 32 Connection 207 contacting technical support 19 conventions, typographical 17 Customize tab 83 D differencing 84 Dimensions representation of IDE projects 24 upload rules 45 Directory Service, Windows 50 DOORS adding files to source control 95 checking in a baseline 106 configuring Dimensions product for 95 configuring Dimensions to open DOORS requirements 104 exporting DOORS objects to change documents 109 fixing a failed baseline check in 112 installing the integration 95 integration, configuring 96 integration, setting up 94 locking a baseline 108 logging in to Dimensions 105 opening DOORS requirements from Dimensions 111 reports 113 supported features 92 unlocking a baseline 108 updating change document status 110 view change document status 111 view change documents from within DOORS 110 Development Interface Implementation Guide

366 Index E Eclipse adding additional workstations 330 files to source control 333 projects to source control 326 check in files 348 check out files 345 disconnect projects 342 excluding files 325 get files 345 moving 335 refactoring 335 remove files 342 renaming 335 revisions, accessing specific 349 supported features 323 undo check out 347 Eclipse 2 compare with local history 359 icon glyphs enabling 344 locking files 346 offline mode 353 replace with local history 360 source control status 343 extract files 62 F fetch files 62 File Detail tab 74 file differences, viewing 86 FrontPage adding new files 125 checking in files 124 checking out a previous revision 125 checking out files 123 projects adding to source control 120 disconnecting from source control G 122 supported features 118 undoing check out 123 get files 62 H History tab 76 I IDE Setup 44 IDEs supported 27 upload rules 45 item attribute rules 44, 45 items, actioning 77 L log in 35 M media kits ordering 18 merge on check in 32 setting defaults 33 Merge - Diff tab 81 Serena ChangeMan Dimensions

Index 367 O online help accessing 17 for the command-line interface 17 for the GUI 17 options, configuring 32 ordering media kits 18 overriding default options 63 P pedigree, viewing 75 PowerBuilder accessing specific revisions 161 checking in objects 160 checking out objects 158 disconnecting from source control 157 getting objects 157 objects removing from source control 156 taking objects 157 undoing check out 159 usability notes 163 printing manuals 18 project differences, viewing 86 project marker file 25 project path, specifying 39 R Rational Rose accessing specific revisions 180 adding files to source control 171 checking in files 179 checking out files 176 getting files 175 removing files from source control 173 supported features 168 undoing check out 177 Version Control Add-In 170 Relationships tab 79 restricting web server access 50 return files 63 revisions, specifying 77 role requirements 27 S SCC compliant IDEs 28 SCC, testing 45 security, web server 50 source control information 72 removing web projects from 57 source control options, configuring 32 specifying revisions 77 T technical support contacting 19 TestDirector integrations, about 182 issue management automatic synchronization 222 automatically created attributes and fields 230 connecting to Dimensions 205 connecting to TestDirector 207 deleting connections 227 deleting links 229 editing mappings 219 log files 231 mapping projects to Dimensions 209 resolving conflicts 234 setting up 202 submitting change documents 233 submitting defects 232 Development Interface Implementation Guide

368 Index troubleshooting 229 using 231 source control adding new tests 200 adding projects to 192 checking in tests 199 checking out tests 196 enabling 192 getting tests 195 installing and configuring 187 removing projects from 194 setting up 187 setting up user accounts 191 undoing check out 199 using 195 viewing version history 201 supported features 184 testing SCC 45 timestamps setting defaults 34 typographical conventions 17 U undo check out 62 UNIX, integrating COM with 56 upload rules 44 definition 45 user privileges, defining 50 types 51 V Visual Basic accessing specific revisions 255 adding new files to source control 256 adding projects to source control 244 binary files 239 checking in files 253 checking out files 250 configuring SCC behavior 243 connecting workstations 246 enabling source control 240 file pairs 239 files outside the project directory 242 getting files 248 removing files from source control 247 supported features 238 undo check out 251 usability notes 257 Visual C++ accessing specific revisions 145, 274 adding projects to source control 264 checking in files 142, 272 checking out files 140, 270 configuring SCC behavior 262 connecting workstations 135, 266 getting files 139, 270 removing files from source control 136, 268 supported features 128, 260, 323 undoing check out 141, 271 using with UNIX servers 263 Visual InterDev non-web projects about 289 accessing specific revisions 300 adding new files to source control 300 adding projects to source control 291 checking in files 299 checking out files 297 deleting files 294 disconnecting from source control 293 getting files 296 getting projects 295 push add to server 300 removing files from source control 293 supported features 290 undoing check out 298 web projects Serena ChangeMan Dimensions

Index 369 about 279 accessing previous revisions 289 adding new files to source control 289 adding to source control 279 checking in files 287 checking out files 285 deleting files 281 disconnecting from source control 280 getting files 282 Master/Local Mode 279 refreshing 284 removing files from source control 281 setting up 278 supported features 277 synchronizing 284 undoing check out 286 Visual Studio.NET accessing specific revisions 320 adding projects to source control 309 checking in files 318 checking out files 316 configuring SCC behavior 306 connecting workstations 312 excluding files from source control 308 getting files 315 multi-developer environment 311 removing files from source control 308 supported features 305 undoing check out 318 web server security 50 WebSphere Studio Application Developer 5 adding additional workstations 330 files to source control 333 projects to source control 326 check in files 348 check out files 345 compare with local history 359 disconnect projects 342 excluding files 325 get files 345 icon glyphs, enabling 344 locking files 346 moving 335 offline mode 353 refactoring 335 remove files 342 renaming 335 replace with local history 360 revisions, accessing specific 349 source control status 343 supported features 323 undo check out 347 Windows Directory Service 50 security 50 workset directory 25, 39, 40 workset scope, defining 40 W web projects about 48 adding to source control 56 administrative workflow 49 checking out a previous revision 58 setting the default workset 54 user accounts 53 Development Interface Implementation Guide

370 Index Serena ChangeMan Dimensions