Edition 3.0 SERENA CHANGEMAN DIMENSIONS DEVELOPMENT INTERFACE IMPLEMENTATION GUIDE

(1)

SERENA



CHANGEMAN



DIMENSIONS

™

DEVELOPMENT INTERFACE

IMPLEMENTATION GUIDE

(2)

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:

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.

(3)

3

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

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

Configuring Source Control Options . . . 32

Connecting to Dimensions . . . 35

Registering IDE Projects with Dimensions . . . 37

About Workset Scope . . . 40

(4)

Upload Rules Management . . . 44

What are Upload Rules? . . . 45

Testing Dimensions SCC . . . 45

3 Integrating COM Projects with Dimensions . . . .47

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

Accessing Files from Source Control . . . 62

Overriding Default Options . . . 63

(5)

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

5 DOORS . . . .91

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

(6)

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

Setting Up Source Control Projects . . . 119

Adding Web Projects to Source Control . . . 120

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

(7)

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

Getting Files . . . 139

Undoing Check Out . . . 141

Accessing Specific Revisions . . . 145

8 PowerBuilder . . . .147

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

Checking In Objects . . . 160

(8)

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

Before Adding Files to Source Control . . . 170

Adding Files to Source Control . . . 171

10 TestDirector . . . .181

About the Dimensions Integrations to TestDirector . . . 182

About TestDirector Defect Status and Dimensions Lifecycle States . . . 183

Source Control Features . . . 184

Issue Management Features . . . 185

Installing and Configuring the Software . . . 187

(9)

Table of Contents 9

Adding Projects to Source Control . . . 192

Removing Projects from Source Control . . . 194

Getting Tests . . . 195

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

(10)

About Visual Basic Files . . . 239

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

Adding New Files to Source Control . . . 256

Visual Basic Specific Usability Notes . . . 257

12 Visual C++ . . . .259

Using a UNIX Based Dimensions Server with Visual C++ . 263 Adding Visual C++ Files to Source Control . . . 264

(11)

Table of Contents 11

13 Visual InterDev . . . .275

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

Deleting Files from Visual InterDev and Source Control . . 281

Using Source Control with Web Projects . . . 282

Project-wide Get Options . . . 284

Undoing a Check Out . . . 286

Checking Out a Previous Revision. . . 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

Deleting Files from Visual InterDev and Source Control . . 294

Using Source Control with Non-Web Projects . . . 295

Getting Projects or Solutions . . . 295

(12)

14 Visual Studio .NET . . . .303

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

15 WebSphere Studio Application

Developer 5 (Eclipse 2 & 3) . . . .321

Configuring Merge Behavior . . . 325

Excluding Files and Directories from Source Control . . . . 325

Connecting Projects to Source Control . . . 326

(13)

Table of Contents 13

Refactoring: Moving or Renaming

Projects or Project Elements . . . 335

Disconnecting Projects from Source Control . . . 342

Viewing Source Control Status . . . 343

Locking Files . . . 346

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

(14)

(15)

15

Welcome to Dimensions

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.

Purpose of this manual

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

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.

Edition status 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.

(16)

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.

■ Part 2: ”IDE Reference,” on page 89, contains procedures

specific to setting up and using the Dimensions Development Interface with each supported IDE.

Unsupported features

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. Additional

information

Use this manual in conjunction with these additional sources of information:

For more information about... See the...

Installing Dimensions Serena ChangeMan Dimensions Installation Guide

Setting up and configuring Dimensions

Serena ChangeMan Dimensions Tool Administration Guide

Dimensions concepts Serena ChangeMan

Dimensions User’s Guide and

Serena ChangeMan Dimensions Process Modeling User’s Guide

Dimensions clients Serena ChangeMan Dimensions User’s Guide

(17)

Typographical Conventions 17

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.

Setting up and using your IDE with source control

Documentation and online help provided by the vendor of your IDE

Convention Explanation

italics Introduces new terms that you may not be familiar with and occasionally indicates emphasis.

bold Indicates the names of controls and fields on dialog boxes and emphasizes important information.

UPPERCASE Indicates keys or key combinations that you can use. For example, press the ENTER key.

monospace Indicates syntax examples, values that you specify, or results that you receive.

monospaced italics

Indicates names that are placeholders for values you specify; for example,filename.

monospace bold

Indicates the names of commands and command options in syntax examples. Also

(18)

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.

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.

(19)

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.

(20)

■ 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.

(21)

21

Part 1: The Dimensions

Development Interface

This chapter… Starts on page…

Overview of Dimensions Source Control

23 Integrating SCC Projects with

Dimensions

31 Integrating COM Projects with

Dimensions

47 Using Dimensions with IDE

Projects

(22)

Introduction

Contents This part of the manual contains conceptual and procedural information common to setting up and using the Dimensions Development Interface with all supported IDEs.

Purpose 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.

Unsupported features

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.

Additional information

Use this part of the manual in conjunction with these additional sources of information.

Dimensions concepts Serena ChangeMan

Dimensions User’s Guide and

Serena ChangeMan Dimensions Process Modeling User’s Guide

Setting up and using your IDE with source control

Documentation and online help provided by the vendor of your IDE

(23)

23

1 Overview of Dimensions

Source Control

In this Chapter

For this section... See page...

Introduction 24

Source Control Concepts 24

(24)

Introduction

Purpose This chapter is an introduction to key source control concepts and the way in which Dimensions represents and integrates with IDE projects.

For more information

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.

IDE specific information

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

(25)

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.

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:

(26)

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.

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.

IDE Extension

Caliber-RM .crm

Eclipse .ecl

FrontPage Extensions .fp

GDPro .gdp

MainFrame Express .mfe

JBuilder .jb

Net Express .ne

PowerBuilder .pb

Rational Rose .rr

Together .tg

Visual Basic .vb

Visual C++ .vc

(27)

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.

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

To... You need the role allowing...

Browse or get files Browsing or getting of the desired items in the project

Check out files Creation of new revisions of the item types used by files in the project Add files 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.

(28)

■ 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)

•

TestDirector (Issue Synchronization) Additional

information

For information on setting up Dimensions with your IDE, see the following:

Procedures common to

integrating with SCC compliant IDEs

Chapter 2, “Integrating SCC Projects with Dimensions,” on page 31

(29)

How Dimensions Integrates with IDEs 29

Procedures common to integrating with COM compliant IDEs

Chapter 3, “Integrating COM Projects with Dimensions,” on page 47

Procedures for integrating with specific IDEs

Part 2: ”IDE Reference,” on page 89

(30)

(31)

31

2 Integrating SCC Projects with

Dimensions

In this Chapter

Introduction 32

Configuring Source Control Options 32

Connecting to Dimensions 35

Registering IDE Projects with Dimensions 37 About Adding Files to Dimensions Source

Control

43

Upload Rules Management 44

(32)

Introduction

Contents and purpose

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. IDE specific

information

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:

(33)

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 Eclipse-based 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

(34)

•

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.

(35)

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 drop-down list.

(36)

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.

(37)

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

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.

Procedure 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.)

(38)

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.

(39)

■ 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.

Example 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.

4 Click OK. Additional

information

Use this section in conjunction with these additional sources of information:

For information about... See...

Follow-on procedures specific to your IDE

Part 2: ”IDE Reference,” on page 89

(40)

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

Project files could be located in:

■ FolderTwo ■ Project1

Example 2 Project path: MyProjects\Project1 Adding files to source control, described in generic, non-IDE-specific terms

“About Adding Files to Dimensions Source Control” on page 43

For information about... See...

Workset scope

(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.

(42)

■ 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.

(43)

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.

(44)

■ 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.

■ View, edit, and delete rules for Dimensions clients, IDEs, and

IDE projects.

Constraints 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.

Invocation 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.

(45)

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.

■ Rules for a specific project: The modified rules will be used

for all subsequent operations in that project. For more

information

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.

(46)

To test Dimensions SCC:

2 Click the Test button. The test results are displayed in the dialog box.

(47)

47

3 Integrating COM Projects with

Dimensions

In this Chapter

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

Nodes

56 Adding Web Projects to Source Control 56 Disconnecting Web Projects from Source Control 57 Checking Out a Previous Revision 58

(48)

Introduction

Contents and purpose

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 web-based IDE projects.

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.

(49)

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.

4 Add the IDE projects to source control. See “Adding Web Projects to Source Control” on page 56.

All users 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.

(50)

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:

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

Use this web server… With this operating system…

(51)

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… Has these privileges…

Administrator Administrative, authoring, browsing Author Authoring, browsing

(52)

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.

(53)

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.

(54)

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

(55)

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.

(56)

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

(57)

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:

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:

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.

Web Web subdirectories

(58)

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.

(59)

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.

(60)

(61)

61

4 Using Dimensions with IDE

Projects

In this Chapter

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

(62)

Introduction

Purpose 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.

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.

(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.)

(64)

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-by-line 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

(65)

the chapter specific to your IDE for information about invoking your IDE’s Check Out dialog box.)

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.

(66)

(See the chapter specific to your IDE for information about invoking your IDE’s Undo Check Out dialog box.)

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

(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-by-line 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.