IntegrationsUserGuide_Integrity_10_4
IntegrationsUserGuide_Integrity_10_4
4
Integrations User Guide
June, 2013
Integrity 10.4
Integrations User Guide
Copyright © 2013 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.
User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively "PTC") are subject to the
copyright laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and
use of such documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this
documentation if provided on software media, but only for internal/personal use and in accordance with the license agreement under
which the applicable software is licensed. Any copy made shall include the PTC copyright notice and any other proprietary notice
provided by PTC. Training materials may not be copied without the express written consent of PTC. This documentation may not be
disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly available by any
means without the prior written consent of PTC and no authorization is granted to make copies for such purposes.
Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as
a warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this
document.
The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary
information, and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any
form or medium, disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written
prior approval from PTC.
UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND CRIMINAL
PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC
software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and
private surveillance resources. As part of these efforts, PTC uses data monitoring and scouring technologies to obtain and transmit data on
users of illegal copies of our software. This data collection is not performed on users of legally licensed software from PTC and its
authorized distributors. If you are using an illegal copy of our software and do not consent to the collection and transmission of such data
(including to the United States), cease using the illegal version, and contact PTC to obtain a legally licensed copy.
Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of your PTC software.
UNITED STATES GOVERNMENT RESTRICTED RIGHTS LEGEND
This document and the software described herein are Commercial Computer Documentation and Software, pursuant to FAR 12.212(a)-(b)
(OCT’95) or DFARS 227.7202-1(a) and 227.7202-3(a) (JUN’95), and are provided to the US Government under a limited commercial license
only. For procurements predating the above clauses, use, duplication, or disclosure by the Government is subject to the restrictions set
forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS 252.227-7013 (OCT’88) or
Commercial Computer Software-Restricted Rights at FAR 52.227-19(c)(1)-(2) (JUN’87), as applicable. 01282013
PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA
Table of Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Integrity Integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Configuring Integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Before Using an Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Where To Go From Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
PART I: CODEGEAR
2 CodeGear Delphi Architect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Key Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Configuring the CodeGear Delphi Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Using the CodeGear Delphi Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Delphi Architect Commit Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Creating an Integrity Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Creating a Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Adding a Member to an Integrity Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Checking Out Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Checking In Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
I
Creating an Integrity Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Creating a Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Adding Members to an Integrity Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Checking Out Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Checking In Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
II
Setting Up Projects to Reuse Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Setting Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Parallel Development Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Optimistic Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Development Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Building Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Command Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Adding a Solution to Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Adding a New Project to Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Joining Development of a Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Adding Members to an Integrity Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Checking Out Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Checking In Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
III
Specifying Task Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Setting Task Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Synchronizing Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Synchronizing All Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Synchronizing Tasks By Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Synchronizing Linked Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Synchronizing Selected Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Detecting Conflicts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
IV
PART IV: OTHER
13 Sybase PowerBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Configuring the PowerBuilder Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Using the PowerBuilder Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Creating an Integrity Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Creating a Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Adding Members to an Integrity Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Checking Out Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Checking In Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
15 CA Endevor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Understanding the CA Endevor Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Integrity Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
PART V: APPENDIXES
A Configuring a Mapping Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Mapping Template XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Mapping Template Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
V
VI
CHAPTER ONE
Introduction 1
For configuration management, Integrity provides a number of integrations for industry leading
Integrated Development Environments (IDEs), such as IBM Rational Software Development/
Eclipse Platform and Microsoft Visual Studio. For workflows and documents, Integrity integrates
into HP Quality Center and Microsoft® Office applications (Microsoft Project, Word, and Excel).
Integrity blends transparently into your tools, providing you with access to Integrity core
functionality from within your host environment.
When using Integrity for configuration management, commands such as creating an Integrity
project or checking out a member are available from within your IDE. More advanced commands
(such as setting the member revision) that cannot be performed within the integrations, can be
performed in the Integrity Client graphical user interface (GUI). Typically, the Integrity Client
GUI can be opened from within the tool you are working in.
When using Integrity for workflows and documents, you can create new items from within your
chosen tool with a one-to-one mapping of fields, configured specifically for your workflow.
This chapter provides information on the following topics:
“About This Guide” on page 2
“Roles” on page 2
“Assumptions” on page 2
“Integrity Integrations” on page 3
“Before You Begin” on page 3
“Configuring Integrations” on page 3
“Before Using an Integration” on page 5
“Where To Go From Here” on page 6
1
About This Guide
For content that is essential and applicable to all guides, PTC provides a single location for you to
access information. See the Integrity Getting Started Guide for information on the following topics:
detailed descriptions for base concepts used in Integrity
installing and configuring the Integrity Client
an overview of the interfaces available for the Integrity Client
Most procedures in this guide are documented using menu-based commands; however, toolbar
buttons, shortcut menus, and shortcut keys exist for most procedures. For more information, refer
to descriptive tooltips and menu items in the interface.
For detailed information on wizards, views, and dialog box options, see the online help.
NOTE For this release, instances of the term “issue” appearing on the interface and in
configuration files, refer to Integrity items, and therefore have the same meaning.
Roles
There are two primary roles to consider when using Integrity—the administrator and the user.
The administrator installs the Integrity database on a network, defines and customizes item types
and workflow, manages groups, creates projects and assigns groups to them, manages e-mail
notification for users and groups, creates additional user accounts, and assigns permissions that
allow users access to specific Integrity operations.
The user is anyone who needs to work with Integrity. Users are assigned user permissions by the
administrator. Users are also assigned to groups that have specific Integrity group permissions
assigned by the administrator.
Assumptions
Before using Integrity, PTC assumes that you have experience with the following:
the operating systems used in your work environment (whether Windows, Solaris, Linux, or
IBM-AIX)
your chosen application (for example, Microsoft Project if you are using the Microsoft Project
integration or Microsoft Visual Studio if you are using an Microsoft IDE application)
for workflow management, the search operators and syntax for the database used by Integrity
(that is, the MS SQL Server, DB2, or Oracle database)
HTML (if you are creating and editing report templates)
XML (if you are modifying integration templates for the Microsoft Project integration)
2
Integrity Integrations
For current information on supported integrations for Integrity, go to the Integrity Support
Center:
http://www.ptc.com/support/integrity.htm
Configuring Integrations
The Integrity Client includes the File > Integrations menu action for enabling and disabling most
supported integrations. You can select from a list of available integrations and enable or disable
them, as required to work with your preferred application. There is no requirement to re-install
the Integrity Client.
NOTE Using the Enable/Disable Integrations dialog box, you can always restore an available
IDE integration at a later date.
Certain supported integrations cannot be enabled using the File > Integrations menu action.
Included in this category are certain Microsoft integrations (Visual Studio SDK, Word, Excel, and
Project) and the Integrity integrations with IBM/WebSphere/Rational/Eclipse. For more
information, refer to the respective chapters for these integrations.
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier.
The new default installation directory for the Integrity Client is:
On Windows: C:\Program Files\Integrity\IntegrityClient10
On UNIX: $HOME/Integrity/IntegrityClient10
3
which is changed from the previous directory (…/MKS/IntegrityClient).
If you had a previous version of the Integrity Client, PTC recommends that you first disable any
existing integrations and then uninstall the previous client before installing Integrity Client 10 (or
greater).
If you have installed Integrity Client 10.x and uninstalled the previous client, but did not disable
previous integrations, those integrations remain enabled but refer to a location that no longer
contains supporting files. In this scenario, SCC integrations are removed due to the missing DLLs.
The Visual Studio SDK integration will not operate due to the missing DLL. Eclipse-based
integrations will fail after a clean re-start of Eclipse.
If you have installed Integrity Client 10.x without first uninstalling the previous version of the
client, the enabled integrations continue to reference supporting files from the old location but
open with the new Integrity Client 10.x. Integrations continue to function in this scenario;
however, any integration-specific HotFixes applied to the Integrity Client 10.x will not update the
supporting files in the old client location.
In both of these scenarios, the integrations can be repaired. For more information on repairing an
integration, contact PTC - Integrity Support.
IMPORTANT If the command is not visible, you must enable it in the active viewset. For
information on viewsets, see the Integrity Getting Started Guide.
The selected integration is moved to the Enabled Integrations list and displays in bold type.
4 To activate the selected integration(s), click OK. The selected integration is activated.
5 To complete the activation, restart your computer.
IMPORTANT If the command is not visible, you must enable it in the active viewset. For
information on viewsets, see the Integrity Getting Started Guide.
4
2 In the Enabled Integrations list, select the integration(s) that you want to disable.
3 To move the selected integration(s) to the Disabled Integrations list, click . To move all
enabled integrations to the Disabled Integrations list, click . The selected integration is moved
to the Disabled Integrations list.
4 To disable the selected integration, click OK. The selected integration is disabled.
5 To complete the process, restart your computer.
5
IDE Integration Tips
where value specifies the file extensions you want stored in binary format, separated by the “|”
symbol. For example:
integrations.DefaultBinaryFileExtensionList=
exe|ocx|frx|doc|bmp|jpg|gif|wri|apf
HP Quality Center—Defect Module “HP Quality Center Requirements and Defect Modules” on
page 169
HP Quality Center—Requirements Module “HP Quality Center Requirements and Defect Modules” on
page 169
6
P ART I
CodeGear
7
C H A P T E R TW O
CodeGear Delphi Architect 2
This chapter provides information on using the Integrity integration with CodeGear Delphi
Architect 2005 (Delphi), including key considerations and the various Integrity operations and
actions you can perform using the Delphi Commit Browser.
This chapter provides information on following:
“Key Considerations” on page 9
“Configuring the CodeGear Delphi Integration” on page 9
“Using the CodeGear Delphi Integration” on page 9
“Delphi Architect Commit Browser” on page 10
“Creating an Integrity Project” on page 11
“Creating a Sandbox” on page 11
“Adding a Member to an Integrity Project” on page 12
“Checking Out Members” on page 12
“Checking In Members” on page 12
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
8
Key Considerations
Note the following when using the Delphi integration:
When you add a project to source control, the Sandbox location you specify in Integrity must
be the original path the project was saved to in Delphi. You must not edit this location.
Do not rename files in Delphi. Instead, in Integrity, use the Rename command, then use the
Resynchronize Member command in Delphi.
When performing a check out, check in, add member, drop member, resynchronize, or revert
operation, if the file is a form or its associated .pas file, the operation is performed on both the
DFM and PAS files. Similarly, when performing an Integrity operation on a Delphi project file
(DPR), its associated RES files are included in the operation.
You cannot double click a Delphi member revision in the Integrity Member History view to open
it. Instead, open the revision from within a Delphi session.
If the Integrity GUI is already running when you run a command from the integration that
launches an Integrity GUI dialog box, the dialog box is not active in the application window.
You must press ALT + TAB to make the dialog box active.
Command Function
Check Out Files Equivalent to the Integrity Member > Check Out command.
Checks out the selected file.
The Integrity Check Out dialog box displays.
9
Command Function
Undo Check Out Files Equivalent to the Integrity Member > Revert command.
Replaces the selected working file with the revision that was checked out, as it
appeared prior to modification, and unlocks the file.
The Integrity Overwrite dialog box may appear.
Commit Browser Launches the Commit Browser dialog box for the open Delphi project that is
under source control with Integrity. For available command operations, see
“Delphi Architect Commit Browser” on page 10.
Place Project into Source Control Equivalent to the Integrity Project > Create and Sandbox > Create command.
Creates an Integrity configuration management project and Sandbox from the
selected Delphi project.
Note: This command can be performed only once.
Pull Project from Source Control Equivalent to the Integrity Sandbox > Create command.
Creates a Sandbox from a project on the server.
Run SCC Integration Equivalent to launching the Integrity graphical user interface if there is no project
open that is currently under source control.
If a project under source control is open, the Run SCC Integration command
displays the Sandbox view.
Action Function
Commit Equivalent to the Integrity Member > Check In command. Checks in the
member, updating the head revision.
Check Out Equivalent to the Integrity Member > Check Out command. Checks out the
head revision of the member.
Undo Check Out Equivalent to the Integrity Member > Revert command. Reverts deferred
operations.
Add Equivalent to the Integrity Member > Add command. Adds members to a
project.
Remove Equivalent to the Integrity Member > Drop command. Drops members from a
project.
10
Integrity information is also available from the following Commit Browser tabs:
Summary Content specifies revision description for all members.
Individual Comment specifies the revision description for the selected member.
Local Source displays the working file contents of the selected member.
Diff and History
Show Differences launches the difference tool specified in the Integrity Client preferences.
Show History displays the member history in Integrity.
NOTE If you are using an existing project, click Cancel and select that project from the Create
Sandbox Wizard in step 5.
4 Create a project as described in the Integrity User Guide. The Create Sandbox Wizard displays.
5 Create a Sandbox as described in the Integrity User Guide. The Create Archive dialog box
displays.
6 Modify the Create Archive options as necessary as described in the Integrity User Guide.
Creating a Sandbox
To create a Sandbox in Delphi
1 In Delphi, select the project under version control that you want to create a Sandbox from.
IMPORTANT When you add a project to source control, the Sandbox location you specify in
Integrity must be the original path the project was saved to in Delphi. You must not edit
this location.
3 Select Tools > Team > Pull Project From Source Control. The Create Sandbox Wizard displays.
4 Create a Sandbox as described in the Integrity User Guide.
11
Adding a Member to an Integrity Project
To add a member to an Integrity project in Delphi
NOTE You can only add one member at a time to an Integrity project in Delphi.
Select Tools > Team > Add Files. The Add File(s) dialog box displays. Select the files you want to add,
then click OK. The Create Archive dialog box displays. Modify the Create Archive options as necessary
as described in the Integrity User Guide.
Checking In Members
To check in members in Delphi
To check in one file, select Tools > Team > Check In Files. The Check In File(s) dialog box displays.
Select the files you want to check in, then click OK. The Check In dialog box displays. Check in each
member as described in the Integrity User Guide.
12
13
CHAPTER THREE
CodeGear JBuilder 3
The Integrity integration with CodeGear JBuilder Enterprise 2007 and 2008 allows you to access
the configuration management functionality of Integrity through your JBuilder development
environment.
CodeGear JBuilder Enterprise 2007/2008 is based on the Eclipse Platform. For detailed
information on configuring and using an Eclipse-based integration, see “IBM Rational Eclipse
Platform” on page 17.
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
14
15
P ART II
IBM
16
CHAPTER FOUR
IBM Rational Eclipse Platform 4
The Integrity integration with Eclipse Platform and the IBM® Rational® Software Development
Platform series allows you to access Integrity version control commands through several IBM
products that use the IBM Rational Platform technology, based on the Eclipse open source
initiative.
IMPORTANT Integrations with the IBM Rational Eclipse platform work only on Windows and
Linux operating systems supported for the Integrity Client. For more information on
supported operating systems, go to the Integrity Support Center:
http://www.ptc.com/support/integrity.htm
Eclipse Team Support provides flexibility in designing and implementing support of the
repository on the workbench. In turn, the Integrity integration is easier to use and provides
greater control.
To assist you in using the integration, the following topics are discussed:
“Overview” on page 18
“Supported Versions” on page 18
“Before You Start” on page 18
“Configuring the IBM Rational Eclipse Integration” on page 19
“Using the Integration” on page 23
“Best Practices” on page 46
“Limitations” on page 47
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
17
Overview
The Integrity integration with Eclipse Platform and the IBM Rational® Software Development
Platform allows you to access Integrity version control commands through several IBM products
that use the IBM Rational Platform technology, based on the Eclipse open source initiative.
The integration also allows you to access Integrity version control commands through several
open source and commercially available development products, built as Eclipse Platform plug-ins.
The integration includes software developed by the Eclipse Project. For more information on the
Eclipse Project, browse to:
http://www.eclipse.org
Supported Versions
The integration with Eclipse Platform and IBM Rational® Software Development Platform is
designed to work with the following:
A supported and licensed IBM Rational Software Development Platform product
A product built on the Open Source Eclipse Platform
Any commercial development tool, certified as Ready for IBM Rational, built on the Eclipse
Platform
IMPORTANT For more information on supported versions of Eclipse Platfrom and IBM
Rational Software Development Platform, go to the Integrity Support Center:
http://www.ptc.com/support/integrity.htm
18
Configuring the IBM Rational Eclipse Integration
For integrations based on Eclipse Platform, including IBM’s Rational Architecture Management
and Construction solutions such as RAD and RSA, you enable the integration using the Add Site
function. For more information, see “To enable the Integrity integration with Eclipse 3.4” on
page 19 and “To enable the Integrity integration with Eclipse 3.5+” on page 20.
IMPORTANT To make use of a new version of the Eclipse integration, you must either
configure Eclipse to perform updates automatically, or force a manual update to pick up
the new version of the integration. In general, you can configure updates by selecting Help >
Check for Updates. For more information on updating software, see the Eclipse product
documentation.
With the release of Integrity 10.0, the default location of the Integrity integration
installation has changed and you must point Eclipse to the new location as the update site.
For example on Windows, the new default location is:
Program Files\Integrity\IntegrityClient10\integrations\
IBM\eclipse_3.4\eclipse
When uninstalling a previous version of the Integrity Client, you must also remove the
previous update site within Eclipse or an error occurs (No repository found) after
installing the new integration.
If you are working with Implementer, the Integrity Server must also be configured to allow
remote API connections to the server. For more information, see the Integrity Integrations Builder
API Guide.
After enabling the integration, you can also set general preferences and additional options related
to change packages and file annotations.
This section discusses the following topics:
“Enabling Access to Java API Libraries (Linux Only)” on page 19
“Enabling the Integration” on page 19
“Setting Preferences” on page 21
“Deactivating the Integration” on page 23
On the Linux platform, the Eclipse integration requires access to the Java API libraries.
Set the LD_LIBRARY_PATH environment variable to the following:
export LD_LIBRARY_PATH=<Integrity Client installdir>/lib/linux
where <Integrity Client installdir> is the path to the Integrity Client installation location.
19
3 To select the directory where you placed your plug-ins as an extension location, click Local
and navigate to the following directory:
<Integrity Client installdir>/integrations/IBM/eclipse_3.4/eclipse
where <Integrity Client installdir> is the path to the directory where you installed the
Integrity Client.
4 To enable the integration, check the box next to the newly-added integration and then click
Install. Eclipse copies the selected plug-in to the Eclipse Features and Plugins directory.
NOTE You can also use Eclipse drop-ins to add a plug-in. For more information on drop-
ins, consult the Eclipse product documentation.
NOTE The Classic Update method is not recommended for installing this version of the
Eclipse integration. Before installing the integration, you can confirm the setting for the
Classic Update option by selecting Window > Preferences and expanding the General node.
Click the Capabilities subnode and confirm that the Classic Update option is cleared.
1 In Eclipse, select Help > Install New Software. The Install dialog displays.
2 Click Add. The Add Site dialog box displays.
3 Click Local. The Browse For Folder dialog box displays.
4 Browse to the following folder on the Integrity Client machine:
<Integrity Client installdir>/integrations/IBM/eclipse_3.4/eclipse
where <Integrity Client installdir> is the path to the directory where you installed the
Integrity Client.
Click OK and the selected folder displays in the Location field.
5 In the Name field, enter a name for the integration (for example, Integrity) and click OK.
6 In the Work with list, select the Integrity integration location.
TIP If the Integrity integration location does not automatically appear in the Work with list,
click the link for Available Software Sites and select the site you just added. The Integrity
integration then becomes available for selection in the Work with list.
7 From the list, check Collaboration check box. The check box for Integrity Eclipse
Integration is automatically selected.
8 Click Next. The Install Details dialog box displays with the Integrity integration in the list of
items to be installed.
9 To install the integration, click Finish.
10 Follow the remaining steps of the installation wizard to accept content and the license
agreement.
In the Software Updates dialog box, click Yes to restart the Eclipse workbench and complete the
installation. When Eclipse restarts, the Integrity menu is available for selection.
20
Setting Preferences
Integration specific preferences allow you to select settings for Integrity commands. The Integrity
preferences become the default.
In addition, the File Content and Ignored Resources preferences affect functions in your
workspace related to the integration.
File Content preferences allow you to specify a file type and the type of content in that particular
file (binary or ASCII content).
Ignored Resources preferences allow you to specify resource name patterns that you do not want
to add to Integrity version control. In addition, any file that is marked derived is ignored by
Integrity. To see if a file is marked derived, check the file’s properties.
Click Restore Defaults at any time to clear the changes you made.
NOTE Any modifications to change package preferences will require that you restart your
Eclipse workspace.
Lock file performs the Integrity Lock command, allowing you to edit the file. Enable
this option to implicitly check out a file while editing it. This option is enabled by
default.
NOTE If you are using non-exclusive locks, you can lock a file; however, other users are not
prevented from locking the same file.
Make file writeable performs the Integrity Make Working File Writable command, allowing
you to edit the working file, but not preventing other users from locking the file.
Enable this option to edit a file locked by another user when you have no intention of
checking the file back in. If you intend to check the file in later on, you can lock the file
or associate the modified working file with a change package, and then submit your
changes.
Annotation of Subprojects
The Eclipse integration provides specific annotations for shared subprojects, including
development path names for variant projects and checkpoint revision numbers for build
projects. When changes are made to a project or subproject configuration from outside the
Eclipse integration, those changes are dynamically displayed within the integration.
Only projects and subprojects under source control are annotated. Ordinary folders/
subfolders are not annotated. In addition, to correspond with behavior in the Integrity
Client, children of shared subprojects are not marked as shared.
The integration also provides annotation for the configuration details of shared and
configured subprojects. For variant subprojects, the annotation shows development path
names. For build subprojects, the annotation shows checkpoint revision numbers. Normal
subprojects configured within a build or variant subproject do not show any annotation.
21
To set the type of annotation required, click to select from the following options under
Annotation of Subprojects:
Display configuration at project level only.
Annotate shared subprojects. (Default)
NOTE To avoid displaying more information than may be generally required, the default
setting provides annotation for shared subprojects only. After setting your preference
options, you must restart Eclipse to have the new annotations displayed in the integration.
The Use Change Package option specifies the use of a default change package when
performing Integrity commands that use a change package. This option is enabled by
default.
When this option is enabled, all changes must be submitted using a change package and
you no longer have the option of submitting individual changes using the Submit Changes
command. To ensure the correct behavior, the Use Change Package option should be used
only if the policy for ChangePackagesEnabled is set to true on the Integrity Server.
When performing Integrity commands that require a change package, prompt for an active change
packageprovides for prompting when performing any software configuration
management operation that requires a change package, if there is no active change
package context. You can only enable this option if the Use Change Package option is
enabled. The default setting for this option is false (disabled).
When this property is enabled, you are prompted to choose or create a change package if
active change package tracking is enabled and there is no active change package set. If
you do not choose or create a change package when first prompted, you are re-prompted
when you attempt further file operations that normally require a change package (such as
additional edits or saving the file). You are also prompted when creating or dropping
subprojects, when moving or renaming files, when adding or dropping files, and when
running the Sharing Wizard to add files.
IMPORTANT To return the expected prompt messages when obtaining locks and change
packages, ensure that change package options are configured consistently between the
Integrity Server and Eclipse (that is, if change packages are mandatory in Eclipse, then they
are also configured as mandatory on the Integrity Server). If the change package policies
are not consistent, prompting may not occur as expected when locking and changing
members.
22
3 To add a file type, click Add Extension. To add a file type via a file name, click Add Name. To
delete a file type from the list, click Remove. To modify the file type content, click Change.
4 To save the changes, click Apply.
5 To close the Preferences dialog box, click OK.
To deactivate the Integrity integration with Eclipse IBM platform, you remove the installed
Integrity software plugin.
3 Under the Installed Software tab, highlight Integrity Eclipse Integration and click Uninstall.
The Uninstall dialog box displays with the Integrity integration in the list of items to be
uninstalled.
4 To uninstall the integration, click Finish.
IMPORTANT As part of uninstalling the integration, you should also remove the Integrity
integration update site. To remove the Integrity update site, select Window > Preferences and
under the Install/Update node, choose Available Software Sites. In the Available
Software Sites panel, highlight the Integrity plugin location, and then click Remove.
23
Online and Offline Mode
When you start Eclipse, the Integrity Client automatically attempts to establish a connection with
the Integrity Server. If the client cannot establish a connection with the server, you can still work
in Eclipse.
When working in Eclipse in online mode without a server connection, all Integrity views and
commands that affect the Integrity repository stay enabled. If you perform a command that
requires a server connection, the Integrity Client attempts to reconnect, prompting you to enter
your credentials if required.
If you know that you will not have access to the server for long periods of time, for example, if you
are working remotely without an Internet connection, you can switch to working in offline mode.
In this mode, you can perform any commands that do not require a server connection, such as
editing a file (the file is made writable, but is not locked). Once you switch to online mode, all
disabled Integrity commands and views become active again, allowing you to resynchronize your
changes with the Integrity repository.
NOTE You will be automatically switched to offline mode in the following situations:
You cancel your server connection dialog without entering any credentials.
The Integrity Client becomes unavailable.
NOTE The Integrity trim displays in the bottom-right corner of the workbench by default;
however, you can drag the trim anywhere in the workbench.
24
Integrity information does not display in Properties dialog boxes.
If you delete a subproject, the Sandbox icon is removed from the subproject. While in offline
mode, do not perform resource operations that affect the repository, such as deleting or
renaming resources.
This section discusses the specific details of setting up projects in your integrated workspace,
including placing projects under Integrity version control, and working with Project Sets.
IMPORTANT When you create an Integrity project and Sandbox, the project can reside
anywhere on the Integrity Server, but the Sandbox must reside in the same directory as the
Eclipse project.
Once an Eclipse project is under Integrity version control, you can perform Integrity operations,
such as checking in files and checkpointing projects.
25
8 For the option you selected in step 5, choose one of the available options:
and click Finish. The Specify Project dialog box
Create a new top-level Integrity Source project
displays. In the File name field, specify the name of the project you want to create on the
Integrity Server.
Create a new subproject of an existing Integrity Source project and click Next. Choose the project
to create the subproject against. Optionally, you can select one of the project’s
development path. To create the subproject, click Finish.
NOTE By default, if you create a chain of nested directories, all subdirectories in the
directory are also created as subprojects. If a subdirectory does not include a .pj file,
project.pj is also added to the subproject string.
9 If your project contains files and you are using change packages, you are prompted to specify
a change package to associate with the files. Select an existing change package, or click Create
to create a new change package, then click OK.
If you are not using change packages, proceed to the next step. The Create Archive dialog box
displays.
10 Modify the Create Archive options.
NOTE If Integrity finds an existing archive, the Existing archive detected dialog box displays.
Integrity automatically creates a Sandbox with the project name in your Eclipse workspace.
11 If your project contains files and you associated them with a change package, you must
commit them to the Integrity repository by submitting the change package associated with the
files via the Synchronize view. For more information, see “Team Synchronizing” on page 42.
If your project contains file and you are not using change packages, submit the changes by
selecting Integrity > Submit Changes. For more information, see “Integrity Commands” on
page 36.
NOTE This is the only method of sharing a project that allows you to rename the project in
your workspace. This enables you to import multiple versions of the same project.
1 In your workspace, select File > Import. The Select panel of the Import wizard displays.
2 Under Integrity, select Projects from Integrity.
3 Click Next. The Choose the Integrity project to import panel displays.
4 Select the project to import. All Eclipse projects currently under Integrity version control are
listed.You can use the Filter field to filter the projects by name.
NOTE If an Eclipse project is missing from this list, it means that the project description file
(.project file) has not been put under Integrity version control.
26
5 Specify the configuration of the project to import. If importing a variant project, specify the
Development Path Name where the project is located. If importing a build project, specify the
Revision number or Label applied to the project.
NOTE If you are importing a variant or build configuration of a project that you already
have in your workspace, you must edit the project name in the Project Name field since you
cannot have two projects with the same name in the same workspace.
6 Specify the location to import the project to. This can either be the default workspace location
or a location specified by you.
In either case, the projects are placed in:
selectedLocation/projectName
where projectName is the name of the project as specified in the Project Name field.
NOTE
If there are dependencies between projects, renaming the project will result in compile
errors.
The name in the .project file is not changed when you edit the project name in this
field.
8 Click Finish.
A directory is created for the project in the specified location, a Sandbox is created within that
directory and the Eclipse project files are added.
Importing an Integrity project results in an identical Eclipse project structure and information
within your workspace.
NOTE The Import wizard is only available if the Eclipse integration is connected to an
Integrity Server that uses the database repository option. If the integration is connected to a
server that uses the RCS-style repository option, the Import wizard is not available and an
error message displays when attempting to the run the wizard.
27
Sharing Projects With Project Sets
The Team Support approach also allows for collaboration on projects. In an integrated workspace,
you can share groups of Integrity projects with other users by creating a Project Set or by
exporting groups of projects in your workspace. Other users can then import the Project Set File
(.psf) and the projects contained in the Project Set are automatically created for them.
This includes the creation and population of the necessary Sandboxes, based on the Integrity
projects referenced in the Project Set. Project sets provide a simple method for team members to
share their workspaces.
Key Considerations
The Eclipse project must be under Integrity version control before you create a Project Set.
Once the .psf is created, do not attempt to edit this file unless errors occur when importing
using the file.
You can export subSandboxes with Team Project Sets. Developers can share workspaces in
their entirety. Importing a Team Project Set results in identical Eclipse project structure and
information within the new workspace, and creates corresponding common root Sandboxes.
For example, if a top level Sandbox and a subsandbox are exported using the Team Project Set
feature, they are recreated in the same hierarchy when the Team Project Set is imported.
If a .project file is not under Integrity version control and you attempt to export a Project Set,
an error message displays (the .psf file is created, but is mostly empty). If the .project file is
under Integrity version control, but has been modified since it was last checked in, exporting
the Project Set displays a warning message; however, the .psf file still exports. As long as the
.project file exists, the export should complete successfully.
If an Eclipse project referenced by the Team Project Set does not have its .project file under
version control and you attempt to import the Project Set, an error message displays. A
Sandbox is created for the project in the Integrity Client, even though the project does not exist
in your workspace. To successfully import the Project Set, you must complete the following
steps:
Drop the Sandbox in the Integrity Client
If you still want to import the project, add the .project file as a member in the Integrity
Client
If you do not want to import the project, remove the appropriate entry from the .psf file.
Re-distribute the updated .psf file to all users of the Team Project Set.
Re-import the Project Set
If the .classpath file is not under Integrity version control, any imported Java projects fail to
compile because the build path does not include the JRE System Library. Once the .classpath
file is in the project, subsequent imports include the new file.
28
5 In the File name field, provide the path and file name for the .psf, or click Browse, to browse to
a location.
6 Click Finish. The Project Set is created. The .psf is ready for distribution to other team
members who can import it into their workspaces.
5 If you do not want the Integrity progress dialog box to display while the Sandboxes are being
created, select the Run the import in the background option. This option is useful when importing
a large .psf file that requires many Sandboxes to be created.
6 Click Finish. The Integrity Import Team Project Set Wizard displays, allowing you to create
Sandboxes in a common root location.
7 Click OK to create the Sandboxes in a common root location. By default, the workspace is
specified as the common root location. You may also specify or browse to a location for the
new Sandbox, where it is created automatically in the directory you specified.
Under this root location, directories are created for each project in the project team
set. Sandboxes are then created within those directories and the associated Eclipse project files
are added.
NOTE If you specify an invalid location as the common root, Eclipse deciphers that invalid
entry to find a valid location.
If the description file for a project in the Team Project Set is not under Integrity version control, the
import fails with the following error message:
There is no project description (.project) file in the repository
for <Eclipse project name> referenced by the Team Project Set file. Please use the
Integrity client to drop the Sandbox for <Eclipse project name>, resolve the
inconsistencies with the Team Project Set, and re-try your import.
To resolve inconsistencies with the Team Project Set, do one of the following:
If you still want to import the project, add its .project file as a member in the Integrity Client
If you do not want to import the project, remove the appropriate entry from the .psf file
29
Note the following:
The first time you specify a directory or file as team ignored, an .mksignore file is created in
the root directory of the Eclipse project. Once you submit changes to the project, the created
.mksignore file is added to Integrity version control.
Use the Team shortcut menu to specify directories or files as team ignored.
Once under Integrity version control, the .mksignore file is editable only through Eclipse or
after it is checked out in Integrity.
Ignored files do not display icon decorators or annotations.
With the exception of the Remove from Ignore List command, all Integrity commands are
disabled when you select a team ignored resource.
Glob patterns are unsupported in the .mksignore file.
NOTE You can only select one file at a time to specify as team ignored.
To remove a directory or file from the team ignored list, right click the directory or file and select
Team > Remove from Ignore List. Icon decorators and annotations for the resources appear.
This section discusses the specific details of working with projects in your integrated workspace,
including:
“Integrity Label Decorations” on page 30
“Displaying Integrity Information” on page 32
“Working With Active Change Packages” on page 33
“Managing Items With Integrity Worktray” on page 34
30
The Eclipse Platform integration provides specific annotations for shared subprojects,
including development path names for variant projects and checkpoint revision numbers for
build projects. When changes are made to a project or subproject configuration from outside
the Eclipse integration, those changes are dynamically displayed within the integration. For
detailed information on the available preferences for annotations, see “Annotation of
Subprojects” on page 21.
Icon Decorations
Icon decorations are appended to directory and file icons:
Decorator Function
The Sandbox decorator indicates that the Eclipse project is under Integrity version control or the
directory is a subproject under Integrity version control.
A variant or build project also displays the corresponding development path or revision number.
A file belonging to a project or subproject under Integrity version control displays the revision number,
and, if applicable, status and change package (Synchronize view only), for example, status.java
(1.8 - locked [1:45]).
Packages and directories created or converted to subprojects also display the Sandbox decorator.
The Added Member decorator and the annotation (new) indicates that the file is not one of the
following:
linked resource
team ignored
member of the Integrity repository (If a file is a deferred add, this icon displays. If a file is a pending
add, this icon does not display.)
When a file is committed to the Integrity repository, the revision number annotation displays and the
Added Member icon disappears.
The Dropped Member decorator indicates that the file is a candidate for dropping as a member from
an Integrity project.
NOTE: Dropping the member deletes the file locally; however, it still exists in the Integrity repository.
From the Synchronize view, the Submit Changes command drops the file from the Integrity repository.
31
Decorator Function
The Moved/Renamed Member decorator indicates that the file is a moved and/or renamed member,
and the move and/or rename is not yet committed to the Integrity repository.
The blue lock decorator indicates that another user has a lock on the member revision and you do not
have a lock on the member or working revision.
The green lock decorator indicates that you have a lock on the member revision and no other users
have locks on the same revision.
The red lock decorator indicates that you have a lock on the working or member revision and another
user has an exclusive lock on the member revision.
The Working file changed decorator indicates that the working file has been modified. A directory
containing modified working files also displays this decorator.
The Revision out of sync decorator indicates that the working revision does not match the member
revision.
In the Packages and Navigator views, this decorator indicates the following:
a new revision that does not exist on the current development path. More specifically, the member
revision is the working revision; however, a new revision is available.
an uncommitted update where a user submitted a change in a transactional change package, or a
change package has been submitted, but not reviewed (if change package reviews are enabled).
For example, the user’s working revision is 1.4 but the member revision is 1.3.
Members
The Properties page for a member displays project and Sandbox information, the path and
name of the member, and the revision number. rename?
If the member is locked, the locker, lock type, revision number the member was locked at, and
change package ID associated with the revision also display.
For more detailed information about the member, click Integrity Member Info. The Member
Information dialog box displays.
32
Upgrading and Downgrading Locks
To downgrade an exclusive lock to a non-exclusive lock, in the Properties page for a member click
Downgrade Lock.
To upgrade a non-exclusive lock to an exclusive lock, click Upgrade Lock. The new lock type
displays.
By default, the active change package label displays the change package ID and change package
summary. Text that exceeds the size of the label is truncated; however, you can hover your mouse
over the label to display the change package ID, server and port that the change package resides
on, and change package summary in a tooltip.
If the last change package used in the workspace has been closed, or if the workspace is new,
<no active Change Package> displays in the Integrity trim.
If you disable the Use Change Package preference, all elements in the Integrity trim are disabled
until Eclipse is restarted, at which point the change package components are removed. No
Integrity commands explicitly set the change package.
The Integrity trim displays in the bottom-right corner of the workbench by default; however, you
can drag the trim anywhere in the workbench. The Integrity trim always displays the Integrity
logo and the online/offline mode button (for more information, see “Online and Offline Mode” on
page 24). If the Use Change Package preference is enabled, it also displays the active change package
label, a list allowing you to select the active change package, and a button to create new change
packages.
33
Managing Items With Integrity Worktray
The Integrity Worktray provides support for Integrity items and Implementer change packages
within Eclipse. Although the Integrity integration must be installed for Integrity Worktray to
function, you can configure it to use only Implementer features.
The Integrity Worktray consists of views that display item and change package data. As with any
other Eclipse element, the location and size of each view can be customized.
IMPORTANT Integrity Worktray view data is not dynamically refreshed. To display changes
made since the last time the view was opened (or changed based on a link to another view),
on the view toolbar click .
IMPORTANT If the Integrity Worktray view is open when making changes to the
Integrity Worktray preferences, you must refresh the view (click ) to show the changes.
NOTE To make new queries available in the list, you must refresh the view.
The Integrity Worktray view displays the column set associated with the selected Integrity query,
rather than only displaying a defined, default column set. Therefore, the column set selection is no
longer available under Integrity Worktray Preferences.
34
To change the column set displayed in the Integrity Worktray view, you modify the column set
referenced in the underlying query. For more information on working with queries and column
sets, see the Integrity User Guide.
IMPORTANT Depending on your Integrity Worktray preferences settings, not all commands
or toolbars documented in this section may be displayed.
The following operations are available from the menu in the Integrity Worktray view:
Command Operation
View Item For the selected item, displays its details in the Integrity Client GUI.
Command Operation
Previous Change Package If more than one change package is associated with the selected item, displays
the previous change package by order of change package ID.
Next Change Package If more than one change package is associated with the selected items, displays
the next change package by order of change package ID.
Open in Integrity Displays the change package details in the Integrity Client GUI.
35
Integrity Commands
To provide a more seamless Integrity experience within Eclipse, basic Integrity commands, such
as adding members and checking out files occur implicitly in the Integrity repository when you
perform the equivalent Eclipse commands. File status is displayed immediately to other Eclipse
users working in the project. For more information on performing operations, refer to the
following sections:
“Adding Members to an Integrity Project” on page 36
“Dropping Members From an Integrity Project” on page 36
“Checking Out Members” on page 37
“Checking In Members” on page 37
To access advanced Integrity version control functionality, such as submitting changes or
checkpointing a project, select an Eclipse project or one or more files, and then select the
Integrity menu, or right click the selected item and then choose the Team menu. Note that not all
commands are available in both menus, and that the available commands depend on your
selection. For example, the View Member Differences command is available only when you select a
file under Integrity version control. The Eclipse status bar indicates when an Integrity command is
complete. For a list of Integrity commands, see “Advanced Integrity Commands” on page 37.
NOTE The integration also adds members if you refresh Eclipse and it discovers one or
more new files that are unknown to the Integrity repository. For example, if you copy a file
to your Sandbox controlled in Eclipse, and then refresh Eclipse, the file is added to the
Integrity project.
The files are added as members and decorators display immediately for each member. If
change packages are enabled and an active change package exists, the new files are associated
with the active change package and the files can be committed to the Integrity repository.
NOTE If you are using change packages and have not set an active change package when a
file is created, use the Move to Change Package command to associate the file with a change
package.
2 Commit the changes to the Integrity repository by doing one of the following:
If you are using change packages, submit the change package associated with the new
files. For more information, see “Team Synchronizing” on page 42.
If you are not using change packages, select the new files, and then select Integrity > Submit
Changes. For more information, see “Advanced Integrity Commands” on page 37.
36
3 Commit the changes to the Integrity repository by doing one of the following:
If you are using change packages, submit the change package associated with the deleted
files. For more information, see “Team Synchronizing” on page 42.
If you are using change packages and have not set an active change package when a file is
deleted, use the Move to Change Package command to associate the file with a change
package.
If you are not using change packages, select the files to delete in the Synchronize view,
and then select Integrity > Submit Changes. For more information, see “Advanced Integrity
Commands” on page 37.
NOTE If the Lock file option is not selected in the Integrity options, the working file is made
writable when you edit the file and you must manually lock the file later, or associate the
modified working file with a change package. For more information, see “Setting
Preferences” on page 21.
Checking In Members
Move to Change Package Moves the selected files to an existing or new change package. The change
package containing the associated changes can then be submitted to the Integrity
repository.
From the list, select a change package or click Create Change Package.
The status bar indicates when the command is complete.
Note:
You cannot move a rename or move change package entry out of a change
package. You can only move these type of entries to another change package.
You cannot move a rename or move operation to a change package if it is not
already associated with a change package.
37
Integrity Command Function
Submit Changes Equivalent to the Integrity Submit command. Submits uncommitted changes on
individual files.
The status bar indicates when the command is complete.
If the selection is from the Packages view, a submit does not include dropped files;
however, a submit includes dropped files displayed in the Synchronize view.
IMPORTANT: The Submit Changes command is not available if you have selected the
option for Use active Change Package. For more information, see “Use Change
Package” on page 22.
Resynchronize by Change Equivalent to the Integrity Resynchronize Member by Change Package command.
Package Processes the change packages associated with the member you are
resynchronizing, and brings the changes from the project to your Sandbox.
Depending on the preferences you have set for the Resynchronize command, the
Confirm Overwrite Working File dialog box displays.
View Member History Equivalent to the Integrity View Member History command.
Displays the revision history of the selected file.
The Member History view displays.
Create Change Package Equivalent to the Integrity Create Change Package command.
Creates a change package.
The Create Change Package dialog box displays.
View Active Change Package Equivalent to the Integrity View Change Package command.
Displays the active change package associated with the selected file. If there is no
active change package, this command is disabled.
The Change Package view displays.
For more information on active change packages, see “Working With Active Change
Packages” on page 33.
38
Integrity Command Function
Submit Active Change Package The Submit Active Change Package command allows you to submit an active
change package directly from the Integrity menu within Eclipse.
The Submit Active Change Package command operates in the same way as the
Submit Change Package command on the Integrity Client, and follows most client
preferences as set for that command.
Convert to Subproject Converts an empty directory or a directory containing files that are not under
Integrity version control to a subproject. If the directory contains files, they must be
added to Integrity version control after the subproject is created.
This command is useful for defining a directory structure for a build project.
Merge child Development Path Equivalent to the Integrity Merge Child Development Path command.
Merges a development path into its parent development path. The parent
development path may be a mainline, or it may be a development path itself. The
merge destination must be the parent of the child being merged into it.The
command creates a propagation change package containing the changes
necessary to perform the development path merge. For more information, see the
Integrity User Guide.
39
Note the following:
You can make the Integrity menu always available from the perspective you have open by
selecting Window > Customize Perspective. In the Commands panel, enable Integrity Source Menu.
You can use Eclipse’s key binding functionality to assign key sequences to commands in the
Integrity and Team menus. Note that Integrity commands are only visible when Include unbound
commands is enabled on the Preference > Keys page. For more information, refer to the Eclipse
documentation.
Although Eclipse supports linked resources, known as out-of-tree members in Integrity, they
cannot be placed under Integrity version control. As a result, Integrity commands are disabled
and decorators do not appear when you select linked resources.
If you select one or more files and then perform a revert or resynchronize, only the selected
files are reverted or resynchronized. If you select one or more containers (Eclipse projects,
directories, packages) and then perform a revert or resynchronize, the integration examines
the first Sandbox or subsandbox of each container and performs a revert or resynchronize on
the entire Sandbox or subsandbox. If you select an Eclipse container that maps to a directory
in Integrity, the Sandbox containing the directory is resynchronized or reverted.
Refactoring
The Eclipse integration allows you to refactor your source code and preview the changes before
you commit them to the Integrity repository. Refactoring activities (adds, drops, moves, and
renames) are handled as member operations not yet committed to the Integrity repository, and are
recorded in change packages that you can either submit or discard.
Submitting a change package commits your changes to the Integrity repository. This is done by
clicking one of the Submit buttons in the Synchronize view (for more information, see “Team
Synchronizing” on page 42), or the Submit Changes/Submit Change Package commands from the
Integrity menu (for more information, see “Advanced Integrity Commands” on page 37).
To discard your changes, discard the change package or change package entry using the
Integrity > Revert command, or undo the change through Eclipse. For example, if you want to undo
a move operation, move the file back to its original location.
Note the following:
Where possible, use Eclipse’s Undo command to undo changes. If it is not possible to use the
Undo command, use the Integrity Revert command.
If you create an Integrity configuration management project in the Integrity Client and then
import it into Eclipse, renaming a package in the project modifies the subproject organization
in Integrity. More specifically, the directory is created on the file system (in the Sandbox
directory), and the files are moved via move member commands to make the changes happen
in Integrity.
Renaming an Eclipse project under Integrity version control is not supported.
When you rename a package that corresponds to a subproject in Eclipse, the operation is
recorded as move operations for the members contained in that package. When these changes
are submitted, the old subproject folder is not removed until the corresponding subproject is
dropped. To drop a subproject, the Drop Subproject operation must be submitted in a separate
change package.
If you rename a folder in the context of the Eclipse workspace, the old folder is removed as a
result of submitting the changes to the files in that folder.
40
If you delete a project from your workspace, the associated Sandbox is automatically dropped
if the preference for Drop Integrity Sandbox when Eclipse project is deleted is enabled. For more
information, see “Setting Preferences” on page 21.
When you use the Eclipse Edit > Delete command (or press the Delete key) on a directory, the
integration drops files in the directory. To remove the entire subproject, use the Integrity > Drop
Subproject command.
Comparing Revisions
The integration with Integrity supports functionality for comparing and merging revisions. When
conflicts are detected during a synchronization, you are automatically prompted to resolve those
conflicts by differencing the files. The integration with Integrity supports both two and three-way
differencing. For three-way differencing, you are prompted to perform a merge on the branch and
then a second merge against the selected project root.
After synchronizing a project, you can navigate all revisions that show differences using Go to Next
Difference and Go to Previous Difference in the Synchronize view. All differences in the file are
visited before opening the next file in the view.
Differencing is supported for both plain text, binary files, and models, provided the required tools
are available on your system. The differencing tool presented is based on the tools you use in your
IDE environment and on the file type, for example, UML, JAVA, or TEXT.
TIP To compare differences between the working file and member revision, select the file in
the Navigator or Packages view, then select Integrity > Member Differences. If differences
exist, the Integrity Visual Difference window displays.
History View
The History view displays the Integrity revision history of a file.
TIP You can also view a file’s revision history by selecting the file, then selecting Integrity >
View Member History. The Member History view displays.
To display the History view, select Window > Show View > Other. The Show View dialog box displays.
Open the Team directory, and then select History.
The History view displays the file name, revision number, modification date, author, change
package, the name of any user with a locked revision and corresponding change package, and
state information. A * beside a revision number indicates the member revision, and bold indicates
the working revision.
To refresh the History view, click .
The button links the History view with the Editor view such that when a file is opened in the
Editor view, the corresponding Integrity revision history displays. Toggle the button to remove
the linking and display the local history.
To pin the History view, click .
41
Team Synchronizing
Synchronize Integrity allows you to work with the Synchronize Wizard and display the state of your
workspace as it relates to the Integrity project.
Pin Current Synchronization prevents dynamic updates of the view, allowing you to hold your
workspace synchronization.
NOTE: You cannot pin a Synchronize view that is filtered on the active change package; however, you
can on an open change package or a set of resources.
Go to Next Difference navigates through the project hierarchy to the next revision containing
differences. Automatically launches the available differencing tool.
Go to Previous Difference navigates through the project hierarchy to the previous revision containing
differences. Automatically launches the available differencing tool.
42
Button Icons Function
Incoming Mode filters the view to show only those working files with associated incoming changes or
incoming add operations.
Outgoing Mode filters the view to show only those working files with associated outgoing changes or
outgoing add operations.
Incoming/Outgoing Mode filters the view to show all working files with incoming and outgoing
changes.
Conflicts Mode filters the view to show only those working files with incoming and outgoing changes
containing conflicts.
Submit this Change Package submits the selected or active change package containing your changes
to the Integrity repository. This button is only visible when you filter the Synchronize view by change
packages.
Submit All Outgoing Changes submits the outgoing changes to the Integrity repository. This button is
only visible when you are not using active change package tracking and you filter the Synchronize
view by resources.
Resync all incoming changes resynchronizes your workspace with all incoming changes. This button
is only visible when you filter the Synchronize view by resources.
Decorator Function
The Incoming changes decorator indicates that there are incoming changes available for the member.
The Incoming add decorator indicates the member was added to the Eclipse project under Integrity
version control, but does not exist in your workspace.
The Incoming drop decorator indicates that the member was dropped from the Eclipse project under
Integrity version control; however, the file still exists in your workspace.
The Outgoing changes decorator indicates that there are outgoing changes available for the member.
The Outgoing add decorator indicates that the member was added to your workspace, but is not
currently a member of the Eclipse project under Integrity version control.
The Outgoing drop decorator indicates that the member was deleted from your workspace, but has
not been dropped from the Eclipse project under Integrity version control.
The Conflict changes decorator indicates that there are conflicting changes between incoming and
outgoing changes for a member. This can include changes to an earlier revision of the member.
The Conflicting drop decorator indicates that you modified a member that was dropped from the
Eclipse project.
43
To perform a Team Synchronization
1 From your Eclipse workspace, open the Team Synchronizing perspective by selecting Window >
Open Perspective > Other and choosing Team Synchronizing from the list.
TIP You can also open the Synchronize view by selecting Window > Show View > Other > Team
> Synchronize. When you finish running the wizard and Eclipse prompts you to switch
perspectives, click No.
TIP The F5 function always refreshes the view and operations within Eclipse trigger an
update to the Team Synchronizing perspective.
Click Next, then select specific resources to synchronize, or select a scope to automatically
select a group of resources:
Workspace synchronizes all available resources in the workspace.
Selected Resources synchronizes the resources you select in the Available resources to
Synchronize list.
Working Set synchronizes the resources in the working sets you select from the Select
Working Sets dialog box. To choose a working set, click Choose.
NOTE
The Synchronize view filters on the entire workspace if you select the following options:
Selected Resources with no projects selected in the Available resources to Synchronize list.
Working Set with one of the following options selected in the Select Working Sets dialog
box: Window Working Set, No Working Set, or Selected Working Set with no projects selected
in the list.
6 To populate the Synchronize view, click Finish. If there are changes, they display in the
Synchronize view. If there are no changes, the Synchronize view is empty.
If you filtered the Synchronize view by specific resources, the Synchronize view appears
similar to the following:
44
If you filtered the Synchronize view by change package, the Synchronize view appears
(similar to the following):
7 To review the changes in a member in the Integrity view, right click the member and choose
View Member Differences. Visual Differences launches, displaying the differences between the
working file and the member revision. To launch the Eclipse Compare editor, use the Open in
Compare Editor command or double click the Synchronize view entry.
8 If you filtered the Synchronize view by specific resources, do one of the following:
To submit all outgoing changes when not using a change package, click .
To submit all outgoing changes when using a change package, click .
To resync all incoming changes, click .
To resynchronize a working file with its corresponding change package, select the
incoming member(s), and then right click and select Resynchronize by Change Package.
If you filtered the Synchronize view by change package, submit the change package by
clicking .
45
Best Practices
This section describes best practices for using the Eclipse integration. It also points out efficiencies
that can be gained by using the integration in a certain way, as well as identifying any risks,
constraints, or other limits within the integration or within a particular implementation of the
integration.
If you are sharing an Eclipse project containing a large number of subdirectories and files, do
one of the following:
Place the project under version control in the Integrity Client, and then share the project in
Eclipse.
Disable the Add all files when creating the new Integrity Source project option when placing an
Eclipse project under Integrity version control. After the Integrity project and Sandbox are
created, add the project files in small batches using a separate change package for each
batch.
For ease of distribution, control, and versioning, create a specific Integrity project and
Sandbox for .psf files. Users can then access the required .psf file from a central location.
Mark .class files as team ignored. For more information, see “To set Ignored Resources
preferences” on page 23.
To optimize the resynchronization of project resources and submission of changes, the
integration is designed to use change packages and the Synchronize view. When you begin
using the integration, open the Synchronize view and filter it by the resources you will be
working on.
A change package is a container for distinct tasks, not a generic container for all tasks
performed during a project. A change package containing too many entries may impact the
integration’s performance. Before you perform a task that requires a change package, create a
change package and enable it as the active change package.
Resynchronize project resources frequently and incrementally. Resynchronizing a large
number of resources in a single operation may take a long time.
Allocate memory to Eclipse and the Integrity Client according to the size of your Eclipse
projects. Use the following as a guideline to help you determine memory allocations:
50 projects with 100,000 members
46
200 projects with 400,000 members
Set the Integrity Client maximum heap size to the highest possible number for your
platform (most commonly this is 1.5 GB)
Set the Integrity Client cache size to 400 MB
Allocate at least 2 GB of memory to Eclipse. Use the 64 bit version of Eclipse if you
need more than 2 GB.
NOTE
To set the Integrity Client cache size, edit the si.Cache.default.size setting in:
<installdir>/IntegrityClientSite.rc
where <installdir> is the path to the directory where you installed the Integrity Client.
To improve performance with large projects, use working sets to display only necessary
resources in navigation views. For more information, see the Eclipse documentation.
The Eclipse integration is tightly coupled with the Integrity Client. When using Eclipse, focus
issues may occur if you open the Integrity Client GUI. If this occurs, close the Integrity Client
interface but do not shut down the Integrity Client process. If Eclipse shuts down, shut down
the Integrity Client, and then restart the client.
Working in offline mode for long periods of time is not recommended. When you switch to
online mode after an extended period of time, performance issues may arise from rebuilding
the cache.
To ensure the expected prompts when obtaining locks and change packages, make sure that
change package options are consistently configured between the Integrity Server and Eclipse.
If change packages are mandatory on the Integrity Server, set the integration option for Use
active Change Package and enable prompting for the active change package. If change package
policies are not consistent, changes you make to the files in your workspace may not be
recorded as expected in Integrity. For more information on the available preferences, see
“Setting Preferences” on page 21.
Limitations
After switching from offline to online mode, you cannot submit changes in the Synchronize
view while the Integrity status cache refreshes. Before you submit changes, check the status of
the Eclipse progress bar and ensure there is no Integrity command activity.
When a subproject is dropped in another user’s Sandbox, resynchronizing the dropped
subproject’s members in the Synchronize view displays an error message. To avoid this,
resynchronize the dropped subproject in the Package Explorer.
When filtered by the active change package, the Synchronize view updates if you change the
active change package from <none> to a change package, or from one change package to
another change package; however, the view does not update when you change the active
change package from a change package to <none>. To display changes not associated with a
change package in the Synchronize view, run the Synchronize wizard, filtering by resources.
Existing locks on dropped members are not removed. To resolve this, open the Locks view in
the Integrity Client GUI and unlock the members.
Performing the View Sandbox command on a dropped subproject incorrectly displays an error
message.
47
The initial attempt to rename a subproject after adding a member to the subproject displays
the error message “the Resource is out of sync with the filesystem.” Refreshing the
subproject, then performing the rename command successfully completes the operation.
Attempts to revert deferred added members from the Synchronize view do not successfully
remove them from the Synchronize or Packages views unless you also delete the file.
Reverting the files from the Integrity Client successfully removes them from both views.
To avoid potential focus problems when using the Integrity Sharing Wizard, close the
Integrity Client if it is open.
To hide files, such as the Integrity project registry file (project.pj), certain resource filters are
enabled by default in Eclipse. By default, these filters apply to the Packages and Navigator
views.
There are a number of conditions that may cause Eclipse to identify new files in a project,
resulting in deferred add operations for non-member files that have not been modified by the
user within the Eclipse IDE. For example, in cases where automatic refresh is enabled in
Eclipse and files are generated by build scripts, the generated files are identified by Integrity
as new files to be added to the project.
If you routinely encounter this situation and do not want Integrity to add such generated files
to your projects, you can add the file type to the Eclipse Ignored Resources list. Under Window >
Preferences > Team > Ignored Resources, add the pattern for the file type you want the integration
to ignore.
48
C HAPTER F IVE
IBM Rational Rose 5
This chapter provides information on using the Integrity integration with IBM Rational Rose
Enterprise Edition 2003, version 6.13. The chapter includes information on the following topics:
“Configuring the Rational Rose Integration” on page 50
“Using the Rational Rose Integration” on page 50
“Creating an Integrity Project” on page 51
“Creating a Sandbox” on page 51
“Adding Members to an Integrity Project” on page 51
“Checking Out Members” on page 52
“Checking In Members” on page 52
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
49
Configuring the Rational Rose Integration
The Integrity Client includes the File > Integrations menu action for enabling and disabling the
integration with IBM Rational Rose. You can select from a list of available integrations and enable
or disable them, as required to work with your preferred application. For more information, see
“Configuring Integrations” on page 3.
Command Function
Add to Version Control Equivalent to the Integrity New Project and Add Members commands.
Brings the current Rational Rose project or selected file(s) under version control.
The Create Archive dialog box displays.
Remove from Version Control Equivalent to the Integrity Drop Members command.
Drops the selected file(s) from the Integrity project.
The Drop Member dialog box displays.
Start Version Control Explorer Equivalent to launching the graphical user interface or the Integrity Open Sandbox
command.
Displays a Sandbox view.
The Rational Rose Browser panel is enhanced with version control features and indicators. For
example, a red check mark displays beside the project to indicate that it is under version control.
50
Creating an Integrity Project
To create an Integrity project in Rational Rose
1 In Rational Rose, select the project you want to put under version control.
2 Select Tools > Version Control > Add to Version Control. The Add to or Associate with MKS Integration
dialog box displays, showing the project file that will be placed under version control.
3 Select one or more files to add to the Integrity project, and click OK.
4 At the following prompt click Yes to browse for a project. The Add to or Associate with MKS
Integrationdialog box displays again.
5 Click OK.
6 At the prompt save your project files. The Specify the Project to Create dialog box displays.
7 Create a project as described in the Integrity User Guide. The Create Sandbox Wizard displays.
8 Create a Sandbox as described in the Integrity User Guide. The Create Archive dialog box
displays.
9 Modify the Create Archive options as necessary as described in the Integrity User Guide. The
Check Out dialog box displays.
Creating a Sandbox
In Integrity, create a Sandbox as described in the Integrity User Guide.
51
5 Click OK.
6 At the prompt save your project files. The Create Archive dialog box displays.
7 Modify the Create Archive options as necessary as described in the Integrity User Guide.
8 Click OK.
Checking In Members
To check in members in Rational Rose
1 In Rational Rose, select one or more files to check in.
2 Select Tools > Version Control > Check In. A list displays, showing all files that will be checked in.
3 Click OK. The Check In dialog box displays.
4 Check in each member as described in the Integrity User Guide.
NOTE When using the Rational Rose integration, you are not prompted to confirm the
check-in of an unmodified file.
52
P ART III
Microsoft
53
CHAPTER SIX
Microsoft Visual Studio (SDK) 6
The Integrity integration with Microsoft® Visual Studio® 2005/2008/2010/2012 (SDK) allows
users to access Integrity commands through Visual Studio, providing a seamless development
and configuration management experience.
This chapter discusses the following topics:
“Before You Start” on page 55
“Setting Up and Configuring the Integration” on page 56
“Online and Offline Mode” on page 60
“Working With Active Change Packages” on page 61
“Integrity Glyphs in Visual Studio” on page 62
“Managing Work In Progress” on page 63
“Managing Assigned Work” on page 66
“Placing Visual Studio Solutions Under Integrity Source Control” on page 67
“Working With Visual Studio Files” on page 77
“Best Practices” on page 81
“Limitations” on page 83
“Troubleshooting” on page 84
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
54
Before You Start
Before you set up or use the integration, note the following:
This guide assumes you know how to use Microsoft Visual Studio and Integrity. For more
information about using a product, refer to the appropriate documentation.
For suggested best practices on using the Visual Studio integration, you should read “Best
Practices” on page 81.
The integration works with the following:
Windows 7, Windows Vista, Windows XP, Windows Server 2008/2003
Microsoft Visual Studio 2005, 2008, 2010, and 2012
Integrity 10
The Visual Studio integration is designed to use change packages for submitting source code
changes to the Integrity repository. Ensure that change packages are enabled on the Integrity
Server.
To use change packages, the administrator must also enable Integrity for startup on the
Integrity Server (mksis.startup.im=true). If change packages are mandatory, Integrity for
workflows and documents functionality must be enabled (that is, the policy for
IntegrityManagerEnabled must be set to true).
For more information on setting properties and policies on the Integrity Server, see the
Integrity Server Installation and Configuration Guide.
The following Integrity Server configurations are supported per Visual Studio solution:
one Integrity Server configured for workflows and documents, and for configuration
management
one Integrity Server configured for Integrity configuration management
one Integrity Server configured for configuration management and one Integrity Server
configured for workflows and documents
Ensure that the Integrity Client path is set correctly for the PATH environment variable (that is,
the Integrity Client’s <installdir>/bin path appears first). Failure to set the path correctly
displays a Package Load Failure error in Visual Studio. In addition, do not disable packages
in Visual Studio. Disabling packages prevents you from selecting Integrity as the source
control provider.
If you are using an older version of the Visual Studio integration, disable the integration in
Visual Studio and the Integrity Client before you upgrade to the new Visual Studio
integration. To enable the new integration, see “Setting Up and Configuring the Integration”
on page 56.
If you have a Visual Studio solution that was placed under Integrity source control using the
previous SCC-based Visual Studio integration, you can migrate it for use with this version of
the integration. For more information, see “Migrating a Visual Studio Solution from the MKS
SCC VS Integration” on page 73.
If you are upgrading from MKS Integrity 2007 SP 4 or earlier, this release of the Visual Studio
integration does not use the MKS Worktray and MKS Change Package view found in
previous releases of the Visual Studio integration. To improve management of work in
progress and assigned work, this release uses Integrity Work In Progress and Integrity Items
views. To use the Integrity Items view, one of your Integrity Servers must be configured for
55
workflows and documents. For more information, see “Managing Work In Progress” on
page 63 and “Managing Assigned Work” on page 66.
When using the Integrity integration with Microsoft Visual Studio, ensure that the necessary
Access Control List (ACL) permissions are granted to users. For example, users adding Visual
Studio solutions to Integrity source control require the following permissions:
CreateProject
ModifyProjectAttribute
CreateSubproject
For more information on configuring ACLs for Integrity, see the Integrity Server Installation and
Configuration Guide.
If you are working in a single Integrity Server environment, you should disable prompts for
server information and credentials in the Integrity Client. This provides a more seamless
experience with the Visual Studio integration.
If you are working in a multi-server environment, you should disable prompting for
credentials, but enabling server prompting so that you can connect to the appropriate
Integrity Server. If you do not disable prompting, Visual Studio displays prompts for server
information and credentials when you perform Integrity commands. Failure to disable
prompting for credentials may display errors when attempting to share a Visual Studio
solution. To disable prompting in the Integrity Client, see the Integrity Getting Started Guide.
To avoid potential focus problems when using Visual Studio, close the Integrity Client
window, but do not shut down the client.
Supported versions of Visual Studio that are currently installed are registered for use with
Integrity when you run the Visual Studio integration installer.
NOTE
If you install another supported version of Visual Studio after you install the integration,
you can register the version of Visual Studio by doing the following:
From the Control Panel > Add or Remove Programs list, select Integrity Integration for
Microsoft Visual Studio and click the link for Click here for support information.
Click Repair.
The Visual Studio integration registers the version of Visual Studio you installed.
56
If you are currently using the Visual Studio integration available in Integrity Client 2007 SP5
or 2009, disable the integration in the Integrity Client.
To remove the Visual Studio integration on Windows Vista Enterprise, you must run the
Integrity Client as an administrator, and then disable the integration.
4 Click Next.
5 To install the integration click Install.
6 To exit the Setup Wizard, click Finish.
Visual Studio supports various source control providers. You must specify Integrity as the source
control provider.
1 In Visual Studio, select Tools > Options. The Options dialog box displays.
2 Select Source Control > Plug-in Selection.
3 From the Current source control plug-in list, select Integrity.
4 Click OK. The Integrity toolbar, Integrity Items, and Integrity Work In Progress views display.
If desired, dock the views to a location of your choice in Visual Studio.
For more information on the Integrity toolbar, see “Working With Active Change Packages”
on page 61.
For more information on using the Integrity Items view, see “Managing Work In Progress” on
page 63.
For more information on using the Integrity Work In Progress view, see “Managing Assigned
Work” on page 66.
The Integrity toolbar displays connection status, a change package list, and toolbar buttons for
managing changes to Visual Studio solutions and managing change packages. By default, the
Integrity toolbar appears docked when you select Integrity as the source control provider.
57
To toggle the Integrity toolbar
1 In Visual Studio, select Tools > Customize. The Customize dialog box displays.
2 From the Toolbars tab, toggle Source Control - Integrity. The Integrity toolbar disappears or
displays in Visual Studio.
3 Click Close.
Once an open solution is under Integrity source control (see “Sharing a Visual Studio
Solution” on page 67), the toolbar buttons in the Integrity toolbar become active.
For more information on connection status, see “Online and Offline Mode” on page 60.
For more information on managing change packages, see “Working With Active Change
Packages” on page 61.
For more information on managing changes to Visual Studio solutions, see “Resynchronizing
a Visual Studio Solution” on page 76 and “Reverting a Visual Studio Solution” on page 76.
Setting Preferences
Once you enable the Integrity plug-in, you can configure source control preferences.
A keyword is a placeholder that can be inserted into text-based working files. This placeholder is a
special variable (for example, $Date$, $Author$, $State$) used to represent textual information in
a working file. Keywords can be expanded (that is, replaced with their literal values) when a
revision is checked out.
To enable keywords, set keyword preferences for the appropriate commands, such as check out
and check in, in the Integrity Client preferences. For more information, see the Integrity User Guide.
To use a keyword, simply include it in a working file, surrounded by dollar signs (for example,
$Date$) and check the file back into its archive.
NOTE If you add keywords to solution and project files, Integrity does not expand them on
check in.
58
Configuring the Location of VS Solutions and Projects in the Integrity
Repository
NOTE This section is intended for Integrity administrators only. It is an optional feature
related to sharing Visual Studio solutions and projects.
By default, sharing a Visual Studio solution allows you to choose where in the Integrity repository
you want to place a Visual Studio solution and Visual Studio project as a top-level Integrity
project and Integrity subproject. In the Integrity repository, the Visual Studio project is placed in
the Visual Studio solution’s Integrity project subtree. The solution and project are known as being
“in-tree” in the repository structure.
As an alternative repository configuration, Integrity administrators can set an Integrity policy that
automatically defines for users where top-level Integrity projects and Integrity subprojects are
placed in the Integrity repository. If set, users do not choose the location where top-level Integrity
projects and Integrity subprojects are placed in the Integrity repository when sharing a Visual
Studio solution.
Note the following:
This policy takes effect immediately; however, it only affects new Visual Studio solutions and
projects. Existing shared solutions and projects are not affected.
Once you add the policy lines do not remove them. To enable or disable the policy, change the
values of integration.catalog.vssolution.enabled and
integration.catalog.vsproject.enabled to true or false.
To define where top-level Integrity projects and Integrity subprojects are placed in the
Integrity repository
1 In the Integrity Administration Client, open the Configuration Management node and select
Policies.
2 In the right-hand pane, select Global Policies, and then select Policies > Edit. The Global Policies
dialog box displays.
3 Click the Other tab.
4 To specify where top-level Integrity projects for Visual Studio solutions are placed, add the
following lines:
integration.catalog.vssolution=<configuration path>
integration.catalog.vssolution.enabled=<true/false>
To specify where Integrity subprojects for Visual Studio projects are placed, add the following
lines:
integration.catalog.vsproject=<configuration path>
integration.catalog.vsproject.enabled=<true/false>
59
where
<configuration path> specifies the configuration path of the top-level Integrity project or
Integrity subproject, for example, #p=/abcFinancialToolkitApp/
abcFinancialToolkitAppsln.pj.
When you open Visual Studio and no solution is open, the integration cannot determine the
connection status, and displays Not Shared in the Integrity toolbar. To establish a connection with
the client and server, open a Visual Studio solution under Integrity source control or place a
solution under Integrity source control. While attempting to establish a connection, Visual Studio
displays Connecting.
When the integration connects to the Integrity Client and the client establishes a connection with
the Integrity Server, the integration switches to Online mode and all Integrity commands and
views are available.
If the Integrity Client cannot establish a connection with the Integrity Server or the previously
established connection is lost, the integration switches to Offline mode. In offline mode, you can
continue working in Visual Studio, performing only the Integrity commands that do not require a
connection to the Integrity Server, such as adding or editing files. Any changes affecting Sandbox
members are done without an active change package, requiring you to move the changes to an
active change package when you switch to online mode. With the exception of the connection
status indicator, all Integrity views and commands that affect the Integrity repository are disabled.
Most notably, you cannot rename files or directories, and the Solution Explorer only updates glyphs
for basic local operations, such as adding, deleting, and editing files.
If you are working in online mode and the server suddenly goes down or there is a poor network
connection, the integration automatically switches to Offline mode, allowing you to continue
working in Visual Studio. When the server connection is re-established, the integration
automatically switches to Online mode and all Integrity commands and views automatically
become active again, allowing you to resynchronize your changes with the Integrity repository.
NOTE Switching from offline to online mode refreshes the Solution Explorer, resynchronizing
all resources in the Visual Studio solution and retrieving the latest glyphs. Depending on
how many files or Visual Studio projects are visible in the solution, this process may take a
long time; however, it occurs in the background and does not prevent you from working in
Visual Studio.
You can also manually switch the integration to offline mode. Working in offline mode is
recommended when you know that you do not have access to the server for long periods of time.
For example, if you are working remotely without an Internet connection or if you intentionally
disconnect your machine from the network by clicking Online and then Go Offline, you work in
60
offline mode, allowing you to work on local files (edits and adds). When you reconnect to the
network by clicking Offline and then Go Online, move your offline changes to a change package for
submission to the Integrity repository.
By default, the active change package label displays the change package ID, change package
summary, and (Active), for example, 1:6 print function broken in Financial Toolkit
(Active). If no active change package exists, No active change package displays. Text that
exceeds the size of the label is truncated; however, you can hover your mouse over the label (if the
change package is the active change package, Currently Active Change Package displays in a
tooltip). If you are connected to more than one server, the server and port that the change package
resides on also appears.
To select a different active change package, click the drop-down arrow button next to the change
package list and select a change package or No active change package.
Note the following about using change packages with the Visual Studio integration:
A change package is a container for distinct tasks, not a generic container for all tasks
performed during a project. A change package containing too many entries may impact the
integration’s performance. Before you perform a task that requires a change package, create a
change package (this enables it as the active change package).
An active change package cannot be used for multiple solutions.
The active change package must be set in Visual Studio. If you set the active change package
in the Integrity Client, the integration does not reflect the change.
You can move added or modified change package entries from one change package to
another. You cannot move renamed or moved change package entries from one change
package to another.
61
Integrity Glyphs in Visual Studio
The Visual Studio Solution Explorer and Integrity Work In Progress view are enhanced with
Integrity glyphs to indicate Integrity source control status. For example, a flag glyph displays
beside a Visual Studio solution or project if it is under Integrity source control, and a pencil glyph
displays beside a file if it is checked out by you with a lock.
For files edited in Visual Studio, the integration automatically updates glyphs in the Solution
Explorer.
The following Integrity glyphs display in the Solution Explorer and/or Integrity Work In Progress
view:
Glyph Definition
Visual Studio Solution, Visual Studio project, or Web Application Project under Integrity source control.
Note: This glyph does not display for Web sites under Integrity source control.
Incoming change.
62
Glyph Definition
63
Revision numbers for files display in brackets, for example, Application.Designer.vb (1.1).
You can view more detailed information about a file by using the View Member Properties command.
For more information, see “Advanced Integrity Commands” on page 80.
Note the following:
After you branch a solution, the revision number that displays beside the solution node is the
revision number of the solution file.
Double-clicking a file in the Integrity Work In Progress view opens it for editing.
File Status
The Integrity Work In Progress view only displays the status represented by working files. This
includes glyphs for added, dropped, moved, renamed, and changed files. For more information,
see “Integrity Glyphs in Visual Studio” on page 62.
Incoming Changes
To notify you when one or more files need to be resynchronized, putting the latest revision in your
Sandbox, the Integrity Work In Progress view displays glyphs for conflicts (incoming and
outgoing changes), and remote drops by other users. For more information, see “Resynchronizing
a Visual Studio Solution” on page 76.
Command Operation
Set Active Change Package ( ) Sets the selected change package as the active change package.
(Active) appears after the change package name.
Create Change Package ( ) Creates a change package, making it the active change package.
The Create Change Package dialog box displays.
View Change Package ( ) Displays the change package for the currently selected change package.
If there is no selected change package selected, this command is
disabled.
The Change Package view displays.
Submit Change Package ( ) Submits the selected change package, committing the associated
changes (files) to the Integrity repository.
By default, confirmation of a successful submission does not appear. To
display a confirmation message, enable the Show Successful Submit
option for the Submit Change Package command in the Integrity Client.
64
Command Operation
View Integrity Item ( ) Displays the Integrity item associated with the selected change package.
The View Item Details view displays.
Discard Change Package ( ) Discards the selected change package and its associated entries.
NOTE Visual Studio automatically makes changes to files based on events in Visual Studio,
for example, changing the development server port number in Web application project
files, and adding debug information to Web site configuration files. If a Visual Studio
project is shared and an associated change package is closed before Visual Studio makes
changes, those changes appear under Unassociated Changes in the Integrity Work In
Progress view.
65
When your changes are complete, you can move the unassociated changes to a change package for
submission to the Integrity repository.
NOTE If you are currently connected to your default Integrity Server, you are not prompted
to establish a connection. If you are not connected to your default Integrity Server, you
may be prompted to choose an existing connection (if you are connected to another server),
or create a new connection.
The Integrity Items view displays items based on the selected query. By default, no query is
selected in the Query list. Query criteria must be defined and made visible from Integrity before
that query can be used from the Integrity Items view. The Query list is built when you display the
Integrity Items view and displays the Quick Query by default.
Note the following:
66
You can refresh the list of queries by clicking .
You can filter the Query list by typing the name of the query you are looking for. The query list
displays the first matching query in the list and auto-completes.
All queries visible to you display (favorites and non-favorites)
Toolbar
The following operations are available from the toolbar on the Integrity Items view:
TIP Right-clicking an item in the Integrity Items view allows you to perform the following
commands: View Item, Edit Item, and Create Change Package (if a Visual Studio solution is
open and under Integrity source control).
Command Operation
View Item ( ) Opens the selected item in the Item Details view.
Refresh Query List ( ) Refreshes the Query list, updating the definitions of available queries.
Re-run Query ( ) Runs the selected query in the Query list. When you run a query for the first time, a table
appears below the toolbar, where the column names are fields defined by the query’s
column set. The table is sorted to match the sort direction and fields in the query
definition. The default sort direction is the sort defined by the query definition. You can
sort the tables by clicking the column headers.
Note: Rich content appears as plain text in fields that support rich content.
Sharing is the process that associates a Visual Studio solution and its Visual Studio projects with an
Integrity project (the Visual Studio solution) and Integrity subprojects (the Visual Studio projects),
storing the relative layout of the solution and projects in a Sandbox (which may not be the layout
in the Integrity repository).
Once you place a Visual Studio solution and its projects under Integrity source control, you can
perform Integrity operations, such as checking in files and viewing annotated revisions. To allow
other users to work with the solution, they must import the solution (this creates a Sandbox of the
solution under Integrity source control). For more information, see “Importing a Visual Studio
Solution” on page 70.
67
Note the following:
The Visual Studio integration supports Web Application Projects and Web sites on file
systems. The integration does not support Web sites located via FTP and remote HTTP (HTTP
links must be converted to local paths before placing the Web Application Project or Web site
under Integrity source control).
Sharing Visual Studio projects within a Web site is not supported.
To avoid potential issues with updating the Integrity repository, always submit change
packages from Visual Studio, not the Integrity Client.
Your administrator may set policies that automatically define where on the Integrity Server
the corresponding Integrity projects and Integrity subprojects for Visual Studio solutions and
projects are placed. If these policies are defined, some of the steps in the following procedure
may not appear.
TIP You can edit the descriptions of the Visual Studio project’s shares, by clicking Advanced.
4 Specify where on the Integrity Server you want to add the solution. Choose one of the
following options, and then click Next:
In a new Integrity project
Specify the root path, project path, and name of the top-level Integrity project, then click
Next.
68
In an existing Integrity project or Integrity subproject
NOTE If the existing Integrity project contains identical files to the ones in the solution, the
files in the Integrity project are updated by the working files in the solution.
From the list, select the Integrity project you want to add the solution to, then click Next.
To filter the project list, type in the Show project names containing field to display top-level
projects matching the name you type.
5 Choose an option for adding Visual Studio solution files to the Integrity repository:
Add all files in the Visual Studio solution to source control using the change package <CP>. This
option is enabled by default.
Add only the Visual Studio solution and Visual Studio project files to source control using the change
package <CP>. This option is recommended if you are sharing a Visual Studio solution
containing a large number of files (over several hundred). After the Integrity project and
Sandbox are created, add the files to the solution in small batches using a separate change
package for each batch.
Click Next. A summary of your choices displays.
6 To share the solution, click Share. The integration informs you that the solution will be made
public (available for importing) when the change package associated with the share operation
is submitted to the Integrity repository.
7 Click OK.
In the Solution Explorer and Integrity Work In Progress view, the solution, project, and its files
display the glyph, indicating they are deferred member adds (files not yet committed to
the Integrity repository).
8 To submit the solution, project, and its files to the Integrity repository, submit the associated
change package by clicking in the Integrity toolbar or the Integrity Work In Progress
view. The Create Archive dialog box displays. Follow the procedure for creating archives, as
described in the Integrity User Guide.
IMPORTANT To avoid potential issues with updating the Integrity repository, always submit
change packages from Visual Studio, not the Integrity Client.
After the change package is submitted successfully, the change package and its entries
disappear from the Integrity Work In Progress view. In the Solution Explorer, the glyph
disappears from the solution, project, and files. The solution and project display the glyph,
indicating they are under source control.
69
Importing a Visual Studio Solution
To allow other users to use a solution under Integrity source control, they must import the
solution into Visual Studio. Importing a solution creates a Sandbox from the solution.
Note the following:
Sharing a solution records the information necessary to import a solution; therefore, you must
share a solution before you can import it (even if it is already in the repository).
If the import fails, any Sandboxes created during the import remain on the file system.
To import a solution
1 In Visual Studio, select File > Source Control > Import Solution. If you have a Visual Studio
solution open that is under Integrity source control, the integration warns you that importing
a solution closes the currently open solution. Before you import a solution, Integrity
recommends submitting any solution changes to the Integrity repository with an associated
change package.
To continue, click Yes. The Import Solution dialog box displays.
2 From the list, select the solution you want to import, then click Next. To filter the results, type
in the Show share names containing text field to display solutions matching the name you type.
NOTE A branched solution displays the development path name in brackets after the
solution name, for example, FinancialToolkit(ServicePack1). For more information
on branching a solution, see “Branching a Visual Studio Solution” on page 75.
3 Select the location on your local drive to create the Sandbox, then click Next. You can type the
location or click Browse to select a directory. A summary of your choices displays.
4 To import the solution, click Import. The solution displays in the Solution Explorer. The solution
and projects display the glyph, indicating they are under Integrity source control.
You can place a new or existing Visual Studio project under Integrity source control by adding it
to the shared Visual Studio solution it belongs to.
To create a new Visual Studio project and add it to the solution, right-click the solution
and select Add > New Project.
Specify the project information and click OK.
70
The Share a Visual Studio Project dialog box displays.
2 Sharing a project requires associating it with a change package. Select a change package from
the Change Package list, or create one by clicking Create.
3 To add the Visual Studio project to the solution, click OK. In the Solution Explorer and
Integrity Work In Progress view, the project and its files display the glyph, indicating they
are deferred member adds.
Adding a project to a solution requires writing to the solution file. To indicate that the solution
file is checked out and locked for editing, a glyph displays in the Solution Explorer and
Integrity Work In Progress view.
4 To submit the project, and its files to the Integrity repository, submit the associated change
package by clicking in the Integrity toolbar or the Integrity Work In Progress view. The
Create Archive dialog box displays. Follow the procedure for creating archives, as described in
the Integrity User Guide.
5 The Check In dialog box displays for the solution file. Follow the procedure for checking in a
member, as described in the Integrity User Guide.
After the change package is submitted successfully, the change package and its entries
disappear from the Integrity Work In Progress view. In the Solution Explorer, the glyph
disappears from the project and its files, and the project displays the glyph, indicating it is
under source control.
71
Before you drop the subproject, Integrity recommends verifying that it is not shared with another
Integrity project.
Importing a Visual Studio project is useful if you want to add a Visual Studio project in a Visual
Studio Solution to another Visual Studio solution. This adds the Visual Studio project to the
solution’s top-level Integrity project as a shared subproject. Both Visual Studio solutions must be
under Integrity source control.
2 Importing a project requires associating it with a change package. Select a change package
from the Change Package list, or create one by clicking Create. To proceed, click Next.
3 From the list, select the solution containing the project you want to import, then click Next. To
filter the results, type in the Show share names containing text field to display solutions matching
the name you type.
4 Select the location on your local drive to create the Sandbox, then click Next. You can type the
location or click Browse to select a directory. A summary of your choices displays.
72
5 To import the project, click Import. In the Solution Explorer, the solution displays the imported
project. The project displays the glyph, indicating it is under Integrity source control.
Importing a project to a solution requires writing to the solution file. To indicate that the
solution file is checked out and locked for editing, a glyph displays in the Solution Explorer
and Integrity Work In Progress view.
6 To submit the updated solution to the Integrity repository, submit the associated change
package by clicking in the Integrity toolbar or the Integrity Work In Progress view.
7 The Check In dialog box displays for the solution file. Follow the procedure for checking in a
member, as described in the Integrity User Guide.
After the change package is submitted successfully, the change package and its entry
disappear from the Integrity Work In Progress view. The solution now displays the glyph,
indicating the changes to the solution file are committed to the Integrity repository.
If you have an existing Visual Studio solution that was placed under version control using the
previous MKS SCC-based Visual Studio integration, you can migrate the solution for use with the
current integration.
To migrate a Visual Studio solution from the MKS SCC Visual Studio integration
1 In the MKS SCC-based Visual Studio integration, open the Visual Studio solution and remove
the SCC binding by selecting File > Source Control > Change Source Control > Unbind.
2 Ensure that all Visual Studio projects are saved and work properly.
3 Enable the new Visual Studio integration, as described in “Setting Up and Configuring the
Integration” on page 56.
73
4 Share the solution, as described in “Sharing a Visual Studio Solution” on page 67.
NOTE After you submit the change package associated with the share operation, some
Visual Studio projects may appear in the Integrity Work In Progress view under
Unassociated Changes. These represent changes for unbinding the projects. When you
share a Visual Studio solution, the integration does not submit any changes in existing
Sandboxes unless the Visual Studio integration changed the files during the share
operation.
5 If you add a new Visual Studio project to the migrated solution, right-click the project and
select View member properties. The Member Properties dialog box displays.
6 Click Allow The Integration To Add Visual Studio Projects To Source Control Automatically. The button
disappears.
Additional projects added to the solution are automatically added to source control; this
button does not appear.
7 Click Close.
For each solution you migrate, repeat this procedure.
There may be occasions where you want to ignore certain Visual Studio entities from source
control, for example, temporary files (.tmp). When you ignore Visual Studio entities from source
control, the entities are not annotated with glyphs in the Solution Explorer and are not valid
selections for Integrity commands. The ignored entities are saved to an .mksignore file with the
Visual Studio project you applied it to, adding it as a member of the Integrity subproject.
To apply the same ignore list to other projects, you must set them on a per-project basis.
2 To add a file type to the filter list, click Add and type the file type. To select multiple files, use
wildcard characters (* or ?). For example, to ignore all temporary files, type *.tmp.
3 To preview the files in the Visual Studio project that will be ignored, select the filter from the
ignore list and click Preview. A dialog box displays a list of files that will be ignored.
NOTE
If a file has a lock on it, you cannot create an ignore filter for that file. The integration
warns you about the affected files, but does not add them to the ignore list. Existing
locks are not removed.
If you choose to ignore file types that are currently in change packages, the integration
warns you about the affected files, but does not add them to the ignore list. To ignore the
file types, resolve the change packages (submit the change packages or remove specific
change package entries), and then add the file types to the ignore list.
4 Click OK.
74
5 To save your changes, click OK. In the Integrity Work In Progress view, the .mksignore file
displays the glyph, indicating it is a deferred member add.
6 To submit the file to the Integrity repository, submit the associated change package by
clicking in the Integrity toolbar or the Integrity Work In Progress view. The Create Archive
dialog box displays. Follow the procedure for creating archives, as described in the Integrity
User Guide.
After the change package is submitted successfully, the .mksignore file disappears from the
Integrity Work In Progress view.
Development paths are used to deliberately create a parallel branch of development for the
purpose of experimenting with research or performing post-release maintenance. Integrity allows
multiple developers to point to the same development path, each using their own variant
Sandbox.
When you need to create a new branch (development path) from an existing Visual Studio
solution under Integrity source control, you branch the solution. Branching a solution checkpoints
the solution, creates a development path on all Integrity projects associated with the solution in
the Integrity repository, and creates a Sandbox for the branched solution.
IMPORTANT Before you branch a solution, you should submit solution changes to the
Integrity repository with an associated change package. If you perform the branch
operation without committing your changes, the uncommitted changes do not appear in
the branched solution.
To branch a solution
1 With the Visual Studio solution open that you want to branch, select File > Source Control >
Branch Solution. The integration warns you that the operation creates a branch of the open
solution, based on the data currently committed to the Integrity repository. In addition, the
open solution will close and a new Sandbox will be created.
TIP If no solution is open, you can select File > Source Control > Branch Solution; however, you
are prompted to select a solution from a list of shared solutions.
6 Select the location on your local drive to create the Sandbox, then click Next. You can type the
location or click Browse to select a directory. A summary of your choices displays.
75
7 To branch the solution, click Branch. The integration informs you that the branched solution
will be made public (available for importing) when the change package associated with the
branch operation is submitted to the Integrity repository.
8 Click OK.
Branching a solution requires writing to the solution file. To indicate that the solution file is
checked out and locked for editing, a glyph displays in the Solution Explorer and Integrity
Work In Progress view.
9 To submit the branched solution to the Integrity repository, submit the associated change
package by clicking in the Integrity toolbar or the Integrity Work In Progress view.
10 The Check In dialog box displays for the solution file. Follow the procedure for checking in a
member, as described in the Integrity User Guide.
After the change package is submitted successfully, the change package and its entry
disappear from the Integrity Work In Progress view. In the Solution Explorer, the glyph
disappears. Other users can now create a Sandbox from the branch by importing the solution.
In the Import Solution dialog box, a branched solution displays the development path name in
brackets after the solution name, for example, FinancialToolkit(ServicePack1).
Resynchronizing a Visual Studio solution under Integrity source control updates your Sandbox
with the latest solution, project, and files. For example, if you see the glyph in the
Integrity Work In Progress view and Solution Explorer, there is a new member revision available
and you should resynchronize the solution.
Reverting a Visual Studio solution reverts all files in the solution containing working file changes;
however, it does not remove any recently added files to the solution from the file system. In most
Visual Studio projects, a revert operation removes recently added files from the project and
associated change package. In a Web site project, a revert operation removes recently added files
in the associated change package and displays the files under Unassociated Changes in the
Integrity Work in Progress view. To remove the files from the web site project, delete them.
IMPORTANT If change package reviews are enabled, submit any pending revisions before
you revert a Visual Studio solution.
76
To revert a Visual Studio solution
Do one of the following:
Select File > Source Control > Revert Solution.
Click in the Integrity toolbar.
Right-click the solution in the Solution Explorer and select Revert Solution.
A warning dialog box displays warning you that reverting the solution overwrites all of your
changes that have not been committed to the Integrity repository, and cannot be cancelled.
To proceed, click OK. The integration updates the solution, removing the change package entries
from the Integrity Work In Progress view and updating the glyphs in the Solution Explorer.
Checkpointing a Visual Studio solution creates a new revision of the associated Integrity project
and adds it to the project history. When you checkpoint a solution, you save all the information
needed to recreate the solution completely as it existed when you checkpointed it. The saved
information includes the solution and project structure and the list of files with their revision
numbers.
You can view the top-level Sandbox for an open Visual Studio solution by selecting File > Source
Control > View Solution Sandbox.
The Sandbox view displays.
For more information on the Sandbox view, see the Integrity User Guide.
77
Adding Members to an Integrity Project
Adding a file to a Visual Studio project performs a deferred add operation on the file.
NOTE When using the Copy command, the revision history is not copied from the source
location to the target location.
Deleting or removing a file from a Visual Studio project performs a deferred drop operation on the
file. After the change package is submitted, the file is deleted from the file system and removed
from the Integrity repository.
Note the following:
For a Web site under Integrity source control, the Visual Studio Exclude From Project command
simply removes the file from the Web site, leaving the file in the file system and under
Integrity source control. The Visual Studio Delete command deletes the file from the file
system and removes it from the Integrity repository.
Although you can delete files from a Visual Studio project while in offline mode and without
an active change package, the deleted files are not dropped from Integrity source control and
do not appear in the Integrity Work In Progress view under Unassociated Changes. In
addition, the files are deleted from the Visual Studio project and file system, preventing you
from moving them to a change package. To allow you to recover or resolve deleted files, you
should delete files in online mode and with an active change package.
78
Checking Out Members
In Visual Studio, open a file for editing and make changes. After you save changes to the file, a
glyph displays next to it in the Integrity Work In Progress view and Solution Explorer, indicating the
file is checked out by you and has been modified.
Checking In Members
In Visual Studio, submit the change package associated with a file checked out by you, indicated
by a glyph in the Integrity Work In Progress view and Solution Explorer.
The Check In dialog box displays for the file. Follow the procedure for checking in a member, as
described in the Integrity User Guide. After the change package is submitted successfully, the
change package and its entry disappear from the Integrity Work In Progress view. In the Solution
Explorer, the glyph disappears.
Renaming Members
Renaming a file in Visual Studio performs a deferred rename operation on the file.
NOTE If you attempt to rename a file locked by you in another change package, the rename
operation is performed in the change package containing the locked file. For example, if
Form.vb is locked by you in change package 12:1 and your active change package is 12:2,
renaming Form.vb to Form2.vb performs the rename operation in 12:1 because Form.vb
already exists in that change package. This also applies to moving a file or locking a file
that is a deferred rename operation in a change package.
1 In Visual Studio, rename a file in a Visual Studio project under Integrity source control. In the
Solution Explorer, the renamed file displays a glyph. In the Integrity Work In Progress view,
the renamed file displays a glyph. In Integrity Work In Progress view and the Solution
Explorer, the Visual Studio project displays a glyph.
2 Submit the change package associated with the rename. The Check In dialog box displays for
the project file.
3 Follow the procedure for checking in a member, as described in the Integrity User Guide. The
Check In dialog box displays for the renamed file.
4 Check in the member. After the change package is submitted successfully, the change package
and its entries disappear from the Integrity Work In Progress view. In the Solution Explorer, the
glyph disappears.
Moving Members
You can move folders and files between projects in a Visual Studio solution, which performs a
deferred move operation.
Note the following:
Dragging and dropping, or using the Cut/Copy command to move a folder or file performs a
deferred drop and add operation, effectively erasing the revision history. If you use these
commands to move a file in offline mode without an active change package, the file is
removed from the Visual Studio project but not from Integrity source control. To move a file,
you should use the Integrity Move From/To commands in online mode with an active change
package.
79
Moving a file to a location where a file with the same name exists results in an error.
If you move an entire tree of files, the source folders are still visible in the Solution Explorer.
After moving a tree of files, you must manually remove the source folders.
Select the project you want to move the file/folder to, then right-click and select Integrity
Move To.
Drag the file/folder you want to move and drop it in the desired project.
Right-click the file/folder you want to move and select Cut/Copy.
Select the project you want to copy the file/folder to, then right-click and select Paste.
In the Solution Explorer, a moved file displays a glyph. In the Integrity Work In Progress
view, a moved file displays a glyph.
2 Submit the change package associated with the move. After the change package is submitted
successfully, the change package and its entry disappear from the Integrity Work In Progress
view. In the Solution Explorer, the glyph disappears.
You can access advanced Integrity member functionality from within Visual Studio by right-
clicking a Visual Studio solution, Visual Studio project, or file in the Solution Explorer or
Integrity Work In Progress view and choosing a command from the short cut menu.
NOTE In the Solution Explorer, short cut menu operations operate on the selected file. The
short cut menu in the editor window operates on the currently open file. If Visual Studio
does not allow you to select the file and display a short cut menu, you can click the "Show
All Files" button in the Solution Explorer, and use the context menu operations from there.
Command Function
80
Command Function
View member history Equivalent to the Integrity View Member History command.
Displays the revision history of the selected file.
The Member History view displays.
View member properties Equivalent to the Integrity View Member Information command.
Displays the member information of the selected file.
A dialog appears, displaying server name and port number, solution share name, solution
project, member name, project share name, project configuration path, member name,
Sandbox, member revision, working revision, and development path (if applicable).
To view additional Integrity information, click Integrity Member.
The Member Information view displays.
Best Practices
This section describes best practices for using the Visual Studio integration. It also points out
efficiencies that can be gained by using the integration in a certain way, as well as identifying any
risks, constraints, or other limits within the integration or within a particular implementation of
the integration.
Displaying working file status for overlapping Sandboxes/subsandboxes
To ensure that correct status displays for working files in overlapping Sandboxes/
subsandboxes, you should:
Not change CreateSubproject policies (creating subprojects for every folder when
adding/moving members) without also manually restructuring existing project trees.
Avoid using mixed CreateSubproject policies across Visual Studio solutions and projects.
Notification of file changes in Visual Studio solutions
To prevent file change notifications from appearing when you resynchronize or revert a
Visual Studio solution, set the following preferences in Visual Studio:
a) Select Tools > Options > Environment > Documents.
b) Enable Detect when file is changed outside the environment and Auto-load changes, if saved.
c) To save your preferences, click OK.
Creating In-Tree Visual Studio projects and Web sites
As a best practice, place Visual Studio projects and Web sites in-tree with the associated
Visual Studio solution to simplify source control operations for other users. Visual Studio
projects and Web sites that are out-of-tree can cause confusion or problems when users import
or branch solutions.
Setting Up Projects to Reuse Code
The ability to reuse code is an important part of managing software development. If you set
up your project structure so that each component is self-contained, you can share that
component with other solutions through the use of Integrity subprojects. By referencing the
original subproject, Integrity allows you to share a subproject and the members it contains
81
between two or more projects. Shared subprojects do not have to be located within the same
directory structure or project hierarchy.
To share project code, import an existing Visual Studio project to the Visual Studio solution
that you want to share the project with. Projects are shared at the solution level; Web sites are
shared at the solution root level. For more information on importing Visual Studio projects,
see “Importing a Visual Studio Project” on page 72.
Creating and sharing a Visual Studio project
The following option should always be enabled in Visual Studio before you create a Visual
Studio project: Tools > Options > Projects and Solutions > General > Save new Projects when created.
By default, this option is enabled. If this option is disabled, a Visual Studio project cannot be
shared.
Ignoring files from source control
There may be occasions where you want to ignore certain Visual Studio entities from Integrity
source control, for example, temporary files (.tmp). As a best practice, specify the entities you
want to ignore before you add files to a Visual Studio project. For best results, ignored files
should not be placed under source control.
Java memory usage
If you are working with large solutions or large change packages, increase the Java heap size
on the Integrity Client for better performance, for example, 512 MB. For more information,
contact PTC-Integrity Support.
Working with multiple Visual Studio Solutions
Opening a Visual Studio solution closes the currently open Visual Studio solution. You should
save your changes and submitting any associated change packages before you open another
Visual Studio solution.
Submitting change packages in Visual Studio
To avoid potential issues with updating the Integrity repository, always submit change
packages from Visual Studio, not the Integrity Client.
Resolve conflicts before submitting change packages
Integrity allows you to resolve conflicts when checking in members; however, PTC
recommends resolving conflicts by resyncing the repository before submitting a change
package. This avoids potential workflow issues and allows compiling and testing with the
incoming changes in the Sandbox.
Refactoring in a Team Environment
When working in a team environment, there are refactoring scenarios that users should be
aware of or avoid to prevent conflicts.
IMPORTANT To allow you to recover or resolve refactored files, PTC strongly recommends
that you perform all refactoring operations (add, drop, move, and rename) in online mode
with an active change package.
82
To recover and save his work, David must manually make changes.
Renaming a Locked Member:
In a change package, Mary has a lock on Application1.vb.
David cannot rename Application1.vb because of the lock.
David can drop Application1.vb and add it as Application2.vb, ignoring Mary’s lock on
Application1.vb.
PTC recommends backing up this file along with other Integrity Server files; however, do not
edit the file. Editing the file may cause shares to not work properly.
Viewing visible fields in query results
When running a query from the Integrity Items view in Visual Studio, query results are
displayed with the ID, Type, State, and Summary columns, even when additional columns are
set as visible. To see all visible fields, you must set the column set to Custom.
To see all visible fields when running a query, open the Integrity Client and select the target
query. Choose Query > Edit > Column Set and select the Custom option. When running the query,
all visible columns are then displayed.
Limitations
While loading a Visual Studio solution, Integrity commands may not appear consistently in
shortcut menus.
Migrating a build Sandbox from the previous SCC-based Visual Studio integration to the
current SDK integration is not supported. This is due to the fact that a migration causes the
member files to change, which is a limitation of build Sandboxes.
When two users simultaneously add Visual Studio projects to a Visual Studio solution, the
project information is not saved in the merged Visual Studio solution file for the user who
83
submitted the solution file first. This generates an error message stating that Visual Studio
cannot load the added project.
To avoid this error, select Option 2 - resynchronize the member revision via change
package, merging as needed. If you do not select Option 2, you must resynchronize the
Visual Studio solution containing the unavailable project.
If you enabled password prompting on the Integrity Client, the integration cannot use the
specified default password. When prompted in the integration, you must re-type your
password.
Moving a file from one Visual Studio project to another may take a long time to complete if
your Recycle Bin contains too many items. This is a known issue with Visual Studio.
Emptying your Recycle Bin improves the speed of the move operation.
The Visual Studio integration does not support renaming Visual Studio solutions, Visual
Studio projects, or Web sites. You can rename directories; however, you must commit any
changes to files in a directory before the rename operation. If you are moving a directory, you
must also commit any changes to files in the directory before the move operation.
Importing a Visual Studio solution containing unshared Visual Studio projects displays an
error message for each unshared project in the solution.
Date-only fields may incorrectly display as date/time fields in the Integrity Items view.
If you create two top-level Integrity projects for a Web site solution and Web site project, and
two separate Sandboxes associated with each Integrity project, when you share the Web site
solution in Visual Studio, the Web site project files are not included in the change package
used for the share operation. The Web site project files display as Unassociated Changes in
the Integrity Work In Progress view and only the solution is shared. To resolve this issue,
move the Web site files from the Unassociated Changes to a change package and submit the
change package.
Troubleshooting
To assist you in diagnosing issues that may arise when using the Visual Studio integration, the
Integrityvsi.log file is created on the machine where Visual Studio and the Integrity Client are
installed. The log file records information, warnings, and error messages.
To open the log file, select Tools > Options > Source Control and then choose the Integrity plug-in.
The Logging option displays. Click Logging and in the right pane click Open.
If you require assistance, contact PTC-Integrity Support and provide them with the log file. In
addition, include the version number of the Integrity Visual Studio integration and the Integrity
Client it is communicating with (in Visual Studio, click in the Integrity toolbar).
84
85
C HAPTER S EVEN
Microsoft Visual Studio .NET 7
The purpose of this chapter is to assist you in implementing and using the Integrity integration
with Microsoft® Visual Studio® .NET 2003. The integration provides a streamlined process for
adding projects and solutions under source control, including the Change Package field that allows
you to pre-select a change package when adding a solution to source control.
This chapter helps you decide how to use the features of Visual Studio .NET 2003 with Integrity
for configuration management, and suggests ways to implement the integration so that it has
minimal impact on end users and minimal administrative overhead. It also describes how users
can access Integrity from Visual Studio .NET 2003 once the integration is implemented.
NOTE MKS Worktray for Microsoft Visual Studio .NET 2003 is no longer supported.
To help you set up and use the integration, this chapter discusses the following topics:
“Implementing the Integration” on page 87
“Setting Preferences” on page 90
“Parallel Development Considerations” on page 91
“Building Projects” on page 93
“Command Functionality” on page 94
“Troubleshooting” on page 101
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
86
Implementing the Integration
This section provides information on implementing the integration and includes the following
topics:
“Assumptions” on page 87
“Required Permissions” on page 87
“Implementing the New Project Structure” on page 87
“Setting Up Projects to Reuse Code” on page 88
Existing Visual Studio .NET, 2002, and 2003 solutions, and projects integrated with earlier
versions of Integrity, are not affected when you upgrade to Integrity.
Assumptions
Before you implement the Visual Studio .NET 2003 integration, you should have a good
understanding of both Integrity and Visual Studio .NET 2003, particularly in the areas of
managing projects and solutions.
Required Permissions
When using the Integrity integration with Microsoft Visual Studio, certain additional permissions
are required for the user running the following commands:
Add Solution to Source Control
Add Selected Projects to Source Control
The user adding the project requires the following permissions in the Integrity Access Control List
(ACLs):
ModifyProjectAttribute
CreateSubproject
For more information on configuring ACLs for Integrity, see the Integrity Server Installation and
Configuration Guide.
Visual Studio .NET 2003 requires integrated source control systems to use a new project structure,
based on the concept of a solution root.
87
For more information on the solution root concept, see http://msdn.microsoft.com.
The ability to reuse code is an important part of managing software development. If you set up
your project structure so that each component is self-contained, you can share that component
with other solutions through the use of Integrity subprojects. By referencing the original
subproject, Integrity allows you to share a subproject and the members it contains between two or
more projects. Shared subprojects do not have to be located within the same directory structure or
project hierarchy.
To share project code, you need to add the project as a shared subproject in Integrity, then add it
as an existing project in Visual Studio .NET 2003. Non-Web projects are shared at the solution
level; Web projects are shared at the solution root level.
NOTE Within the integration, sharing a variant subproject is possible but not
recommended.
2 In the Sandbox view, select the solution Sandbox and add the shared subproject.
For more information on how to set up shared subprojects, see the Integrity User Guide.
88
3 Resynchronize the new shared subproject.
4 Close the Sandbox view.
5 In the Visual Studio .NET 2003 Solution Explorer panel, select the solution, then select Add >
Existing Project.
6 Select the project to add. You are prompted to check out the solution file.
7 Check out the solution file.
8 Check in the solution file.
IMPORTANT You must share the subproject using the same name as the original subproject,
for example, WebApplication1/project.pj.
For more information on how to set up shared subprojects, see the Integrity User Guide.
2 Create a Sandbox from the newly shared subproject.
3 In the Visual Studio .NET 2003 Solution Explorer panel, select the solution, then select Add >
Existing Project.
4 Select the project to add. You are prompted to check out the solution file.
5 Check out the solution file.
6 Check in the solution file.
NOTE If the member revision is updated in the source project, it is not updated in the
project it is shared to. The member revision in the shared project must be updated
manually.
89
To set up Master Projects
1 In Visual Studio .NET 2003, create your solution.
2 In Integrity, create your master project.
For more information, see the Integrity User Guide.
3 Create the subproject that you want to use as your solution root.
For more information, see the Integrity User Guide.
4 Create a subproject inside the subproject you created in step 3 and name it <solution name>/
project.pj.
5 Create a Sandbox from the subproject you created in step 4 and place it in your solution
directory.
6 In Visual Studio .NET 2003, select your solution and click File > Source Control > Add Solution to
Source Control.
You are prompted to add the solution files to your Sandbox location.
7 Repeat steps 1-6 for additional solutions.
Setting Preferences
You can now set Integrity Client preferences from within Visual Studio .NET 2003 using the
Preferences Configuration option.
Required Settings
You must also set the following Integrity Client preferences to make the integration work
smoothly:
Under the Integrity Client node, click the Connection folder and in the right pane, clear the Prompt
for User Name and Prompt for Password options for connection preferences. This eliminates the
need for users to enter this information when they perform an action that interacts with
Integrity.
Under the Configuration Management node, click the Commands folder and under the Add
Members command, select the Create Subprojects option. This enables subprojects to be created
for sharing project components.
90
NOTE If you select the Create Subprojects option after adding non-Web projects, and then
add new members to those projects, see “Troubleshooting” on page 101 to resolve the
issue. If you do not resolve the issue, you will encounter Sandbox detection problems
when performing operations in the integration.
Under the Configuration Management node, click the Commands folder and under the Check In
command, select the Check In if Unchanged option. In Visual Studio .NET 2003, there are several
cases where multiple files are used to represent one thing. When a change is made, it is
typically made to one of the set of files, but Visual Studio .NET 2003 checks out all associated
files and attempts to check in all associated files. Selecting this option prevents users from
getting potentially confusing messages.
For more information on setting preferences, see the Integrity Server Installation and Configuration
Guide.
NOTE The integration between Visual Studio .NET 2003 and Integrity does not support
non-exclusive locking.
Optimistic Locking
Optimistic locking allows multiple users to check out and edit any file, even if another user has
checked it out. When you check in a file that has been checked out with optimistic locking, the
following steps take place:
The latest revision of the file is silently checked out with an exclusive lock.
If the latest revision has changed since the file was checked out, the file being checked in is
merged with the latest revision. This can happen automatically or manually, depending on
how you set up your policies (for more information, see “Setting Up Optimistic Locking” on
page 92). Any merge conflicts are reported so the user can resolve them.
The file is checked in as a new revision.
91
(check in)
1.4
User 2
1.1
If this policy is set to false (the default), optimistic locking is disabled. Setting this policy to
true enables optimistic locking.
If this policy is set to true (the default), when files are checked in they are automatically
merged with the current member revision if there are no conflicts. If this policy is set to false,
users are given the option of automatically or manually merging on checkin. Users should be
given the option to merge manually if they are working with structured files (for example,
HTML, XML).
SCC.optimisticLocking.autoCheckinAfterMerge (default is confirm)
If this policy is set to confirm (the default), when a user checks in a file that requires merging,
the user must confirm that their files should be automatically checked in after merging. If this
policy is set to yes, files are automatically checked in after merging. If this policy is set to no,
users have the option of testing their merged files before checking them in.
SCC.optimisticLocking.autoCheckInIfBinary (default is confirm)
Binary files cannot be merged. If the latest revision has changed since the file was checked out,
the file being checked in overwrites the latest revision. If this policy is set to confirm, when a
user checks in a binary file that is different from the latest revision, they are asked to confirm
the check in. If this policy is set to yes, binary files are automatically checked in and overwrite
the latest revision. If this policy is set to no, users have the option of not overwriting the latest
revision.
You must also ensure that source control dialogs are disabled in Visual Studio .NET 2003 (they are
disabled by default). To check the setting, in Visual Studio .NET 2003 click Tools > Options > Source
Control, and on the General tab make sure the Display silent check out command in menus, and the
Display silent check in command in menus are both selected.
Development Paths
Development paths are used to deliberately create a parallel branch of development for the
purpose of experimenting with research or performing post-release maintenance. Integrity allows
multiple developers to point to the same development path, each using their own variant
Sandbox.
92
If you use branching to support parallel development, experienced users can also use branching
instead of development paths for experimental work. This eliminates the administrative work
associated with development paths.
If you use optimistic locking to support parallel development, all experimental work must be
done on development paths.
To make sure you get the correct version of all project files in your development path, you need to
establish a record—or baseline—of the project at the time you create the development path.
Checkpointing a project in Integrity saves a copy of the project as a baseline revision in the
project’s history.
Parallel
Developm ent Project
1.2.1.2
Main Developm ent
Project
1.4 1.3.1.1 1.2.1.1 1.4.1.1
Checkpoint
create
development utility.cpp utility.h utility.rc
1.3 1.3 path
IMPORTANT Make sure all projects have the same development path.
3 In Visual Studio .NET 2003, create a variant Sandbox from the project (File > Open From Source
Control). For more information, see the Integrity User Guide.
Building Projects
At key development stages, you need to build a static version of an entire project based on a
particular project revision. To make sure your build includes the correct version of all the files in
your solution, you should do the following:
1 In Integrity, checkpoint the project at the solution root level.
2 In Integrity, create a development path from the checkpointed revision.
3 In Visual Studio .NET 2003, create a build Sandbox from the project (File > Open From Source
Control).
NOTE Build projects are not explicitly supported in the integration with Integrity. For each
Sandbox you create, you must manually select the project revision required for the build
project.
93
Command Functionality
This section describes how to access Integrity functionality through Microsoft Visual Studio .NET
2003.
You can access basic version control functionality, such as checking in a file, from within Visual
Studio .NET, by selecting one or more files in the Solution Explorer panel, then selecting File > Source
Control (or right clicking), then selecting one of the following commands:
Command Function
Add Solution to Source Control Equivalent to the Integrity New Project command.
Creates an Integrity project from the selected Visual Studio .NET solution
(this includes all related Visual Studio .NET projects in the solution).
The Create Project Wizard displays.
For more information, see “Adding a Solution to Integrity” on page 96.
Add Selected Projects to Creates a top-level Integrity project outside of the solution root structure for
Source Control the selected Visual Studio .NET Web project.
Important: This command is not recommended if you have an existing
solution root. Instead of this command, you can also use the Check In
command to add new projects to source control.
If the SLN file is not added to source control, this command also launches the
Create Project Wizard.
If the SLN file is already under source control, you are prompted to add the
selected projects to the same location.
If change packages are enabled, the Create Subproject dialog box displays.
Open From Source Control Equivalent to the Integrity New Sandbox command. Selection must be
subproject of the solution root that contains the SLN file.
Creates a Sandbox from a solution on the server.
If you are creating a build Sandbox, see “Joining Development of a Solution”
on page 98.
Change Source Control Allows you to connect/disconnect from the Integrity Server or bind a solution
that was added to Integrity outside of the integration.
You are prompted to check out the SLN file. To update the bindings, click OK.
For more information, see “Joining Development of a Solution” on page 98.
Note: The Browse function is not applicable to Integrity.
Check Out Equivalent to the Integrity Check Out command. Checks out the selected
file(s).
The Check Out dialog box displays.
For more information, see “Checking Out Members” on page 100.
94
Command Function
Exclude … from Source Control Disables version control operations for the selected file(s).
Add Project From Source Control Equivalent to the Integrity New Sandbox command.
Creates a Sandbox from the selected Visual Studio .NET project on the
server, and adds that project to the current solution. Use shared subprojects
as described in “Setting Up Projects to Reuse Code” on page 88.
Important: This command is not recommended if you have an existing
solution root.
MKS SCC Integration Equivalent to launching the Integrity graphical user interface or the Integrity
Open Sandbox command.
Displays a Sandbox view.
Note: If there is no selection, the default view displays.
The Visual Studio .NET Solution Explorer panel is also enhanced with version control features and
indicators. For example, a lock icon is displayed beside a file if it is under version control, and a
red check mark with an exclamation mark displays beside a file if it is checked out by you with a
lock.
95
Solution Explorer Icons
Icon Definition
Displays when the file is under version control but is not currently being accessed.
Displays when checking out the file using optimistic locking. The file is writable.
Displays when you check out the file with a lock, or the file is locked by you.
Displays when someone else checks out the file with a lock, or file is locked by that
person.
By adding a solution to Integrity, you automatically add all of the projects and files contained in
that solution.
When adding a solution, subprojects are created for Web projects. However, by default,
subprojects are not created for non-Web projects. To create subprojects for non-Web projects,
before performing this procedure, select the Create Subprojects option in Preferences Configurations
dialog box for the Add Members command.
NOTE If you select the Create Subprojects option in Preferences Configurations dialog box for
the Add Members command after adding non-Web projects, and then add new members to
those projects, see “Troubleshooting” on page 101 to resolve the issue. If you do not resolve
the issue, you will encounter Sandbox detection problems when performing operations in
the integration.
When adding a solution, all files in the solution are added as members. For information on the
recommended project structure, see “Best Practices for Solution Root Project Structure” on
page 88.
A Sandbox is automatically created for the solution, containing corresponding subSandboxes for
the subprojects.
IMPORTANT If you added a solution to Integrity from outside of Visual Studio .NET instead
of as described in this procedure, you must bind the files by selecting Source Control >
Change Source Control. Then from the Change Source Control dialog box, select the files in the
list, and then click Bind.
96
3 For the project you originally selected, choose one of the available options:
Create a new projectand click Finish. The Specify Project dialog box displays. In the File name
field, specify the name of the project you want to create on the Integrity Server.
Create as a subproject of an existing project and click Next. In the Project Name field, specify the
name of the existing Integrity configuration management project or click Browse to select it
from the list of existing registered projects on the Integrity Server. In the Subproject Name
field, specify the name of the subproject you are creating. (By default, the name is
<solution name>.root.) To have the changes take effect, click Finish.
NOTE By default, if you create a chain of directories, all subfolders in the directory are also
created as subprojects. If a subfolder does not include a .pj file, project.pj is also added
to the subproject string.
4 If your project contains files, the Create Archive dialog box displays. Modify the Create Archive
options as described in the Integrity User Guide or online help.
NOTE If Integrity finds an existing archive, the Existing archive detected dialog displays. For
more information on sharing archives, see the Integrity User Guide or online help.
For each Web project, subprojects are created using the Web project names.
Each file under version control corresponding to a Integrity member is marked in the Solution
Explorer with the icon.
Integrity also automatically creates a Sandbox with the project name in your .NET workspace.
If an existing Sandbox is detected in the solution directory, the Get SCC Project Path dialog box
displays, asking you if you want to use the existing Sandbox for source control operations.
NOTE If you want to use a new Sandbox, click No to return to the Create Project Wizard.
To use the existing Sandbox for source control operations, click Yes. The Solution Root Location
Wizard displays.
97
5 The solution root represents the location where future Web projects will be created. Select
from the available options:
Use the identified project or click Browse to select another project.
Create a new project or subproject on the Integrity Server.
Disable solution root functionality for this solution.
6 To use the selected solution root option, click Finish.
If a solution is already under version control, but you have now created additional projects, those
projects can be added separately to Integrity as either top level projects or subprojects of the
solution. A Sandbox is automatically created for the projects or subprojects.
NOTE If the SLN file is bound through Change Source Control and Web projects are added,
the Solution Root Location Wizard displays. The Solution Root Location Wizard also displays if
the SLN file is bound through Change Source Control and it contains pre-existing Web
projects.
If you are adding a non-Web project, a Sandbox is created automatically. For subdirectories to
be added as subprojects in the Sandbox, you must select the Create Subprojects option for the
Add Members command.
If change packages are enabled, the Create Subproject dialog box displays. Select the
appropriate change package from the list and click OK.
The Create Archive dialog box displays.
2 Modify the Create Archive options as necessary as described in the Integrity User Guide.
Each file under version control corresponding to an Integrity member is marked in the
Solution Explorer with the icon.
You can join the development of a solution already under source control by creating a Sandbox
corresponding to that solution on your local machine.
If you are creating a build Sandbox, see “Building Projects” on page 93.
NOTE If you are creating a Sandbox for a master project that was created and placed under
source control before using Integrity (but not migrated to a solution root), each time the
Create Sandbox Wizard displays for a Web project, you must select the Integrity project that
corresponds to that Web project.
98
To create a Sandbox in Visual Studio .NET
Select the subproject of the solution root containing the Visual Studio .NET solution (SLN file)
under version control that you want to create a Sandbox from. Select File > Source Control > Open
From Source Control. The Create Sandbox Wizard displays. Create a Sandbox as described in the
Integrity User Guide.
NOTE If an existing Sandbox is detected in the solution directory, the Get SCC Project Path
dialog box displays. To add the solution to source control, click Yes.
You can add new members to source control by checking them in.
NOTE If you previously added non-Web members to source control without creating
subprojects for them, and are adding new members to those projects, see
“Troubleshooting” on page 101 to resolve Sandbox detection errors.
99
Checking Out Members
IMPORTANT If optimistic locking is enabled, you cannot have an exclusive lock on the
member. The member displays in the Solution Explorer with a icon. For more
information, see “Optimistic Locking” on page 91.
In the Integrity GUI, there is no icon marker for members that have optimistic locks.
The file displays in the Solution Explorer with a icon denoting that it is checked out with a
lock.
Checking In Members
If optimistic locking is enabled, your checked in changes are merged with the latest revision,
rather than contained in their own revision. Binary files cannot be merged, but instead they
overwrite the member revision. For more information, see “Optimistic Locking” on page 91.
NOTE If another user has an exclusive lock on a member that you have an optimistic lock
on, you must wait until that user checks in the member (thereby releasing the exclusive
lock) before you can check in your changes. For more information, see “Optimistic
Locking” on page 91.
IMPORTANT If optimistic locking is enabled with auto merge, the changes are merged with
the latest revision automatically. If auto merge is not enabled, then you are presented with
the option to merge manually.
If you are checking in a binary file, you are prompted to overwrite the member revision
with the working file contents.
For more information on optimistic locking, see “Building Projects” on page 93.
100
Troubleshooting
Problem Solution
The file is not a current or Occurs when trying to check out a member after adding Visual Studio .NET non-
destined or pending member or Web projects to source control as Integrity subprojects, when non-Web projects
subSandbox of project (after were previously added as subfolders only. This occurs because the Create
Create Subprojects option is Subproject option was selected in the Integrity Client preferences after already
selected in Add Member adding .NET projects, and then new members were added to the non-Web project.
command preferences). If a non-Web project is added to source control with the Create Subprojects option
not selected in the client preferences, it is added as a sub folder in the Integrity
configuration management project. If you select the option at a later date, any new
members added to the non-Web project will create a subproject in the folder for that
member.
Workaround: Before continuing to use source control with any members that were
added before enabling Create Subprojects, migrate them from the sub folder to the
subproject.
If you do not migrate the sub folder members to the non-Web subproject, you will
encounter Sandbox detection problems when performing operations in the
integration.
Working file revision contents Occurs when cancelling a check in operation on an optimistically locked member
failed to revert after cancelling a after previously accepting a merge operation. By accepting the merge, you have
check in operation. accepted the introduction of another user’s work into your Sandbox working file.
Workaround: None
Sandbox not populated with Occurs when selecting the solution project file rather than the project that contains
members after creating a new the SLN file during an Open From Source Control operation.
Sandbox through the VS .NET Workaround: Select SLN file when performing Open From Source Control
integration. operation.
Sandbox for Web project created Occurs when you added the Web project to source control using the Add Selected
as top level Sandbox when Projects to Source Control command.
should be subSandbox. Workaround: Drop the Web projects from Integrity, and then add the Web projects
Sandbox on main trunk when from the .NET integration using the Check In command.
should be on same variant as
solution.
Error Message: "You already Occurs when you are attempting to join the development of a solution already under
have a local copy of the solution source control by creating a Sandbox corresponding to that solution on your local
or project you selected. Use the machine, but that the following has occurred:
Open Solution command on the You attempted to create the Sandbox through the integration using the Open
File menu to open the local From Source Control command.
copy." The user who created the solution added an existing project, which is located
outside of the solution tree, to that solution before placing it under source control.
Workaround: Create a Sandbox for the solution using the Integrity Client instead of
the integration. When creating the Sandbox, be sure to select the subproject that
contains the SLN file for the solution, not the root project. Then open the Sandbox
through the integration using the Open From Source Control command.
Error Message: “Refresh source Occurs when you are attempting to add a project to source control using the
code control status: The Add Selected Projects to Source Control command.
operation could not be Workaround: In the Integrity Client connection preferences, in the Prompt for area,
completed” clear the User Name and Password options.
101
CHAPTER EIGHT
Microsoft Visual Basic 8
The Integrity integration with Microsoft® Visual Basic® allows you to access the configuration
management functionality of Integrity when working within a Visual Basic integrated
development environment.
This chapter provides instructions on using the integration and includes the following topics:
“Using the Microsoft Visual Basic Integration” on page 103
“Creating an Integrity Project” on page 104
“Creating a Sandbox” on page 104
“Adding Members to an Integrity Project” on page 104
“Checking Out Members” on page 105
“Checking In Members” on page 105
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
102
Using the Microsoft Visual Basic Integration
This section describes how to access Integrity through Microsoft Visual Basic 6.0.
You can access version control functionality from within Visual Basic by choosing Tools >
MKS Integrity SCC Extension,
then by selecting one of the following commands:
Command Function
Add Project to MKS Integrity SCC Equivalent to the Integrity New Project command.
Extension Brings the selected Visual Basic project under version control.
Add Files to MKS Integrity Equivalent to the Integrity Add Members command.
SCCExtension Adds the selected file(s) to the Integrity project.
Run MKS Integrity Equivalent to launching the graphical user interface or the Integrity Open Sandbox
SCC Extension command.
Displays a Sandbox view.
Refresh File Status Equivalent to the Integrity Scan for Changes command.
Updates the status and archive information of the selected file(s).
The Visual Basic Project window is enhanced with version control features and indicators. For
example, a check mark beside a file icon indicates the file is currently checked out. When a file is
read-only, a small lock displays next to the file icon in the project window.
103
Creating an Integrity Project
To create an Integrity configuration management project in Visual Basic
1 Open the Visual Basic project you want to put under version control.
2 Select Tools > MKS Integrity SCC Extension > Add Project to MKS Integrity SCC Extension. The Specify
the Project to Create dialog box displays.
3 Create a project as described in the Integrity User Guide. The Create Sandbox Wizard displays.
4 Create a Sandbox as described in the Integrity User Guide. The Add Files to MKS Integrity SCC
Extension dialog box displays.
5 Select the file(s) you want to add to the Sandbox.
6 Click OK. The Create Archive dialog box displays.
7 Modify the Create Archive options as necessary as described in the Integrity User Guide.
Creating a Sandbox
To create a Sandbox in Visual Basic
Open the Visual Basic project you have under version control. Select Tools > MKS Integrity SCC
Extension > Create a Project from MKS Integrity SCC Extension. The Create Sandbox Wizard displays.
Create a Sandbox as described in the Integrity User Guide.
104
Checking Out Members
To check out members in Visual Basic
1 In Visual Basic, select one or more files to check out.
2 Select Tools > MKS Integrity SCC Extension > Check Out. A list displays, showing all files that can
be checked out.
3 Select one or more files to check out.
4 Click OK. The Check Out dialog box displays.
5 Check out each member as described in the Integrity User Guide.
Checking In Members
To check in members in Visual Basic
1 In Visual Basic, select one or more files to check in.
2 Select Tools > MKS Integrity SCC Extension > Check In. A list displays, showing all files that can be
checked in.
3 Select one or more files to check in.
4 Click OK. The Check In dialog box displays.
5 Check in each member as described in the Integrity User Guide.
105
CHAPTER NINE
Microsoft Visual C++ 9
The Integrity integration with Microsoft® Visual C++® 6.0 allows you to access the configuration
management functionality of Integrity when working within a Visual C++ integrated
development environment.
This chapter provides instructions on using the integration and includes the following topics:
“Configuring the Visual C++ Integration” on page 107
“Using the Microsoft Visual C++ Integration” on page 107
“Creating an Integrity Project” on page 108
“Creating a Sandbox” on page 108
“Adding Members to an Integrity Project” on page 108
“Checking Out Members” on page 108
“Checking In Members” on page 109
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
106
Configuring the Visual C++ Integration
The Integrity Client includes the File > Integrations menu action for enabling and disabling the
integration with Microsoft Visual C++. You can select from a list of available integrations and
enable or disable them, as required to work with your preferred application. For more
information, see “Configuring Integrations” on page 3.
Command Function
Add to Source Control Equivalent to the Integrity New Project command or the Integrity Add Members
command.
If you choose a DSP or DSW file in Visual C++, then select Add to Source Control, the
Visual C++ project is placed under version control.
If you choose an individual Visual C++ project file, then select Add to Source Control,
the file is added to version control as a member.
The Create Archive dialog box displays.
Remove from Source Control Equivalent to the Integrity Drop Members command.
Drops the selected file(s) from the Integrity project.
The Drop Member dialog box displays.
MKS Integrity SCC Extension Equivalent to launching the graphical user interface or the Integrity Open Sandbox
command.
Displays a Sandbox view.
107
Creating an Integrity Project
To create an Integrity project in Visual C++
1 In Visual C++, select the project you want to put under version control.
2 Select Project > Source Control > Add to Source Control. The Specify the Project to Create dialog box
displays.
3 Create a project as described in the Integrity User Guide. The Create Sandbox Wizard displays.
4 Create a Sandbox as described in the Integrity User Guide. The Add to Source Control dialog box
displays.
5 Select one or more files to add to the Integrity project.
6 Click OK. The Create Archive dialog box displays.
7 Modify the Create Archive options as necessary as described in the Integrity User Guide.
Creating a Sandbox
To create a Sandbox in Visual C++
1 In Visual C++, select File > Open Workspace. The Open Workspace dialog box displays.
2 Select the Visual C++ project that you want to create a Sandbox from.
3 Click Source Control. The Create Sandbox Wizard displays.
4 Create a Sandbox as described in the Integrity User Guide.
5 To add the project members to the Sandbox, select the Populate Sandbox option.
108
Checking In Members
To check in members in Visual C++
1 In Visual C++, select one or more files to check in.
2 Select Project > Source Control > Check In. A list displays, showing all files that can be checked in.
3 Select one or more files to check in.
4 Click OK. The Check In dialog box displays.
5 Check in each member as described in the Integrity User Guide.
109
C H A P T E R TE N
Microsoft Project 10
The Integrity to Microsoft® Project integration combines the powerful project management
features of Microsoft Project 2003, 2007, and 2010, with the flexible workflow of Integrity, allowing
project managers to track and monitor project status, cost, and readiness, as well as potential
associated risks.
The Integrity2009_MSProject2003_Integration.zip and
Integrity2009_MSProject_Client_Template.zip files are available for download from the
Integrity Support Center (http://www.ptc.com/support/integrity.htm).
To help you set up and use the integration, the following topics are included:
“Overview” on page 111
“Before You Start” on page 111
“Pre-installation Administration” on page 114
“Installing the Microsoft Project Integration” on page 117
“Repairing or Removing the Integration” on page 119
“Microsoft Project Configuration” on page 119
“Using the Microsoft Project Integration” on page 123
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
110
Overview
The Microsoft Project integration works through an add-in component that provides access to the
available functionality through the Microsoft Project Tools menu. The integration supports:
Creation of new Integrity items from Microsoft Project tasks
Creating a new item from a task adds more detail to a task, such as a history of state changes,
attachments, related items, and change package information. Using the Synchronize All Tasks
command, you can automatically create items based on existing tasks in Microsoft Project. A
hyperlink to the Integrity item also displays next to the Microsoft Project task. Once an item is
created, you can track and monitor the item’s state changes by synchronizing the task in
Microsoft Project.
Creation of new Microsoft Project tasks from existing Integrity items returned in a query
Synchronizing by query adds the individual Integrity items as task items in the Microsoft
Project file. The Synchronize Tasks By Query command essentially populates the Microsoft
Project file with items defined only in the target Integrity query. For each item found in the
Integrity query, the integration creates a task in Microsoft Project.
Synchronization of selected or linked tasks
Maintaining synchronization between Integrity and Microsoft Project is carried out using
either the Synchronize Linked Tasks or the Synchronize Selected Tasks commands.
Using the Synchronize Linked Tasks command, Integrity publishes and retrieves updates for all
tasks in the Microsoft Project file that have been linked between Integrity and Microsoft
Project. Linked tasks are those tasks that have been previously synchronized between
Integrity and Microsoft Project.
Using the Synchronize Selected Tasks command, selected linked tasks are updated with the
information from Microsoft Project, and selected unlinked tasks are added and linked to
Integrity.
Conflict detection for resources or field contents
Conflict detection operates in cases where a change is entered for the field contents or
resources (assigned users) associated with a task in Microsoft Project, and different
information is entered for the linked item in Integrity. The integration provides the Conflict
Detected dialog box to help you resolve the identified differences.
111
Integrity Server Requirements
General requirements for the Integrity Server are as described in the Integrity Server Installation
and Configuration Guide. The Integrity Server must be configured to accept remote API
connections (see “Configuring the Integrity Server” on page 114).
Integrity database requirements are as described in the Integrity Server Installation and
Configuration Guide.
The Integrity Server has Integrity for Application Lifecycle Management (ALM) installed. For
more information, see “Installing the Integrity ALM template” on page 116.
The required XML mapping template is installed.
Client Requirements
NOTE To use the Microsoft Project integration, users do not require the Integrity Client.
Integration Components
The Microsoft Project integration is available for download from the Integrity Support Center
(http://www.ptc.com/support/integrity.htm). The Microsoft Project integration includes the
following components (available as ZIP files):
Integrity2009_MSProject2003_Integration.zip—the Integrity to Microsoft Project
Integration install (with Setup Wizard), including the MKSProjectTemplate.mpt Project
template.
Integrity2009_MSProject_Client_Template.zip—the XML mapping templates that
configure the integration.
Sample mapping templates work with the Application Lifecycle Management solution and
are available for download from the Integrity Support Center.
112
Assumptions
You know how to use Microsoft Project. For more information about using the product, refer
to the appropriate documentation from the product vendor.
You are using one of the sample XML mapping templates and have installed ALM 2009 on
your system.
If you are modifying the XML mapping template, you understand and can use XML.
You have made any required modifications to the internal field values in the XML mapping
template to reflect the ALM installed field name. For example, if you installed ALM with a
prefix, that same prefix is present in the internal field values contained in the XML mapping
template. For general information on configuring the XML mapping template, see
“Configuring a Mapping Template” on page 188. For more detailed information, contact
PTC-Integrity Support.
Key Considerations
For existing linked tasks, changes to the task/sub-task hierarchy cannot be made from within
Integrity. Any changes to the task/sub-task hierarchy must be made in the project file from
within Microsoft Project.
The Microsoft Project integration does not support commas (,) in user names. Commas
contained in user names are changed to spaces. Semi-colons (;), and open and closed brackets
are supported in the integration.
The Microsoft Project integration does not set the following fields:
Constraint Type
Request/Demand
Resource Type
Status
Work Contour
These fields are read-only and therefore Integrity cannot change the values directly. Other
fields (such as Start Date, Finish Date, or Status) can indirectly drive the values for these
fields.
NOTE To avoid errors, read-only fields should be set to the direction value of in. If a read-
only field is set to a bidirectional value (both) or the value of out, the resulting error is
recorded in the log file.
If you are working with two Microsoft Project files that contain shared items in Integrity,
running synchronizations with both projects open at the same time does not synchronize
information across the project files. All projects are handled independently by the integration.
Conflict detection may not function correctly when the Integrity Server and the database
reside on separate machines, and clocks for the two machines are not in sync. In this situation,
conflict detection errors can occur if an item modification timestamp pre-dates an item
creation timestamp.
To ensure that conflict detection works correctly, use a clock synchronization utility to keep
the two machine clocks in sync.
When entering data, Microsoft Project includes a known limitation of 255 characters for text
fields, outline code fields, and for values and characters in Enterprise Resource Multi-Value
(ERMV) fields. For fields containing more than 255 characters, Microsoft Project truncates the
113
data and adds an ellipsis (…). A Microsoft Project Notes field can hold more than 255
characters; however, a Notes field only displays a maximum of 255 characters before
truncation occurs.
To avoid having truncated data exported to Integrity, consider the following:
If you routinely have data in excess of 255 characters, only synchronize from Integrity to a
Notes field in Microsoft Project. Avoid performing bidirectional synchronizations.
If you need to synchronize data bidirectionally, map the Project Notes field to a
255-character text field in Integrity. If necessary, use an Integrity event trigger for editing
operations to copy only the first 255 characters from the Integrity field to the Project Notes
field.
For more information on the 255 character limit in Microsoft Project, refer to Microsoft’s
product documentation.
For purposes of running the Microsoft Project integration, only Integrity 2007 or greater can
connect to Integrity Server 2009. Older versions of the Microsoft Project XML mapping
templates (for example, MSprojint.xml for Integrity 2006) are not supported with Integrity
2009.
Pre-installation Administration
Before users can install and use the Microsoft Project integration, an administrator with access to
the Integrity Server must carry out certain configuration tasks for both the Integrity Server and
Integrity. Pre-installation administration tasks include configuring the Integrity Server to allow
for remote API connections and installing the Integrity ALM template. Depending on the
Microsoft Project fields used in your organization, the administrator may also need to modify the
XML mapping template that configures the integration.
This section provides the following information on the required pre-installation administration
tasks:
“Configuring the Integrity Server” on page 114
“Configuring Integrity” on page 115
“Setting Permissions” on page 116
“Modifying the Integration XML Mapping Template” on page 116
Before users can work with the Microsoft Project integration, the administrator must configure the
Integrity Server to allow remote API connections. This configuration sets the connection policy for
a server integration point.
The two policies that control API access to the Integrity Server are the connection and
authentication policies. Settings for these policies are specified in the following file on the Integrity
Server:
<installdir>/config/client/IntegrityClientSite.rc
where <installdir> is the path to the directory where you installed the Integrity Server.
114
The required settings for these policies depend on your integration point; however, defaults are
set for the server integration points. For the Microsoft Project integration, changes are required to
the connection policy only. No changes are required for the authentication policy settings.
Connection Policy
Within the IntegrityClientSite.rc file, the default connection policy is specified by the
following property:
daemon.connectionPolicy=mks.ic.common.policy.
ICAllowSpecificConnectionPolicy
The default setting allows only a specific set of IP addresses to connect. The required setting
allows remote API connections.
where <installdir> is the path to the directory where you installed the Integrity Server.
2 Comment out the default policy (that is, insert the # symbol), and then uncomment the
following property:
daemon.connectionPolicy=mks.ic.common.policy.
ICAllowAllConnectionPolicy
TIP When you uncomment a property (by removing the # symbol), you enable the required
property.
This allows all clients to request an API connection; however, all connecting clients still
require the proper authentication.
If there is a requirement to specify individual users who are allowed to connect, use a comma-
delimited list of the user IDs to define the property for daemon.validUsersList. Using a
comma-delimited list does not change the connection policy setting.
3 Save and close the file.
4 To have the changes take effect, restart the Integrity Server.
NOTE For more information on configuring the Integrity Server to allow remote API
connections, see the Integrity Integrations Builder API Guide.
Configuring Integrity
This version of the Microsoft Project integration provides improved flexibility for configuring the
integration. You can set up the basic configuration using the Integrity ALM template. The sample
XML mapping templates work with the types that are defined for ALM.
As an alternative, the basic configuration can be extended and modified to suit the workflows and
types used for projects within your organization. To create a custom configuration for the
Microsoft Project integration, contact PTC-Integrity Support.
The next step in setting up the integration is to configure Integrity by installing the Integrity ALM
template.
115
Installing the Integrity ALM template
You install the Integrity ALM template using the Integrity Administration Client. Before
beginning the installation, refer to the Integrity Administration Client online help for detailed
instructions.
IMPORTANT
Ensure that the internal field values in the XML mapping template reflect the Integrity field
names as installed for your workflow or ALM installation. For example, if you installed
ALM with a prefix, ensure that the same prefix is present in the internal field values
contained in the XML mapping template. For information on configuring the XML
mapping template, see “Configuring a Mapping Template” on page 188. For more detailed
information, contact PTC-Integrity Support.
For more information on working with Integrity ALM, see the documentation included
with the ALM solution download, available from the Integrity Support Center:
http://www.ptc.com/support/integrity.htm
To install the ALM template for use with the Microsoft Project integration, note the following
important information:
Before installing the ALM template, it is important that you back up your Integrity Server
database. Follow the database vendor’s recommended procedures for performing the backup.
To begin the installation, right click the Workflows and Documents node in the tree pane, and
select Install Solution from the shortcut menu. The Solution Installer wizard takes you through
the rest of the installation process.
During the installation, make sure to map the listed Group and User roles to existing groups
and users in your organization.
Setting Permissions
The integration user must have a valid user ID in the realm and must be allowed the ViewAdmin
permissions under the mks:im access control list (ACL). For more information on configuring ACL
permissions, see the Integrity Server Installation and Configuration Guide.
The Microsoft Project integration is based on a configurable XML mapping template. The
following sample XML mapping templates are pre-configured to allow you to use all the
supported features of the Microsoft Project integration:
MS_Project_ALM_Test_Objective.xml.sample
MS_Project_ALM_Work_Items.xml.sample
The mapping templates work with Integrity for Application Lifecycle Management and are
available for download from the Integrity Support Center.
By default, the XML mapping template is structured to work with the types installed with
Integrity ALM. You can also create additional XML mapping template files to support multiple
workflows for different Microsoft Project files. Each mapping template you create must have a
unique ID.
116
If you need to modify the existing mapping template or create additional templates, contact PTC-
Integrity Support. For general information on modifying the XML template, see “Configuring a
Mapping Template” on page 188.
IMPORTANT If you need to work with additional features, such as date fields, contact
PTC-Integrity Support for assistance.
where <installdir> is the path to the directory where you installed the Integrity Server.
2 Rename the files to remove the .sample extension, and then modify the XML mapping fields
as required to correspond to your existing workflow or ALM installation. Ensure that the
internal field values used in the XML mapping template correspond to the Integrity field
names as installed for your existing workflow or ALM installation.
117
4 By default, the following folder is specified:
C:/Program Files/MKS/Microsoft Project Integration
To specify another directory for the installation, click Browse and choose the target directory.
To determine the amount of disk space required for the installation, click Disk Cost. The Disk
Space dialog box summarizes information on the Volume, Disk Size, Available, and Required
disk space. To return to the Setup Wizard, click OK.
5 On the same panel, you can also configure the option that allows access to the integration
while using Microsoft Project. To allow access to yourself only, select Just Me. To allow access
to anyone using your computer, select Everyone. By default, the option is set to Just Me.
6 To continue, click Next. The Confirm Installation panel displays.
7 To start the installation, click Next. The Installing Panel displays, indicating the progress for the
installation. When the installation is complete, the Installation Complete panel displays.
8 To exit the Setup Wizard, click Close.
IMPORTANT The Microsoft Project integration uses certain files installed with the .NET
Framework. Use the Microsoft Windows Update site at windowsupdate.microsoft.com to
check for any critical updates to the .NET Framework.
9 From the common directory you unzipped to, copy the MKSProjectTemplate.mpt file to the
Microsoft templates directory on the machine using the integration. On Windows, this
directory is:
C:/Documents and Settings/<username>/Application Data/
Microsoft/Templates/
You can now open Microsoft Project and configure the required Microsoft Project properties.
For more information, see “Microsoft Project Configuration” on page 119.
118
Repairing or Removing the Integration
You can use the Setup Wizard to repair or remove the Microsoft Project integration.
TIP You can also remove the Microsoft Project integration using Windows Start > Control
Panel > Add or Remove Programs.
To repair or remove the Microsoft Project integration using the Setup Wizard
1 Ensure that you close Microsoft Project before attempting to repair or remove the integration.
2 From the Project-Integration ZIP file, extract and run the setup.exe file. The Setup Wizard
displays.
3 Select one of the available options as required:
To repair the integration with Integrity, select the option for Repair Integrity to Microsoft
Project Integration.
To remove the integration with Integrity, select the option for Remove Integrity to Microsoft
Project Integration.
4 To continue the selected operation, click Finish. The integration with Integrity is repaired or
removed, according to the option you selected.
To use the integration with Microsoft Project, certain custom properties are configured for each
project file you are working on. The required custom properties are created automatically when
you run the first synchronization operation. The required integration properties are configured
under select File > Properties.
IMPORTANT The MKS Integration ID property is automatically generated after the first
synchronization. It includes a unique identification key and has the form:
project name.mpp:identification key
Do not modify this automatically generated property.
119
The following properties are automatically configured for each Microsoft Project .mpp file when
you run a synchronization with Integrity:
MKS Integrity Server Number Port number used by Integrity to connect to the Integrity Server.
Port By default, the port number is 7001. Check with the administrator to
confirm the correct port number.
MKS Template Name Text By default, references the integration XML mapping template
installed on the Integrity Server.
The mapping template is configured to use the supported features of
the Microsoft Project integration. You can also modify the template to
suit the workflows and types used for your projects. For more
information on modifying the template, see “Modifying the Integration
XML Mapping Template” on page 116.
Note: This property can also be set to reference another template
file.
The integration also requires certain custom fields to work with the default template installed
with Integrity. The required custom fields are pre-defined in the MKSProjectTemplate.mpt
template file provided with the integration. To use the Integrity template, you must copy the
MKSProjectTemplate.mpt file to the Microsoft templates directory on the machine using the
integration. Once this step is completed, the required fields are created dynamically if they do not
already exist.
The custom project fields include:
MKS User ID User name of the user in Integrity. This is the login ID rather than the full
name.
Column displayed automatically on the Resources Sheet view when using the
MKSProjectTemplate.mpt file as the template.
MKS Issue Type Type of item in Integrity. In the default configuration, this is one of Project,
Requirement, Test Objective, Test Plan, Work Item, Feature, or
Task.
Column displayed automatically when using the MKSProjectTemplate.mpt
file as the template.
MKS State Initial state for items of the defined type. Field is visible in Integrity, but no
column displays in Microsoft Project.
Note: To view Integrity state information in Microsoft Project, you must create
a new column for MKS State.
Important: Once you create the MKS State column, all tasks must have a
valid initial state for the associated Integrity items of that type. If no valid initial
state exists for the type, an error occurs during all subsequent
synchronizations.
120
Integrity Custom Project Field Description
MKS Effort Pick list field with options of Small, Medium, Large, and Very Large.
Information is published from Integrity to Microsoft Project only. Column not
displayed by default.
To display the column in Microsoft Project, select a task view and choose
Insert > Column. In the Column Definition dialog box, select MKS Effort
from the Field Name list.
MKS Risk Pick list field with options of Low, Medium, and High. Information is published
from Integrity to Microsoft Project only. Column not displayed by default.
To display the column in Microsoft Project, select a task view and choose
Insert > Column. In the Column Definition dialog box, select MKS Risk from
the Field Name list.
MKS Requirement ID Is the content of the External ID field in Integrity. Information is published
from Integrity to Microsoft Project only. Column not displayed by default.
To display the column in Microsoft Project, select a task view and choose
Insert > Column. In the Column Definition dialog box, select MKS
Requirement ID from the Field Name list.
When using the Integrity integration with Microsoft Project, you can choose a Secure Sockets
Layer (SSL) connection. To configure SSL for the Microsoft Project integration:
1 Open the Microsoft Project (.mpp) file and select File > Info > Project Information > Advanced
Properties.
2 Click the Custom tab and in the Name field, add a property for MKS SSL Connection.
3 In the Type field, select Yes or no. In the Value field, choose the Yes option. To accept the changes
click Add and then OK.
4 Save and re-open the .mpp file. The SSL connection to Microsoft Project is now enabled. For
Microsoft Project, SSL communications are enabled on a per-session basis, therefore, if you
close Microsoft Project, you must reset the MKS SSL Connection property to use secure
communications when you start a new session. To deactivate SSL during the same Project
session, you can set MKS SSL Connection to No.
NOTE To use an SSL connection with the Microsoft Project integration, you must also
enable SSL communications for the server-side API. The API authenticates its session via a
separate HTTP connection to the Integrity Server. To allow this authentication to use the
SSL connection, the Certificate Authority associated with the SSL certificate must be
registered with the JRE used by the Integrity Server.
Microsoft Project Server stores a pool of Enterprise Resources. To make use of Enterprise
Resources within a project, they must first be imported into the project file. In Microsoft Project
Server, this is done either through the menu action for Insert > New Resource From > Project Server or
through the menu action for Tools > Build Team from Enterprise. Once imported into the Microsoft
Project file, the Enterprise Resources are treated as normal resources for purposes of editing the
project.
The mechanism for linking Integrity users with resources in Microsoft Project is based on a
required custom resource field (MKS User ID). The MKS User ID field provides the link between
the two systems and allows the Microsoft Project resource to own the resource field for purposes
121
of representation, reporting, and control. The Integrity user identifier (as based on the user’s
Integrity logon) is expected to exactly match the value in the MKS User ID custom resource field.
This custom field exists in the MKSProjectTemplate.mpt, but can be added to any project file as a
custom text field for resources.
To make use of the Microsoft Project Server Enterprise Resources, you must edit and record the
Integrity user ID information with those resources. When this information is imported into the
Microsoft Project file, it is represented by the MKS User ID field. For more information on working
with Enterprise Resources in the Integrity integration, contact PTC-Integrity Support.
NOTE The Integrity Synchronize Resources operation pre-loads the Microsoft Project file
with resources from the Integrity user base and also populates the custom MKS User ID
field. To make use of Enterprise Resources in a synchronization operation, resources in the
Microsoft Project file must have user information populated in the MKS User ID field.
Whether the information is populated automatically or manually, is a matter of preference.
3 In the created custom text field, enter the Integrity user ID for each Enterprise user. Save these
resources back to the Microsoft Project Server resource pool.
4 Insert the Enterprise Resources into the Microsoft Project file.
5 If required, rename the created custom text field to MKS User ID. This step is not required if
you are using the MKSProjectTemplate.mpt and you used Text20 as the custom field in step 2.
6 You can now synchronize tasks between Microsoft Project and Integrity.
Logging Configuration
To enable logging for the Microsoft Project integration, you must add the MKS Enable Logging
custom property for each project file you are working on. By default, the MKS Enable Logging
property is set to No and logging is not activated.
The MKS Enable Logging custom property is configured in the .mpp file by selecting
File > Properties. Once enabled, log and error messages are sent to <temp dir>/projint.log on the
machine running the integration.
122
6 Save and re-open the .mpp file. Log and error messages are sent to <temp dir>/projint.log
file and can be checked to assist with any diagnostic work.
Linked tasks are those tasks that have been previously synchronized between Integrity and
Microsoft Project. Unlinked tasks are tasks or items that exist either in Microsoft Project or
Integrity and have not yet been synchronized through the integration. When a task is linked, the
MKS Issue ID displays in the MKS Issue field of the task. When a synchronization is complete, the
Microsoft Project status bar displays Ready.
IMPORTANT Ensure that the date format used in your Microsoft project file matches the
default Microsoft Project date format—month/day/year. If you need to use another date
format, contact PTC-Integrity Support for assistance.
Prior to a synchronization, you can link tasks manually by entering the MKS Issue ID number in
the MKS Issue field. For any new tasks that are not linked in this way, Integrity creates a new
Integrity item when the next synchronization runs.
Integration functionality is accessible through the Microsoft Project Tools menu, allowing you to
synchronize linked tasks, selected tasks, tasks in a single Integrity query, all tasks, and resources.
The integration also provides conflict detection to help you resolve conflicts in the case of field
content and assigned resources (users).
IMPORTANT For task related synchronization, you must be in a task oriented view.
Synchronizing resources is independent of the view.
123
also have a date. Wherever the Integrity item contained an empty date field, the created
Microsoft Project task will have no date.
Where Microsoft Project task contains a valid date and the corresponding Integrity item has
an empty date field, a synchronization will populate the Integrity item with the date
information from the Microsoft Project task.
Where a Microsoft Project task was previously populated with a date from an Integrity item
and that date is removed in the project file but remains in the Integrity item, a synchronization
will cause the Microsoft Project task to be repopulated with the date information from the
Integrity item.
Key Tasks
The primary steps for using the integration are:
“Specifying Task Types” on page 124. This task includes specifying tasks types using the
MKS Issue Type custom project field.
“Setting Task Relationships” on page 125. This task includes setting task relationships using
the outline level in Microsoft Project.
“Synchronizing Resources” on page 126. This task includes synchronizing project resources
(or users) using the Synchronize Resources command.
“Synchronizing All Tasks” on page 126. This task includes publishing task items from an
existing Microsoft Project to Integrity using the Synchronize All Tasks command.
“Synchronizing Tasks By Query” on page 126. This task includes publishing items from an
existing Integrity query to Microsoft Project using the Synchronize Tasks By Query command.
Each item from the query is linked to a task in Microsoft Project to create a new project.
“Synchronizing Linked Tasks” on page 127 and “Synchronizing Selected Tasks” on page 127.
These tasks include maintaining the status of items in Microsoft Project and Integrity using
the Synchronize Linked Tasks and Synchronize Selected Tasks commands as required.
“Detecting Conflicts” on page 128. This task includes resolving any conflicts detected during
synchronizations.
When creating a task in Microsoft project, you specify the type of Integrity item (for example
Project, Requirement, Test Objective, Test Plan, Work Item, Feature, or Task,) using the
MKS Issue Type custom project field. Once the task is assigned to a type, the next synchronization
creates that task as an item of the specified type in Integrity. The mapped fields are then
dependent on this type.
The MKS Issue Type custom project field is displayed automatically in Microsoft Project when
using the MKSProjectTemplate.mpt file as the template. For more information on custom project
fields, see “Integrity Custom Project Fields” on page 120.
NOTE Using the default template, the MKS Issue Type is a required field. If you are not
using the pre-configured MKSProjectTemplate.mpt file, you must create this field
manually.
124
To specify the type of task using Microsoft Project
In the Microsoft Project file, create the required line items for the tasks. In the MKS Issue Type
column, enter the type that will be used for the linked item in Integrity (for example, Project,
Requirement, Test Objective, Test Plan, Work Item, Feature, Task). Run the required
synchronization—Synchronize All Tasks or Synchronize Selected Tasks—to publish the information to
Integrity. For more information, see “Synchronizing All Tasks” on page 126 or “Synchronizing
Selected Tasks” on page 127.
The tasks are created as items of the specified types in Integrity.
When manually adding tasks in Microsoft Project, you can create relationships between tasks
using the outline level. To relate tasks, you set the main task at the top outline level and indent the
related subtasks as required. Each task is indented one additional level to the task it is related to.
In Microsoft Project, the outline level is controlled through Project > Outline > Indent or Outdent. For
more information, refer to the documentation provided with Microsoft Project.
Once the parent/child relationships are set using the outline level in Microsoft Project, the next
synchronization creates the specified relationships between the items in Integrity. Integrity maps
task relationships downward through the hierarchy. The relationships are then shown when you
view the linked item in Integrity.
IMPORTANT If the integration is configured for the default ALM solution as outlined in this
guide, the relationship hierarchy cannot be changed from within Integrity once the
relationship hierarchy is set in Microsoft Project and a synchronization is run to link with
items in Integrity. Custom configurations can be created to allow greater flexibility.
For example, if you set the following hierarchy of relationships, running a synchronization that
links to items in Integrity:
Requirement 1
Feature 1
Feature 2
Requirement 2
and then from Integrity attempt to change the hierarchy to:
Requirement 1
Feature 1
Requirement 2
Feature 2
The relationship hierarchy in Microsoft Project is not updated. To change the relationship
hierarchy, you must make the required changes through Microsoft Project.
125
The corresponding relationships are created for the linked items in Integrity.
NOTE For information on valid relationships, see the documentation included with the
ALM solution download, available from the Integrity Support Center at:
http://www.ptc.com/support/integrity.htm
Synchronizing Resources
The Synchronize Resources command publishes resources to both Microsoft Project and Integrity
and ensures that resources (users) are created/updated in the project file, and updated in
Integrity. If the Integrity user does not have a full name, the MKS User ID is used as the resource
name. If a full name is later added in Integrity, the resource name is updated to the full name in
the next synchronization.
IMPORTANT Before performing any other synchronizations, you must first synchronize
resources (users) for the project. If you add resources before synchronizing, those resources
are included as entries in addition to the resources provided through the synchronization.
You can delete the unwanted resources by selecting the associated resource number, right
clicking, and choosing Delete Resource from the shortcut menu.
To synchronize resources
From the Microsoft Project menu, select Tools > Synchronize Resources. Enter the Integrity Server
and Connection Details if prompted, and from the list, choose the XML mapping template
Details
you want to use. A connection to Integrity is opened and all resources are synchronized. The
Microsoft Project status bar displays Ready to indicate the synchronization is complete.
TIP You can also link resources manually by entering the user’s login ID in the MKS User ID
field.
The Synchronize All Tasks command essentially allows you to populate Integrity with task items
defined only in the Microsoft Project file. For each task item in Microsoft Project, the integration
creates an item in Integrity, or updates the item if the task is already linked.
The Synchronize Task By Query command allows you to synchronize tasks based on a defined
Integrity query. Synchronizing by query adds the individual Integrity items as task items in the
Microsoft Project file. The Synchronize Tasks By Query command essentially populates the Microsoft
Project file with items defined only in the target Integrity query. For each item found in the
Integrity query, the integration creates a task in Microsoft Project.
126
You can use this command to start a new .mpp file based on an existing query in Integrity. For
example, for a query based on a specific type—All Features—you could create new project file
that included all items of the type Feature found by the Integrity query.
NOTE When synchronizing Integrity items with Microsoft Project, new resources are
created and assigned to the linked tasks, if the items have users (resources) that do not
already exist in Microsoft Project.
When you perform a synchronization of linked tasks, Integrity publishes and retrieves updates for
all tasks in the Microsoft Project file that have been linked between Integrity and Microsoft Project.
Linked tasks are those tasks that have been previously synchronized between Integrity and
Microsoft Project. Unlinked tasks are tasks or items that exist either in Microsoft Project or
Integrity and have not yet been synchronized through the integration. When a task is linked, the
MKS Issue ID displays in the MKS Issue field of the task.
When synchronizing linked tasks, you do not need to select every task in a set of relationships. If a
relationship is mapped (as to predecessor, successor, outline parent, or outline children), Integrity
automatically selects the related tasks, and new, related tasks are created in Integrity as required.
NOTE Prior to a synchronization, you can link tasks manually by entering the MKS Issue
ID number in the MKS Issue field. For any new tasks that are not linked in this way,
Integrity creates a new Integrity item when the next synchronization runs.
The Microsoft Project integration includes functionality that allows you to synchronize selected
project tasks, whether those tasks are linked or unlinked. When synchronizing selected tasks, you
highlight the project tasks you want to synchronize, run the Synchronize Selected Tasks operation
and the selected tasks are published to Integrity.
Using the Synchronize Selected Tasks command, selected linked tasks are updated with the
information from Microsoft Project, and selected unlinked tasks are added and linked to Integrity.
127
When synchronizing selected tasks, you do not need to select every task in a set of relationships. If
a relationship is mapped (predecessor, successor, outline parent, or outline children) Integrity
automatically selects the related tasks, and new, related tasks are created in Integrity as required.
Detecting Conflicts
Conflict detection operates in cases where a change is entered for the field contents or resources
(assigned users) associated with a task in Microsoft Project, and different information is entered
for the linked item in Integrity. The integration provides the Conflict Detected dialog box to help
you resolve the identified differences.
128
129
C HAPTER E LEVEN
Microsoft Word 11
This chapter provides information on the Integrity integration with Microsoft® Word as installed
with the MKSWordImporterSetup.msi installer available for download from the Integrity Support
Center as part of the MKSIntegrity2009-2007_SP6_MSWord2003_Integration.zip file.
This chapter is intended only for users who are using the Word integration that is installed with
the MSI installer, and who want to export requirements from Word documents into Integrity. The
instructions provided here do not apply to the new Integrity Client functionality for editing items
and documents in Microsoft Word.
NOTE For information on the new Integrity Client functionality for editing items and
documents in Word (including embedded objects and quick export of items/documents to
Word format), see the MKS Gateway User Guide.
This Integrity integration with Microsoft Word provides support for rich content in Word
documents. The integration is intended to work with Integrity for Requirements Management
2007 or Integrity for Application Lifecycle Management 2009.
This chapter includes the following topics:
“Assumptions” on page 131
“Overview of the Integration” on page 131
“System Requirements” on page 133
“Configuring the Integrity Server” on page 133
“Installing and Uninstalling the Integration” on page 134
“Customizing the Word Integration” on page 135
“Exporting Word Documents to Integrity” on page 141
“Troubleshooting” on page 143
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
130
Assumptions
Before you use the Word integration, PTC assumes that you fully understand the following:
the hardware platform and Windows operating system you are installing the Integrity Client
on
Integrity for managing workflows and documents
Integrity for Requirements Management or Integrity for Application Lifecycle Management
Microsoft Word
If you are customizing the Word integration, you should have a working knowledge of XML
mapping files and the MCFG file used for the Word integration, as well as knowledge of XSLT.
NOTE To ensure an accurate conversion, your Integrity workflow must be consistent with
the DSD. For example, if a type has a mandatory field in the workflow, it must also be
mandatory in the DSD.
To export Word documents that include rich content (tables, embedded images, and formatted
text), the data is converted to HTML, then mapped to rich content fields in Integrity items. In
Integrity, rich content is expressed using a limited set of HTML elements and attributes. For more
information, see “Rich Content Support” on page 131.
NOTE Rich content fields are supported only with Integrity for Requirements Management.
Exporting a Word document containing rich content to the Application Lifecycle
Management (Process) Solution does not preserve the rich content formatting.
The Word integration is subject to rules for user and group visibility, editability, and relevance for
fields in the target Integrity item type you are exporting to. For more information, contact your
Integrity administrator.
131
embedded images
embedded OLE objects
For the complete list of HTML elements and attributes supported in Integrity, see the Integrity
User Guide. Unsupported HTML elements and attributes in the document are silently discarded
when new items are created.
Headings
Headings are mapped from the available Word heading styles (Heading1 to Heading 9) to the
available HTML heading tags (h1 to h6). Headings that extend beyond Heading 6 are converted to
h6.
Correctly defined numbered headings (i.e. numbered sections) remain as headings. If incorrectly
defined in Word, numbered headings are converted to lists.
If you include a table of contents in your document, page numbers are appended to the end of
headings instead of retaining the spacing between the heading and page number, for example, 1)
Title Page......1 displays as 1) Title Page1.
Lists
Numbered and bulleted lists are supported.
Tables
Irregularly shaped cells (L-shaped) are unsupported.
Embedded Objects
The integration exports an image snapshot of the embedded object and the object itself. If the
embedded object is exported into a rich content field, you can edit the embedded object. The
Integrity Document view allows you to edit the embedded item via an external application.
Embedded Images
The Word integration supports EMF (Windows Metafile), GIF, JPG, and PNG image formats in
Word documents. EMF images are converted to PNG format in the new items. Autoshapes and
WordArt in Word documents are not supported.
Hyperlinks
Hyperlinks in the Word document are preserved.
132
System Requirements
For the integration to work effectively, you must have the following installed and configured
correctly:
Integrity Server, configured to allow API connections. For more information, see
“Configuring the Integrity Server” on page 133.
Microsoft Windows XP Professional/Vista Business or Enterprise.
Integrity Client 2007, 2009, or 10.
Microsoft Word 2003 Service Pack 2, Word 2007, or Word 2010.
NOTE Although the integration supports Word 2003 and 2007, the integration requires
documents saved in Word 2007 (DOCX) format. If you are exporting a Word document that
is not in Microsoft Word 2007 (DOCX) format, the integration prompts you to save a copy of
the document in DOCX format. To save Word 2003 documents in DOCX format, the Microsoft
Office Compatibility Pack must be installed, which you can download from:
http://go.microsoft.com/fwlink?LinkID=77512.
If not currently installed on your system, the following components must be installed before you
run the integration installer:
Microsoft .NET Framework 2.0 and 3.0
NOTE The Word integration uses the Microsoft .NET framework. PTC recommends
running Windows Update to check for any critical updates to the .NET framework.
Microsoft Visual Studio 2005 Tools for Office Second Edition runtime
Microsoft Visual Studio 2005 Tools for Office Language Pack
Windows Installer 3.1
Microsoft Office 2003/2007 Primary Interop Assemblies
You can download these components from http://www.microsoft.com or run the Microsoft
Office installer and select them during the install.
133
To set the Integrity Server connection policy
1 In a text editor, open the IntegrityClientSite.rc file.
2 Comment out the following default policy:
daemon.connectionPolicy=mks.ic.common.policy.
ICAllowSpecificConnectionPolicy
TIP To comment out a policy, insert a # symbol as the first letter of the property.
To uncomment a policy, remove the # symbol.
This allows all clients to request an API connection; however, all connecting clients still
require the proper authentication.
If there is a requirement to specify individual users who are allowed to connect, use a comma-
delimited list of the user IDs to define the property for daemon.validUsersList. Using a
comma-delimited list does not change the connection policy setting.
4 To have the changes take effect, restart the Integrity Server.
NOTE For more information on configuring the Integrity Server to allow remote API
connections, see the Integrity Integrations Builder API Guide.
NOTE The Word integration provided with Integrity 2006 is no longer supported. If you
have this earlier version of the integration, uninstall it before installing the later
integration. For information on uninstalling the earlier Word integration, refer to the
original product documentation.
2 In the temporary directory, run setup.exe. The MKS Word Document Importer Setup Wizard
displays.
3 To continue, click Next. The Select Installation Folder panel displays. Accept the default path
location or specify another location by browsing or typing the path of the directory where you
want to install the integration.
4 Click Next. The Confirm Installation panel displays.
134
5 To start the installation, click Next.
6 Once the integration is successfully installed, click Close to exit.
The name.txt file, containing the title name that displays in the Document Structure Definition list
in the Export to MKS Integrity Wizard.
The static.txt file, containing all definitions and properties for fields displayed in the Export
to MKS Integrity Wizard.
The process-items.xlst file, that translates the document and prepares it for export to
Integrity.
This section discusses the following topics:
“Customizing the DSD” on page 136
“Importing the DSD” on page 138
“Importing a Local DSD” on page 139
“Understanding the XML Mapping File” on page 140
“Understanding the Static TXT File” on page 139
“Understanding the Process Items XLST File” on page 141
135
Customizing the DSD
By default, the Word integration allows for the export of requirement documents into Integrity.
You can also create additional DSDs to use with different document types (or domains), for
example, specification, test, or input documents. This section describes how you can create a
custom DSD for other document types.
Once you have created a custom DSD for a new document type, the specified identifier will be
available for selection from the list in the Word Importer dialog box.
Sample XML mapping templates for use with the Word integration are included in the
Integrity2009_Server_Templates.zip file that is available for download from the Integrity
Support Center (http://www.ptc.com/support/integrity.htm).
Sample MCFG files are provided in the Integrity2009_MSWord_Client_Templates.zip, also
available for download from the Integrity Support Center.
You extract the sample XML mapping template files, including:
MS_Word_Requirements_Document.xml.sample
MS_Word_Test_Suite.xml.sample
to the following directory on the Integrity Server:
<Integrity Server installdir>\data\gateway\mappings\
The XML mapping template must be renamed to remove the .sample extension, and then
modified to reflect your workflow or ALM installation. The modified XML mapping template
then becomes your production mapping template for the Word integration.
TIP
The XML template file name should differentiate between the default template and the
custom one being created.
Ensure that the internal field values in the XML mapping template reflect the Integrity field
names as installed for your workflow or ALM installation. For example, if you installed
ALM with a prefix, ensure that the same prefix is present in the internal field values
contained in the XML mapping template.
For general information on modifying an XML mapping template, see “Configuring a
Mapping Template” on page 188. For more detailed information, contact PTC-Integrity
Support.
IMPORTANT Before making any modifications to your MCFG/DSD files, you should create
backup copies in a safe location.
136
If you have imported the MCFG file, it resides in:
C:\Documents and Settings\<username>\.mks\integrations
\Word30\RuleSets
NOTE The MCFG file is a ZIP file that can be opened and repackaged using a ZIP utility.
Copy the MCFG file to a temporary location and change the file extension from .mcfg to
.zip. You can then can extract the files using any ZIP utility.
3 Using a ZIP utility, extract the contents of the MCFG file, which includes mapping_name.txt,
name.txt, static.txt, and
4 Update the mapping_name.txt file with the name of the custom mapping template. For
example, if you are working with the MS_Word_Requirements_Document.xml.sample template,
you would add Microsoft Word Requirements Document as the mapping name.
5 Update name.txt with a new identifier. The specified identifier will be available for selection
from the list in the Word Importer dialog box.
To have this modified DSD to appear in the list with the default DSDs, change its name by
modifying the contained name.txt file. The name.txt file contains a single line of text
representing the name that will appear in the Document Structure Definition list in the export
wizard. If this DSD is going to replace an existing DSD file, you do not need to change its
name.
IMPORTANT By default, the name.txt file is read-only. Depending on your text editor, you
may need to set the file to read-write access to save your changes.
6 In the directory where you extracted the MCFG contents, open the static.txt file and in the
Category line, change the last (ninth) parameter to a comma separated list of the allowable
categories in the your document.
When editing the static.txt file, ensure that field relationship rules are respected.
IMPORTANT By default, the static.txt file is read-only. Depending on your text editor, you
may need to set the file to read-write access to save your changes.
For additional information on the static.txt file, see “Understanding the Static TXT File” on
page 139.
7 Save the files and re-package the MCFG file.
To re-package the MCFG file, select the required TXT files and add them to a ZIP archive in
the directory where you extracted the MCFG contents. Rename the ZIP file to change the
extension from .zip to .mcfg. If you want to replace the existing MCFG, give the re-packaged
file the same name as the original MCFG file.
8 After importing the DSD, you can export the defined document type to Integrity. For more
information, see “Importing the DSD” on page 138.
137
IMPORTANT
When rendering rich content, broken image links are displayed if Word cannot find the
following file in the DSD:
internal_attachments_name.txt
If internal_attachments_name.txt is not found, Word defaults to using RQ_Text
Attachments as the attachment field name for the rich content attachment links. This
default behavior causes the broken image links in the rich content.
To resolve this issue, you must add a file that contains the actual attachment field name
in the DSD (internal_attachments_name.txt). Ensure that the internal field values in
the DSD reflect the Integrity field names as installed for your workflow or ALM
installation. For example, if you installed ALM with a prefix, ensure that the same prefix
is present in the internal field values contained in the DSD.
If you were previously using the Word integration with an RM 2007-based solution and
the rich content field did not have RQ_Text Attachments mapped as the attachment
field, you must add the internal_attachments_name.txt file to the RM MCFG files
and ensure that the file contains the correct attachment field name. To add the
internal_attachments_name.txt file, follow the instructions for “Customizing the
Word Integration” on page 135.
The ALM 2009 MCFG files contain the internal_attachments_name.txt file. This file
uses the ALM_ prefix to illustrate where changes are required. You must modify the
contents of the internal_attachments_name.txt file if your ALM 2009 solution is
installed with no prefix or a prefix other than ALM_.
Once you have customized the DSD and re-packaged the MCFG, you can install and import the
modifications to the integration. Once imported, the defined DSDs are available to all Word
integration users.
IMPORTANT Before making any modifications to your MCFG/DSD files, you should create
backup copies in a safe location.
138
When importing a document using the modified DSD, the field values should now correspond to
the new values that you set in the static.txt file.
This DSD is available from the Document Structure Definition list when you export your
document(s).
The Word integration populates fields that are defined in the MCFG (or DSD files), and then
prompts for inputs from the user through the Export to MKS Integrity Wizard. The fields displayed in
the export wizard are called external fields, which in turn map to internal fields that are defined
within Integrity.
Each DSD file includes a static.txt file which contains all the definitions and properties for
fields used in the Export to MKS Integrity Wizard. For example, the Assigned User field is defined as:
Assigned User|Assigned User|String|true| User Name ||false|false|
User Name1,User Name2
The Project field is defined as:
Project|Project|String|true|/Release2|Project value to be used for all
items.|false|false|
The preceding line contains a number of properties for the Project field. For example, the Default
value property (that is, the 5th property—in the preceding example, this property has a value of
"/Release2") .
The line is separated into segments using the ‘|’ symbol. Each segment represents a property to
define the field as follows:
Display Name The field name displayed in the Export to MKS Integrity
Wizard interface.
139
Field Name Description
Hidden Boolean field. Field hidden from the user in Preview and
Results panels of the Export to MKS Integrity Wizard.
The mapping of external and internal fields is specified in the XML mapping file (for example, the
MS_Word_Requirements_Document.xml file). The XML mapping file allows the integration to
retrieve the required values from the correct locations.
Using the example of a System Requirement, the internal Assigned User field in Integrity would
be defined with the following mapping:
<map name="System Requirement">
<set-attribute name="rmtype" value="content" />
<field internal="Category"
direction="in"
on-create-only="true">
<default>System Requirement</default>
</field>
<field external="Summary"
internal="ALMText"
field-type="richcontent"
direction="in"
on-create-only="true"
required="true" />
IMPORTANT For fields that are mandatory in Integrity, you must define a default value in the
XML mapping template. If a mandatory field is left blank, the export operation fails.
140
Understanding the Process Items XLST File
The integration retrieves the value of a newly-created field through the process-items.xlst file,
as contained in the content folder of the DSD. The process-items.xlst file translates the
document and prepares it for export to Integrity.
For example, to configure the process-items.xlst file for Assigned User, add the following lines
under the <xsl:template name="OutputFields"> tag:
<mks:field>
<xsl:attribute name="name">
<xsl:value-of select="$assigned_user_key"/>
</xsl:attribute>
<xsl:value-of select="local-variables:stringValueOf($assigned_user_key)"/>
</mks:field>
These lines are used to retrieve the value of the Assigned User field. The variable
$assigned_user_key should be defined in the same file under the field variable declaration
segment and can be defined as:
<xsl:variable name="assigned_user_key" select="'Assigned User'"/>
NOTE Processing time and performance is affected by data size, network communication
between the client and server, and server load.
To export portions of a document currently open in Word, select the relevant portions,
then select MKS > Export Selection.
To export multiple documents not currently open in Word, select MKS > Export Multiple
Documents. The Select Documents for Export dialog box displays.
Select the documents you want to convert by clicking Add, then click OK.
141
2 From the Document Structure Definition list, select the DSD to parse the document.
3 Under Fields, complete or change the default field values. Mandatory fields appear red.
4 Do one of the following:
To apply the DSD to the document and see a preview, click Next or Preview in the left-hand
pane. A progress bar in the wizard indicates status. The Preview panel displays a preview
of the document as it would appear in the Outline panel of the Integrity Document view.
To skip the preview and view the final results, click Results in the left-hand pane and
proceed to step 7. The integration applies the DSD to the document and creates new items.
NOTE If you are exporting a Word document that is not in Microsoft Word 2007 (DOCX)
format, the integration prompts you to save a copy of the document. Click OK, then save
the document as a DOCX file.
5 In the Document pane, you can view the content by expanding and collapsing segments and
selecting items. Item content displays in the Item pane.
142
6 To create the items and view the final results, click Next or Results in the left-hand pane. The
Results panel displays.
7 The Results panel displays a summary of the document with icons to indicate the success ( )
or failure ( ) of exported items. Successfully exported items display item IDs.
The filter at the top of the wizard allows you to Show All or Show Errors.
NOTE You can copy the results to the clipboard by right-clicking on the tree or pressing
CTRL+C.
8 To close the wizard, click Close. If errors occurred, the integration displays which document(s)
did not successfully export. Click OK.
NOTE If the initial document submission fails, the next submission may attempt to reuse
any items that were successfully created the first time and merge them with the new items.
If you are exporting selections from a document, the integration does not attempt to reuse
and merge items. For more information, see “Troubleshooting” on page 143.
9 You can now switch to the Integrity Client to work with the new items.
Troubleshooting
Integrity provides two log files to troubleshoot errors. By default, the C:\Documents and
Settings\<user>\Local Settings\Temp directory contains the following log files:
143
C H A P T E R TW E L V E
Microsoft Excel 12
The Integrity to Microsoft® Excel® integration combines the powerful spreadsheet features of
Microsoft Excel 2003, 2007, and 2010 (Excel), with the flexible workflow of Integrity. Users can
work with Integrity item data in either product and keep the information in sync. This integration
can be used for any situation where Excel’s functionality might be useful, for example, for
gathering requirements or managing features for projects.
NOTE The Integrity integration with Excel uses XML functionality and therefore requires
Microsoft Excel 2003/2007 Office Professional Edition.
The integration also allows the import and export of requirement documents between Integrity
and Excel. Unstructured documents can be created in Excel and structure added using the
Integrity Document view. The integration works with both embedded and attached documents in
Integrity.
The integration ZIP file (MKSIntegrity2009&2007_SP3_MSExcel2003_Integration.zip) is
available for download from the Integrity Support Center (http://www.ptc.com/support/
integrity.htm). The integration ZIP file can be found under the Downloads tab.
To help you set up and use the integration, this chapter includes the following topics:
“Overview” on page 145
“Before You Start” on page 145
“Setting the Integrity Server Connection Policy” on page 147
“Installing the Microsoft Excel Integration” on page 147
“Repairing or Removing the Integration” on page 148
“Customizing the Microsoft Excel Integration” on page 149
“Using the Microsoft Excel Integration” on page 152
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
144
Overview
The Microsoft Excel integration uses the Excel data list (or table) to store Integrity data. The
integration supports users who need to use the features of Excel to manage and process data
stored within Integrity.
The integration allows you to use Integrity data within Excel to produce requirement documents,
reports, and charts, and to perform data analysis for project planning. Users can also import
Integrity data into an Excel sheet and publish data in an existing Excel sheet to Integrity.
An Excel data list comprises a series of rows containing related data. The integration works
through an add-in component that provides access to functionality through the Microsoft Excel
Data menu. The integration supports:
General requirements for the Integrity Server are as described in the Integrity Server Installation
and Configuration Guide.
Integrity database requirements are as described in the Integrity Server Installation and
Configuration Guide.
Integrity Server 2009 or Integrity Server 10.
145
Client Requirements
Microsoft Excel 2003 (Microsoft Office Professional Edition, Service Pack 2 or greater).
Microsoft Excel 2007 (Microsoft Office Professional Plus 2007).
Microsoft Excel 2010.
Microsoft .NET Framework 1.1 runtime with required service packs installed. If Microsoft
.NET Framework 2.0 or greater is installed, but version 1.1 is not, you cannot install the
integration. If .NET Framework 2.0 or greater is installed after version 1.1, there is no effect on
the integration.
Administrators require the Integrity Administration Client for configuring ACL permissions
and setting up Integrity workflows.
Users do not require the Integrity Client to use the Microsoft Excel integration.
Integration Components
CAUTION If you have previously modified the XML mapping template files, ensure that you
create backup copies of your modified templates before extracting any new template files
provided with this integration.
Assumptions
You know how to use Microsoft Excel. For more information about using the product, refer to
the appropriate documentation from the product vendor.
If you are modifying a mapping template, you understand and can use XML. If you need to
modify a template and do not understand XML, contact PTC-Integrity Support.
Key Considerations
If you are using an English version of Excel on a machine with regional settings configured for
a non-English language, an error may occur when running the integration (Old Format or
Invalid Type Library). For more information on this error and how to resolve it, browse to
the following Microsoft Support Web page:
http://support.microsoft.com/kb/320369/en-us
146
Setting the Integrity Server Connection Policy
Before users can work with the Microsoft Excel integration, the administrator must configure the
Integrity Server to allow remote API connections to the server. This enables integration users to
connect to and run commands on the server. The default connection policy allows only a specific
set of IP addresses to connect. The required setting allows all clients to connect.
The connection policy is specified in the following file on the Integrity Server:
<installdir>\config\client\IntegrityClientSite.rc
where <installdir> is the path to the directory where you installed the Integrity Server.
TIP To comment out a policy, insert a # symbol as the first letter of the property. To
uncomment a policy, remove the # symbol.
This allows all clients to request an API connection; however, all connecting clients still
require the proper authentication.
If there is a requirement to specify individual users who are allowed to connect, use a comma-
delimited list of the user IDs to define the property for daemon.validUsersList. Using a
comma-delimited list does not change the connection policy setting.
4 To have the changes take effect, restart the Integrity Server.
NOTE For more information on configuring the Integrity Server to allow remote API
connections, see the Integrity Integrations Builder API Guide.
During the installation, you may be prompted to install updates for Microsoft .NET Framework
1.1, depending on the Microsoft updates installed on your system. If you are prompted to perform
an update, follow the links to download the required redistributable program from the Microsoft
Windows Update site at:
http://windowsupdate.microsoft.com
147
The following updates are required and must be installed in the sequence shown:
.NET Framework 1.1 Redistributable (Developer version)
.NET Framework 1.1 Service Pack 1
NOTE If Microsoft .NET Framework 2.0 is installed but version 1.1 is not, you cannot install
the integration. If .NET Framework 2.0 is installed after version 1.1, there is no effect on the
integration.
To specify another directory for the installation, click Browse and choose the target directory.
To determine the amount of disk space required for the installation, click Disk Cost. The Disk
Space dialog box summarizes information on the Volume, Disk Size, Available, and Required
disk space. To return to the Setup Wizard, click OK.
5 On the same panel, you can also configure the option that allows access to the integration
while using Microsoft Excel. To allow access to yourself only, select Just Me. To allow access to
anyone using your computer, select Everyone. By default, the option is set to Just Me.
6 To continue, click Next. The Confirm Installation panel displays.
7 To start the installation, click Next. The Installing Panel displays, indicating the progress for the
installation. When the installation is complete, the Installation Complete panel displays.
8 To exit the Setup Wizard, click Close.
IMPORTANT The Microsoft Excel integration uses certain files installed with the .NET
Framework. To check for any critical updates to the .NET Framework, use the Microsoft
Windows site at:
http://windowsupdate.microsoft.com
You can now open Microsoft Excel on a client machine and configure the required Microsoft
Excel properties. For more information, see “Customizing the Microsoft Excel Integration” on
page 149.
TIP You can also remove the Microsoft Excel integration using Windows Start > Control
Panel > Add or Remove Programs.
148
To repair or remove the Microsoft Excel integration using the Setup Wizard
1 Ensure that you close Microsoft Excel before attempting to repair or remove the integration.
2 From the MKSIntegrity2009&2007_SP3_MSExcel2003_Integration.zip file, extract and run
the setup.exe file. The Setup Wizard displays.
3 Select one of the available options as required:
To repair the integration with Integrity, select the option for Repair Integrity to Microsoft
Excel Integration.
To remove the integration with Integrity, select the option for Remove Integrity to Microsoft
Excel Integration.
4 To continue the selected operation, click Finish. The integration with Integrity is repaired or
removed, according to the option you selected.
The following XML mapping templates provide sample mappings for running the Microsoft Excel
integration with Integrity for Application Lifecycle Management 2009:
MS_Excel_Defects.xml.sample, providing a sample mapping configuration for ALM 2009
Defects. By default, the template supports the Defect type.
MS_Excel_Requirements_Document.xml.sample, providing a sample mapping configuration
for ALM 2009 Requirement Documents. By default, the template supports the Requirement
type.
MS_Excel_Test_Suite.xml.sample, providing a sample mapping configuration for ALM 2009
test suites. By default, the template supports the Test Case type. For more information on test
suites, see the Integrity User Guide.
MS_Excel_RM2007_Requirement_Document.xml.sample, providing a sample mapping for
migration from 2007 to 2009.
149
NOTE
Ensure that the internal field values in the XML mapping template reflect the Integrity
field names as installed for your workflow or ALM installation. For example, if you
installed ALM with a prefix, ensure that the same prefix is present in the internal field
values contained in the XML mapping template. For general information on configuring
the XML mapping template, see “Configuring a Mapping Template” on page 188. For
more detailed information, contact PTC-Integrity Support.
If changes are made to the fields visible with the supported type, the selected template
must be modified.
The external name for Summary should not be changed.
where <installdir> is the path to the directory where you installed the Integrity Server.
CAUTION If you have previously modified the XML mapping template files, ensure that you
create backup copies of your modified templates before extracting any new template files
provided with this integration.
2 Rename the files to remove the .sample extension, and then modify the XML mapping fields
as required to correspond to your existing workflow or ALM installation. Ensure that the
internal field values used in the XML mapping template correspond to the Integrity field
names as installed for your existing workflow or ALM installation.
To use the Excel integration with a type other than those defined in a template, you must
create a copy of the template and change the name attribute to indicate the type it will be used
with. All field mappings must then be modified to correspond with the selected type. For
general information on modifying the XML mapping templates for Excel, see “Configuring a
Mapping Template” on page 188.
150
Integrity Custom Properties
To use the integration with Microsoft Excel, certain custom properties are configured for each
worksheet file you are working on. The required custom properties are created automatically
when you run the first synchronization operation.
For Excel 2003, the required integration properties are configured under File > Properties.
For Excel 2007, the required integration properties are configured under Office Button > Prepare >
Properties.
Click the Document Properties panel and Advanced Properties. Properties are configured
under the Custom tab in the Properties box.
The following properties are automatically configured for each Microsoft Excel .xls file when you
run a synchronization with Integrity:
MKS Integrity Server Port Number Port number used by Integrity to connect to the
Integrity Server.
By default, the port number is 7001. Check
with your Integrity administrator to confirm the
correct port number.
When using the Integrity integration with Microsoft Excel, you can choose a Secure Sockets Layer
(SSL) connection. To configure SSL for the Microsoft Excel integration:
1 Open the Microsoft Excel (.xls) file and click the Microsoft Office Button. From the menu,
select Prepare > Properties. Click the Document Properties panel and select Advanced Properties.
2 Click the Custom tab and in the Name field, add a property for MKS SSL Connection.
3 In the Type field, select Yes or no. In the Value field, choose the Yes option. To accept the changes
click Add and then OK.
4 Save and re-open the .xls file. The SSL connection to Microsoft Excel is now enabled. For
Microsoft Excel, SSL communications are enabled on a per-session basis, therefore, if you
close Excel, you must reset the MKS SSL Connection property to use secure communications
when you start a new session. To deactivate SSL during the same Excel session, you can set
MKS SSL Connection to No.
NOTE To use an SSL connection with the Microsoft Excel integration, you must also enable
SSL communications for the server-side API. The API authenticates its session via a
separate HTTP connection to the Integrity Server. To allow this authentication to use the
SSL connection, the Certificate Authority associated with the SSL certificate must be
registered with the JRE used by the Integrity Server.
151
Logging
Logging is enabled by default for the Microsoft Excel integration. Log and error messages are sent
to a temporary subdirectory under the home directory of the user. On Windows, the file for client
logging is:
C:\Document and Settings\<username>\Local Settings\Temp\excelint.log
Logging and error messages can be used to assist with any diagnostic work. The log files are
retained until the integration is re-started.
NOTE The location for log files depends on the value set for the system variable TMP. If the
system variable is not set, then the value of the user variable TEMP is used.
IMPORTANT Ensure that the date format used in your data list matches the default Microsoft
Excel date format. For more information on date formats and how they are handled by the
integration, see “Date Fields and Formats” on page 159.
You can perform any of the following tasks within the Excel data list:
rename or delete columns
change the order of columns
add columns of non-Integrity data
NOTE A new row added to the Excel data list becomes a new Integrity item upon
synchronization.
152
“Detecting Conflicts” on page 159
“Working With Special Fields” on page 159
The Import Map function loads the fields from the XML mapping template into the Excel sheet.
After importing the mapping template, you can then display the XML source and use drag and
drop to customize the sheet with only the fields you need.
Once the fields are mapped, you can also rename the column headers with a new display name or
change the order of the columns without affecting your ability to publish and retrieve updates.
Updates to the sheet retrieve and publish data only for the selected subset of fields. For example, if
you did not map the Project field in your sheet, you cannot publish data to the Project field for
the Integrity item.
TIP If you require all the fields contained in the mapping template, you can use the Create
New List function
to import the complete mapping template and automatically create the
required columns.
2 To complete the import, choose the required template from the Select a Template list and click
OK.
NOTE If you select the Microsoft Excel Requirements Document Template, you can also
enter information under Document Properties. For more information, see “Editing an
Existing Requirement Document” on page 158.
3 After importing the mapping template, you can then drag and drop individual fields from
Integrity into the Excel data list.
4 To display the template fields in Excel 2003, select Data > XML > XML Source. The XML Source
pane displays all the fields from the mapping template that you imported. To customize your
Excel sheet, drag and drop the required fields from the XML Source pane onto the sheet in the
column where you want the field heading to appear.
TIP You can also create a column by right-clicking the target field name under XML Source
and then choosing Map element from the shortcut menu. In the dialog box, specify or choose
the column cell where you want the field heading to appear and click OK.
To display the template fields in Excel 2007, click the Microsoft Office Button and then click
Excel Options. Under Popular, select the option for Show Developer tab in the Ribbon and click OK.
In the XML section of the Developer tab, click Source and the XML Source pane displays all the
fields from the mapping template that you imported.
153
5 To remove a mapped field, right click the bolded field name under XML Source and choose
Remove element from the shortcut menu. To remove the column from the sheet, you must
manually delete it.
The Create New List function imports the complete mapping template and automatically creates the
required columns in the Excel sheet. Create New List creates an empty data list, but does not allow
you to use drag and drop to select XML fields.
To populate the sheet with data, you can use either the Get Items or Synchronize with Query function.
For more information, see “Retrieving Items From Integrity” on page 154 and “Synchronizing
Using Queries” on page 156.
When working with a requirement document, you can also use the Synchronize command to
populate the data sheet. For more information, see“Creating a New Requirement Document” on
page 157.
IMPORTANT
You cannot create item ID numbers. Item ID numbers are created automatically by
Integrity.
You can create multiple lists within a single Excel sheet. You can also have multiple lists
containing Integrity and non-Integrity data.
If you are creating a large document, you can improve performance when adding
requirements by using the Synchronize with Query command.
2 From the Select a Template list, choose the required template. This imports the mapping
template and uses the template fields to create the column headings. For a list of the fields
included in the available templates, see “Customizing the Microsoft Excel Integration” on
page 149.
You can also enter data in the list and publish it to Integrity by clicking Data > MKS Integrity >
Synchronize.For each row in the Microsoft Excel data list, the integration creates an item in
Integrity.
The Get Items function allows you to import the mapping template and retrieve all items from the
Integrity query you select. For example, if you selected a query called All Projects, Get Items
creates a new data list that includes all items found by that query.
IMPORTANT
Do not attempt to import Integrity data into an Excel data list that contains existing data.
The Select a Query list displays only those queries that you have added as favorites
within Integrity. For more information on working with queries, see the Integrity User
Guide.
154
If Integrity items cannot be retrieved, an error message displays, providing information on the
location to check for additional details (the MKS Status (Reserved) column or the log file). If the
MKS Status (Reserved) column is not mapped, then an error status dialog box will display
information. If the MKS Status (Reserved) column is mapped, then any errors are reported in the
MKS Status (Reserved) column for each row of data.
NOTE For more information on the log file, see “Logging” on page 152.
2 From the Select a Template list, choose the required template and then select a query from the
Select a Query list. To complete the operation, click OK.
All Integrity items found in the query are retrieved into the Excel sheet, with a row for each
item found in the query.
Synchronizing Data
The Synchronize function allows you to publish updates from Excel to Integrity, and from Integrity
into Excel. Changes can include updates to existing Integrity items or the creation of new items in
Integrity.
When publishing data to Integrity, the list you are synchronizing should not contain any empty
rows. Depending on the setup of the XML mapping template (for example, if there is no
mandatory field, or if a default value is set for a required field), an empty row can cause a new
item to be created in Integrity.
The synchronization publishes to Integrity any updates made to item data in the Microsoft Excel
data list. Updates to items in Integrity are also retrieved into Excel.
Any non-Integrity data in Excel is not affected by the synchronization. The order of the rows in the
Excel list is also not affected. Formatting applied to any fields in Excel is not affected.
If the same data has been updated in both Excel and Integrity, this causes a conflict when you
attempt to synchronize the data. Conflicts are logged and must be resolved manually. For more
information, see “Detecting Conflicts” on page 159.
NOTE
Before running a synchronization, save all changes in your Excel worksheet.
You can only synchronize one data list per operation.
If you synchronize a data list that contains a highlighted table cell, an error occurs. To
correct the error, move the cursor to de-select the table cell, and repeat the
synchronization operation.
155
Publishing data from Microsoft Excel
1 To synchronize the data between Microsoft Excel 2003 and Integrity data, click Data >
MKS Integrity > Synchronize.
To synchronize the data between Microsoft Excel 2007 and Integrity data, click the Add-Ins tab
and select MKS Integrity > Synchronize.
2 You are prompted to confirm the synchronization operation. When the synchronization
completes, the Microsoft Excel status bar displays Ready.
The Synchronize with Query function works in two directions: to retrieve items from Integrity into
the Excel sheet, and to publish updates from the Excel sheet to Integrity. When a synchronization
is complete, the Microsoft Excel status bar displays Ready.
When publishing data to Integrity, the list you are synchronizing should not contain any empty
rows. Depending on the setup of the XML mapping template (for example, if there is no
mandatory field, or if a default value is set for a required field), an empty row can cause a new
item to be created in Integrity.
If new items are added through a synchronization based on a query, the new items are appended
to the bottom of the list. Error information is displayed in the MKS Status (Reserved) column.
NOTE
You can only resynchronize one data list per operation. Synchronizing data between
Integrity and Microsoft Excel does not affect non-Integrity data.
Excel removes empty cells from its output when publishing to Integrity; therefore,
deleted content will be updated with values from Integrity upon synchronization.
If you add a new requirement to an Excel list using an existing document ID, that
requirement is added to the specified document when you run Synchronize with Query.
If you are creating a large document, you can improve performance when adding
requirements by using the Synchronize with Query command.
156
Working With Requirement Documents
The Integrity integration with Excel allows you create a new data list in Excel and publish it as a
single requirement document to Integrity. The new document is created as plain text with a flat
structure. Any included subdocuments are also handled by the integration when you run the
commands for Get Items, Synchronize, or Synchronize with Query. For more information, see “Creating
a New Requirement Document” on page 157.
NOTE The procedures for working with requirements documents also apply to test suites.
The integration also allows you to edit existing requirement documents using both Excel and
Integrity. Using the Get Items command, you can retrieve an existing document from Integrity and
then edit it in Excel. You can also use the Synchronize command to publish and retrieve changes
made in either Excel or Integrity. Existing documents can also be edited in rich text using the
Document view in Integrity, with updates exported to Excel using the Synchronize command.
Updates can be made using Document Properties. For more information, see “Editing an Existing
Requirement Document” on page 158.
To change the structure of a document, you should use the Integrity Document view. After
making the required changes, you can update the Excel sheet by using Synchronize to retrieve the
updated document from Integrity. For more information, see “Adding Structure to a Document”
on page 159.
When working with requirement documents, you should select one of the following templates
from the Select a Template list:
Microsoft Excel Requirements Document
Microsoft Excel Test Suite
Microsoft Excel migrated RM 2007 Requirement Document Template
NOTE For any errors where the requirement document is not created successfully, re-run
the Create New List command, and copy the existing content to the new list.
157
2 From the Select a Template list, choose the Microsoft Excel Requirements Document and in the
Project field under Document Properties, specify the project name. Text entered in the Summary
field is used as the item summary. If no text is entered, the requirement document displays a
null summary.
NOTE
To create a new requirement document, a valid project name must be specified in the
Project field. If the Project field is blank, the integration uses the default value specified
for Project in the mapping template.
If the Summary field is blank, the integration uses the default value specified for Summary
in the mapping template.
When creating a list and synchronizing, an error message displays if you have entered
an incorrect project name in the Project field. To resolve the error, correct the project
value in the Project column of the Excel data list and then synchronize with Integrity.
The project and its contents are then created correctly.
5 Enter new rows and text in the Excel data list as required to create the content in your
requirement document. You can use the Category column to specify whether the Excel row is a
comment, heading, or specific type of requirement. Each listed requirement is created at the
top level within the parent document.
6 To publish the updates and create the necessary related items in Integrity, select MKS Integrity >
Synchronize and click OK. Integrity automatically creates the required items and relationships.
To retrieve an existing document for editing in Microsoft Excel 2007, click the Add-Ins tab and
select Data > MKS Integrity > Get Items. The Excel Integration Configuration dialog box displays.
2 Under Document Properties, enter the Document ID (the associated Integrity item number).
3 Click OK, and the requirement document is retrieved into the Excel table list.
4 Edit the rows as required to update the document.
5 To publish the information back to Integrity, run MKS Integrity > Synchronize.
Edits made in Integrity can be exported to Excel using Document Properties and specifying a
Document IDto identify the requirement document you want to update.
158
NOTE
You can only work with one requirement document per sheet. For Excel workbooks
with multiple sheets, you can import requirements using one Excel sheet for each
transaction.
Excel does not support rich text; therefore if you edit a rich text entry using Excel, it is
exported as plain text into Integrity. Inserted image attachments are not dropped;
however, they must be manually restored to their previous location in the document.
Detecting Conflicts
If the same data has been updated in both Excel and Integrity, you will see a conflict when you
attempt to synchronize the data. Conflicts are logged and noted in the MKS Status column. Details
of the field conflicts are included in the log file and must be resolved manually.
To review information on an identified conflict, refer to the excelint.log file found in the
temporary directory. On Windows, this is under the home directory of the user:
C:\Document and Settings\<userID>\Local Settings\Temp
For the API, conflict information is logged to the excelintc.log file in the same temporary
directory.
Formulas
Excel formulas can be used within Integrity data. When the data is published to Integrity, it uses
the resulting field value. Depending on the field mapping used in the mapping template, the
formula is replaced with the field value when a synchronization brings updated data from
Integrity.
Once a date field is set with a specified format in the XML mapping template, the value for that
date field should not be left empty in either Integrity or Excel. Leaving a date field empty means
the date format cannot be satisfied and causes the retrieval and/or publishing of that item to fail.
159
Within Integrity there are two date formats:
MM/dd/yyyy - (month/day/year) simple date; default format if not otherwise specified
MM/dd/yyyy hh:mm:ss - date+time (24hr format)
NOTE The internal Integrity date format defaults to the simple date format; however, if time
is required, the secondary date+time format must be specified.
Within Excel, there are three date types - date (date only), time (time only), and datetime
(date+time). The date types do not affect the display within Excel, but do affect the way data is
handled during import and export, or for purposes of calculations.
Currently, the integration supports only the date type in Excel. Time information can be included,
but Excel calculations for such fields will not use time values.
For the integration, the following external Excel formats are supported:
"yyyy-MM-dd" - (year-month-day) simple date
"yyyy-MM-dd hh:mm:ss a" - date field with time (display only) value
IMPORTANT Using a date format other than one of the supported formats can cause Excel to
convert date values to display strings, making further date calculations impossible for that
value.
Example
The following provides an example of the XML mapping for date formats:
<!-- For a field that is a date-only field -->
<field
external="New_Date"
internal="New Date"
data-type="date"
external-date-format="yyyy-MM-dd"
internal-date-format="MM/dd/yyyy"/>
<field
external="Modified_Date"
internal="Modified Date"
direction="out"
date-type="string" />
The date-only format is supported in the integration with Excel; however, any date/time fields in
Integrity do not appear in Excel. Ensure that the date format used in your data list matches the
date format used by Microsoft Excel.
NOTE If you want to use any other date formats, contact PTC-Integrity Support for
assistance.
160
161
P ART I V
Other
Sybase, HP, CA
162
CHAPTER THIRTEEN
Sybase PowerBuilder 13
The integration with Sybase® PowerBuilder® 10.5 allows users to access Integrity configuration
management commands from within the PowerBuilder interface. This chapter provides
information on configuring the integration and using the available commands. The following
topics are discussed:
“Configuring the PowerBuilder Integration” on page 164
“Using the PowerBuilder Integration” on page 164
“Creating an Integrity Project” on page 166
“Creating a Sandbox” on page 166
“Adding Members to an Integrity Project” on page 166
“Checking Out Members” on page 167
“Checking In Members” on page 167
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
163
Configuring the PowerBuilder Integration
The Integrity Client includes the File > Integrations menu action for enabling and disabling the
integration with Sybase PowerBuilder. You can select from a list of available integrations and
enable or disable them, as required to work with your preferred application. For more
information, see “Configuring Integrations” on page 3.
Before you can use Integrity for configuration management in your PowerBuilder projects, you
must select Integrity as the source control system. This does not create Integrity configuration
management projects or Sandboxes, but allows you to access the necessary commands when
working in PowerBuilder.
IMPORTANT You must enable Integrity as the source control system for any PowerBuilder
workspace in which you want to perform any other Integrity operation.
Command Function
164
Command Function
Remove from Source Control Equivalent to the Integrity Drop Members command.
Drops the selected object(s) from the Integrity project.
The Drop Members dialog box displays.
MKS SCC Integration Properties Equivalent to the Integrity Member Information command.
Displays member information for the selected object.
The Member Information dialog box displays.
Note: From the shortcut menu, select SCC Properties.
Run MKS SCC Integration Equivalent to launching the graphical user interface or the Integrity Open
Sandbox command.
Displays the Sandbox view.
Note: From the shortcut menu, select Run Source Control Management Tool.
When refreshing the status of a member through the Refresh Status command, PowerBuilder
displays a message asking permission to overwrite the selected member. This message
informs you that PowerBuilder is overwriting read-only files when it copies them from the
PBL.
165
To avoid these messages, right click and select Properties from the shortcut menu. The
Properties of Workspace dialog box displays. From the dialog box, select the Suppress prompts to
overwrite read-only files option.
NOTE You must create a folder for the Integrity project and Sandbox before you create a
project or Sandbox.
1 In PowerBuilder’s Workspace panel, select the workspace file containing the PowerBuilder
project you want to put under version control.
2 Right click and select Properties. The Properties of Workspace dialog box displays.
3 Next to the Project field, click the browse button. The Specify the Project to Create dialog box
displays.
4 Create a project as described in the Integrity User Guide. The Create Sandbox Wizard displays.
5 Create a Sandbox as described in the Integrity User Guide.
6 Fill in additional options of the Properties of Workspace dialog box as needed and click OK.
Creating a Sandbox
PowerBuilder does not directly support the creation of Sandboxes. For more information on
working with Integrity Sandboxes from within PowerBuilder, contact PTC- Integrity Support.
166
Checking Out Members
To check out members in PowerBuilder
1 From PowerBuilder’s Workspace panel, select one or more objects to check out.
2 Right click and from the shortcut menu, select Check Out. The PowerBuilder Check Out dialog
box displays.
3 Select one or more objects to check out.
4 Click OK. The Check Out dialog box displays.
5 Check out each member as described in the Integrity User Guide.
NOTE To check out a revision without placing a lock, add the following to the PB.INI file:
SccCheckoutNoLock=1
If a library section already exists, add the SccCheckoutNoLock option at the end of that
section. If there is no library section, add the option at the end of the PB.INI file.
Checking In Members
To check in members in PowerBuilder
NOTE PowerBuilder does not prompt you when checking in an unmodified member. You
should scan for changes before checking in a member.
1 From PowerBuilder’s Workspace panel, select one or more objects to check in.
2 Right click, and from the shortcut menu, select Check In. The PowerBuilder Check In dialog box
displays.
3 Select one or more objects to check in.
4 Click OK. The Check In dialog box displays.
5 Check in each member as described in the Integrity User Guide.
167
168
CHAPTER FOURTEEN
HP Quality Center
Requirements and Defect
14
Modules
The Integrity integration with the HP Quality Center 9.2 Requirements and Defect Modules
allows you to map requirement and defect items between Integrity and Quality Center 9.2.
The integration references the user fields in Quality Center to map to fields in Integrity. To
provide a direct link between a Quality Center requirement or defect and an Integrity item, a
linked field is created in Quality Center. In the field you have designated as the linked field in
Quality Center, you can enter the Integrity item ID that you want the requirement to correspond
to.
This integration is intended to work with Integrity for Application Lifecycle Management 2009.
You can also configure the integration to work with previous workflows (for example, with
workflows installed for Integrity for Requirements Management 2007 and ALM 2.1).
This chapter provides information on the following topics:
“Integration Overview” on page 170
“Assumptions” on page 171
“System Requirements” on page 171
“Installation and Configuration Overview” on page 171
“Step 1: Configuring the Integrity Server” on page 172
“Step 2: Configuring Quality Center” on page 173
“Step 3: Configuring Integrity” on page 176
“Step 4: Installing the Integration” on page 177
“Step 5: Configuring the Integration” on page 178
“Step 6: Running the Integration” on page 182
“Troubleshooting” on page 183
IMPORTANT With the release of Integrity 10.0, the default installation directory of the
Integrity Client has changed. This change affects integrations that were installed with the
Integrity Client 2009 or earlier. For more information, see “Integrity Client Default
Installation Directory” on page 3.
169
Integration Overview
The integration references the user fields in Quality Center to map to fields in Integrity. To
provide a direct link between a Quality Center requirement or defect and an Integrity item, a
linked field is created in Quality Center. In the field you have designated as the linked field in
Quality Center, you can enter the Integrity item ID that you want the requirement to correspond
to.
You can run the integration with many different configurations to suit particular projects. Each
configuration and server must have their own requirement and defect process configuration file
and log file.
RM and defect process configuration files set the parameters for connecting to the Quality Center
server and for handling logging and e-mail notifications. The sample file included with the
integration can be used as a basis for your own configuration. To learn about the valid field values
for this file, see “Modifying Process Configuration and Mapping Files” on page 179.
NOTE Each processConfig.xml file contained in the directory defined in the hp-im-
integration.bat file is run each time the integration is run.
The XML mapping configuration files included with the integration are the sample templates you
can use as a basis for the field mappings between Quality Center and Integrity. To learn about the
valid field values for these files, see “Modifying Process Configuration and Mapping Files” on
page 179.
Once the items are mapped, any updates to these fields are reflected in the item/requirement
and/or item/defect when the integration is run. You can map integer, pick, float, logical, date,
short text, long text, state, user, and group data types.
A log file reports any errors encountered while the integration is running. The path to the log file
is specified in the process configuration files. Any errors that cause the integration to fail are
logged, and can be reported via e-mail notification. Non-fatal errors are logged and the integration
continues to run. You can specify one e-mail address or a set of e-mail addresses in the process
configuration file.
To learn how to resolve specific errors or situations, see “Troubleshooting” on page 183.
NOTE
The integration supports basic rich content synchronized between Integrity and Quality
Center, for example: bold, underline, italic, and strikethrough are preserved.
Links between defects and requirements in Quality Center are not captured by the
integration. As a result, the corresponding issues in Integrity will not be linked unless
you link them manually. Similarly, relationships between Integrity requirements and
tasks are not maintained during the integration and need to be added manually.
Folder names containing spaces that are listed in the hp-im-integration.bat file may
cause issues with the integration. Ensure that you convert all folder names that have
spaces to their DOS file system short name equivalent. To determine the short name of a
folder, run the dir/x command from a command prompt on the required folder.
170
Assumptions
Before you use the integration, you should fully understand:
The hardware platform and Windows operating system on which the integration is installed.
Integrity.
Integrity for Requirements Management or Integrity for Application Lifecycle Management
(ALM).
HP Quality Center, including the Requirements and Defect modules.
For more information on Quality Center, browse to www.hp.com and search for Quality Center
9.2.
XML.
NOTE
This integration uses XML files to create the mappings between Integrity and
Quality Center. This guide assumes that if you are modifying the XML files, you
understand and can use XML.
For general information on configuring the XML mapping template, see “Configuring a
Mapping Template” on page 188. For more detailed information, contact PTC-Integrity
Support.
System Requirements
For the integration to work effectively, you must have the following installed and configured
correctly:
Integrity Server 2009 or later
HP Quality Center 9.2
JVM 1.5.0_11 or higher
171
The following list is a high-level overview of the steps required to install and configure the
integration:
“Step 1: Configuring the Integrity Server” on page 172
Configuring the Integrity Server to allow remote API connections.
“Step 2: Configuring Quality Center” on page 173
a) “Creating and Editing Projects” on page 174
b) “Creating MKS ID Field for Requirements and Defects” on page 174
c) “Creating Additional Requirements User Fields” on page 175
d) “Adding the User Fields to All Requirement and Defect Types” on page 176
“Step 3: Configuring Integrity” on page 176
Configuring Integrity by creating the applicable required fields.
“Step 4: Installing the Integration” on page 177
Installing the integration from the QC92_IM_Integration_Install.zip file.
“Step 5: Configuring the Integration” on page 178.
a) Create a new Integrity query.
b) Create the applicable process configuration files (processConfig.xml), each with a unique
name.
c) Create a new mapping configuration file each for requirements and/or defects or edit the
existing one.
d) Specify the location of the configuration files in the hp-im-integration.bat file.
e) In the Integrity Administration Client, set the Attachments fields to Visible on the required
types.
“Step 6: Running the Integration” on page 182
Schedule the execution of the hp-im-integration.bat file.
If you have any issues running the integration, see “Troubleshooting” on page 183.
172
Connection Policy
Within the IntegrityClientSite.rc file, the default connection policy is specified by the
following property:
daemon.connectionPolicy=mks.ic.common.policy.
ICAllowSpecificConnectionPolicy
The default setting allows only a specific set of IP addresses to connect. The required setting
allows remote API connections.
where <installdir> is the path to the directory where you installed the Integrity Server.
2 Comment out the default policy (that is, insert the # symbol), and then uncomment the
following property:
daemon.connectionPolicy=mks.ic.common.policy.
ICAllowAllConnectionPolicy
TIP When you uncomment a property (by removing the # symbol), you enable the required
property.
This allows all clients to request an API connection; however, all connecting clients still
require the proper authentication.
If there is a requirement to specify individual users who are allowed to connect, use a comma-
delimited list of the user IDs to define the property for daemon.validUsersList. Using a
comma-delimited list does not change the connection policy setting.
3 Save and close the file.
4 To have the changes take effect, restart the Integrity Server.
NOTE For more information on configuring the Integrity Server to allow remote API
connections, see the Integrity Integrations Builder API Guide.
173
Creating and Editing Projects
Project settings must be configured for each individual Quality Center project referenced by the
integration. For more information on creating a new project or editing an existing project, refer to
the Quality Center product documentation.
Each project you create must have an appropriate integration user with permissions for creating
and editing custom fields.
The integration requires the MKS ID custom field by default. After you add this field to both
requirements and defects you then need to add it to the applicable column set. The MKS ID custom
field allows the Integrity item number to be displayed in the project.
You must have administrator rights to create custom fields in Quality Center.
NOTE For the Requirements module, all items are imported into Integrity as requirements
(instead of requirement documents) unless you set the MKS_Type field to Requirement
Document. At minimum, the top-level requirement folder of Quality Center should be set to
Requirement Document before the initial run of the integration.
TIP Use the Quality Center Tools menu, not the Web browser's Tools menu.
4 Under Requirement, select User Fields, and create the MKS ID custom field as follows:
Field Length 40
The options for Masked should be set specifically for your project.
174
5 Under Defect, select User Fields, and create the MKS ID custom field as follows:
Field Length 40
The options for Searchable (defects only) and Masked should be set specifically for your project.
6 Click Return to get back to the Project Customization page. The next step is to display the MKS ID
field for requirements and defects in the Quality Center column heading.
The next section provides procedures for creating and displaying the MKS ID field in Quality
Center. For more detailed information on creating custom fields in Quality Center, see the
Quality Center product documentation.
TIP Use the Quality Center View menu, not your Web browser’s View menu.
2 Under Available Columns, select MKS ID and click the right arrow to move your selection to
Visible Columns for both the Requirement and the Defect column set.
To accept the changes, click OK. The MKS ID displays in the requirement or defect item.
You must create additional Requirements user fields for the integration to function properly.
Required fields can be used to pass information to or from Integrity to Quality Center. Any
additional custom fields must be strings of an appropriate length.
NOTE The defect types require only the BG_USER_01 field. To learn how to create this field,
see “Creating MKS ID Field for Requirements and Defects” on page 174.
To set up new fields for use between Integrity and Quality Center, define the new field as follows:
Set up the custom field in Quality Center.
Map the new field in your production copies of the mapping files, located in:
<integration installdir>\MappingConfigFiles
For more information on mapping fields, see the comments provided within that file.
175
Adding the User Fields to All Requirement and Defect Types
By default, the user fields RQ_USER_01, RQ_USER_02, and RQ_USER_03 are only added to the
Unspecified requirement type. You must add all three fields to all five requirement or defect
types for them to function correctly.
Select Customize > Requirements Types and move all three user fields from Not in Type to In Type
individually for each of the five other requirement or defect types.
The MKS Type must be set when you create requirements in QC 9.2. For example, with the ALM
2009 workflow, you would choose the Requirement Document type when creating documents and
Requirement type for requirements.
IMPORTANT The creation of your requirement fails if you do not define the MKS type for
each requirement document. If the type is left blank, a requirement rather than a document
is created.
5 Type the same field name as the field label you defined in the Quality Center project entities.
6 To save the new field, click OK.
7 Under the Types node, select the Requirement type.
8 Right click and select Edit Type. The Edit Type dialog box displays.
176
9 In the left pane, select Visible Fields and enable the new field to ensure that it is visible to all of
the groups using the integration. For more information on creating fields and editing types,
see the Integrity Server Administration Guide.
10 Repeat steps 5 - 7 for Defect.
11 Save your changes.
NOTE For detailed instructions on configuring the Integrity Document view, see the
Integrity User Guide.
NOTE Ensure you install Integrity, Quality Center, and the integration on machines that
register the same time in the same time zones. If the times and time zones are not in sync,
you may experience problems completing the integration.
4 Update the hp-im-integration.bat file (located in the Quality Center installation directory)
with the path to OTAClient.dll.
5 Ensure that you have JVM installed and point to the JVM install location in the
hp-im-integration.bat file instead of the JVM version included with Quality Center.
177
Step 5: Configuring the Integration
After you install the integration, the next step is to configure the applicable components.
The majority of the configuration is done using the XML process configuration and mapping
configuration files.
Additional details on process configuration and mapping configuration files are discussed under:
“Process Configuration XML Files” on page 180
“XML Mapping Configuration Templates” on page 180
Sample XML mapping configuration templates and process configuration files are provided in the
Integrity2009_Server_Templates.zip file, which is also available for download from the
Integrity Support Center.
To download the sample configuration files, go to the Integrity Support Center:
http://www.ptc.com/support/integrity.htm
If the number of items returned exceeds the server query maximum, increase the limit by
configuring the mksis.im.queryGovernor property (formerly
mksis.im.maxQueryIssueCount in the <Integrity Server
installdir>\config\properties\im.properties file). For more information on
configuring mksis.im.queryGovernor, see the Integrity Server Installation and Configuration
Guide.
TIP You can determine the existing query limit by running the following command:
im diag --diag=policies
2 Create a new process configuration file for each Quality Center requirement and defect
module project. Each file requires a unique name. You will require one processConfig.xml
per server and one per configuration. You may require one or more for defects, one for
requirements, one or more for ALM defects, one for ALM requirements, etc.
Place the newly created process configuration file in:
<integration installdir>\ProcessConfigFiles
IMPORTANT The integration uses different processConfig.xml files for each defect or
requirement module, Quality Center project, and associated server.
Integrity runs all *.xml files that are contained in the directory specified in the.bat file.
Any process configuration files you do not want to run must be renamed to something
other than *.xml.
Mapping files are only used if they are referred to in the process configuration files. You
may have as many mapping configuration files as required with any name you choose.
178
Refer to the requirement and defect processConfig.xml.skeleton files for additional
information. To learn how to configure the files, see “Modifying Process Configuration and
Mapping Files” on page 179.
3 Create or edit the existing mapping configuration files located in:
<integration installdir>\MappingConfigFiles
If required, you can modify the process and configuration mapping files to suit your
application environment. See “Modifying Process Configuration and Mapping Files” on
page 179 for field-level details.
4 Specify the location of the configuration files in the hp-im-integration.bat file. All .xml files
contained in the above directory are referenced.
5 In the Integrity Administration Client, set the Attachments fields to Visible on the Requirement
and Requirement Document types. If you want attachments to be visible on defects, do the
same in Task and/or the Requirement type.
Together, these files are used to configure the integration. The mapping configuration files can be
configured for your application environment.
NOTE Ensure that the internal field values in the XML mapping template reflect the
Integrity field names as installed for your workflow or ALM installation. For example, if
you installed ALM with a prefix, ensure that the same prefix is present in the internal field
values contained in the XML mapping template.
For general information on configuring the XML mapping template, see “Configuring a
Mapping Template” on page 188. For more detailed information, contact PTC-Integrity
Support.
Key Considerations
For each processConfig.xml file, you can only specify one Quality Center server, one
Integrity Server, one Quality Center project, and one defect or requirement module.
For example, if you have one Quality Center server with one project and one Integrity Server,
and you want to use defects and requirements, you must use two process configuration files.
Mandatory fields in Integrity must have a value when an item is created. If mandatory fields
do not have mappings to Quality Center fields, the integration cannot create an Integrity item.
The default XML templates provided with the integration provide the necessary mappings
and default values for mandatory fields in the Requirement type in Integrity.
When creating any additional mandatory fields, ensure that all mandatory Integrity fields for
the requirement type are mapped to the appropriate Quality Center fields. Ensure that the
fields mapped in Quality Center are also mandatory.
For more information on configuring mandatory fields, see the Integrity Server Administration
Guide.
The Quality Center integration user (connecting to Integrity) must have the required
permissions for projects in Quality Center and for type and field visibility in Integrity. The
179
integration cannot map data to a type or field that is invisible to the integration user. For more
information on visibility rules, see the Integrity Server Administration Guide or online help.
Updates to Integrity requirement items will fail if the Integrity user configured to run the
Quality Center integration does not have permission to create or modify a requirement item.
If permission is then granted to the user before the next run of the integration, the missed
updates are not be picked up because the date of the update precedes the last run time.
Moving a requirement to a different parent is not supported in Quality Center. If you
re-parent a requirement in Quality Center and then attempt to run the integration, you may
not see the corresponding change in Integrity.
Related requirements in Integrity cannot have the same name in the target Quality Center
project.
NOTE
XML code is case-sensitive.
If you need to further customize the template to suit the workflows used in your
organization, contact PTC-Integrity Support.
1 Copy the files and save them in the same directory for as many integrations as you require
(separate directories for each).
2 Modify and save the copied versions to create the required mappings.
An internal field is a field referenced in Integrity. An external field is a field in Quality Center.
Additional fields are mapped as external="ALM_USER_nn" internal="MKS field name" and so on.
For more information, see “Creating Additional Requirements User Fields” on page 175.
180
For general information on configuring XML mapping templates, see “Configuring a Mapping
Template” on page 188. For more detailed instructions, contact PTC-Integrity Support.
IMPORTANT Ensure that the internal field values in the XML mapping templates reflect the
Integrity field names as installed for your workflow or ALM installation. For example, if
you installed ALM with a prefix, ensure that the same prefix is present in the internal field
values contained in the XML mapping template.
This section provides information about configuring the contents of the processConfig.xml, file
for e-mail notification for logging integration errors.
Contents of the e-mail message are configurable using number-encoded tags that expand to
populate the message with the related information. The following tag codes are available:
{2} Date/Time
For example,
An error occurred at {2} with the following log message:"{4}". For more
information, refer to the {3} file.
expands to the following message:
An error occurred at 01/09/06 2:50 PM with the following log message: "An
error occurred when mapping item 26 Could not save modified item 26: The
following fields may not be edited [ Summary ]". For more information, refer
to the QCDataMapper.log file.
The mapping files define the mapping of attachments between Integrity and Quality Center.
Key Considerations
Ensure that you monitor and periodically clean up the attachments folder specified in the
process configuration files.
Non-file attachments are not supported, for example, links. However, you can use the field
<field name="QC-ADDLINKS">http://HOSTNAME:PORT/im/viewissue?selection={ID}</
field>; to create attachment links. This field is further discussed in the process configuration
file description in “Step 5: Configuring the Integration” on page 178.
To use attachments with defects, you have to make Attachments visible on Task.
181
To change the way attachments are handled, modify the following field mappings:
<field external="_ATTACHMENT" internal="Attachments" direction="both" field-
type="attachment" clobber="false"/>
where
external="_ATTACHMENT" is the unique field name the integration uses for Quality Center
attachments.
direction="both" defines the allowed direction of information transfer. Valid values are
both, in, or out. both moves information in both directions between Integrity and Quality
Center. in moves information into Integrity from Quality Center. out moves information
out of Integrity and into Quality Center.
on-create-only="false" defines when attachments can be created. Valid values are true
or false.
The value clobber=false defines how attachments are handled by the integration. The
value only applies to the handling of attachments in Quality Center when they are
exported to Integrity.
The value clobber=false means that upon refresh, the new list of attachments is
appended to any existing list of attachments. Revised attachments are updated in the list
and new attachments are added to the existing list.
The value clobber=true means that upon refresh, the new list of attachments is used to
replace any existing list of attachments. If the revised requirement has no attachments,
then the update deletes any previously existing attachments.
182
Key Considerations
Links between defects and requirements in Quality Center are not captured by the integration.
As a result, the corresponding issues in Integrity are not linked unless you link them
manually. Similarly, relationships between Integrity requirements and tasks are not
maintained during the integration and must be added manually.
For the requirements module, all items are imported to Integrity as requirements unless you
set the MKS_Type field to Requirement Document. The top-level requirement directory of QC 9.2
should be, at minimum, set to Requirement Document before the initial run of the integration.
Troubleshooting
Log files store information about historical synchronizations. Integrity allows you to specify the
name and location of the Quality Center integration log file. You must specify one log per
scheduled integration. The log file name and location is specified using the <log-file></log-
file> mapping in the processConfig.xml files.
To learn how to configure the process configuration file, see “Modifying Process Configuration
and Mapping Files” on page 179.
In addition, the IntegrityClientSite.rc file may provide additional Integrity Server
information.
Potential errors include: failed initial load synchronizations or updates, extra logging information
in the IntegrityClientSite.rc log file, communication with the API, data processing with the
mapping files.
Possible reasons for errors occurring during the initial load or update process include: connection
errors, misconfiguration of the mapping files or process configuration file, running simultaneous
integrations.
When problems occur in the Quality Center integration, an attempt is made to rectify the problem
on the next run. This is accomplished using a defined number of retries in the processConfig.xml
files.
If the problems are not resolved, the retry list (and subsequently, the integration runtime), may
become long. To solve this:
check the log files for any issues and fix them.
delete the files in the <installdir>/data directory. Doing so will remove some of the retry
attempts and keep the integration going.
If additional errors occur, consider the following:
If you cannot run a synchronization because you have received an error indicating that
integration is already running (and you are sure there is not one already running), delete the
.lck file.
Adjust the number of retries in the processConfig.xml file. This setting controls the number
of times the integration attempts to update a requirement in the Quality Center Requirements
module. If a requirement exceeds the number of failures it is no longer synchronized.
183
Re-run the integration if a synchronization failed during an initial load:
Ensure that all mappings in the mapping files contain values.
Reset the passwords in the Quality Center connection settings and/or the Integrity
connection settings in the processConfig.xml file. Change QC-PASSWORD-ENCRYPTED to
false.
Delete the .lrt and .dat files specific to each Quality Center project (four in total).
Run the integration again.
If a fatal error occurs during an initial load and the synchronization stops, try the following
and re-run the integration:
Verify that the integration log does not end with
***** DATA MAPPER END *****
Verify the existence of the hs_err_pidXXXX.log log file corresponding to the halted
integration.
If both of the above are true:
Delete corresponding .lrt and .dat files.
Delete the .lrk (lock) file.
Run a query against the REQ table in the Quality Center database to determine if a
requirement with the name New_Requirement exists.
Sample query:
SELECT * FROM REQ WHERE ALM_REQ_NAME LIKE 'New Requirement'
184
CHAPTER FIFTEEN
CA Endevor 15
This chapter contains general information on the Integrity integration with CA Endevor® Change
Manager (CA Endevor).
The following topics are discussed:
“Understanding the CA Endevor Integration” on page 186
“Integrity Commands” on page 186
185
Understanding the CA Endevor Integration
The Integrity integration with CA Endevor allows you to combine the highly customizable
workflow management functionality of Integrity with the change management functionality of
Endevor within a mainframe software development environment.
The integration is designed so that specific events in Endevor will trigger specific commands in
Integrity. This allows you to connect development changes in Endevor to the workflow
management in Integrity.
Integrity Commands
Integrity and Endevor communicate through the COBOL Adapter, which in turn uses the
Integrity API to run the commands in Integrity. The following Integrity commands can be
configured to run once a specified Endevor event occurs:
im connect
im viewissue
im editissue
im createissue1
im createcp
im createcpentry1
im viewcp
im editcpentry1
im cps
Depending on the configuration of the integration, one or more of the available commands is
initiated in Integrity. For more information on these commands, see the Integrity CLI Reference
Guide for Workflow and Documents. For more information on Endevor change packages, see the
Integrity User Guide or online help.
NOTE Depending on the configuration of the integration, you may or may not receive
confirmation from Integrity when commands are run, and you may or may not be required
to provide input.
For more information on configuring and implementing this integration, visit the Integrity
Support Center (http://www.ptc.com/support/integrity.htm). A guide is available with the
integration download and includes useful examples. Additionally, you may consult the Integrity
Integrations Builder API Guide.
1
For more information on these commands, go to the Integrity Support Center (http://www.ptc.com/support/
integrity.htm).
186
P ART V
Appendixes
187
APPENDIX
Configuring a Mapping Template
This appendix provides information on the XML mapping template file that is used to configure
the integrations with Microsoft Excel, Project and Word. The mapping template file defines the
necessary two-way relationships between internal Integrity items and external items. The two-
way mappings allow each set of items to remain synchronized such that a change made in one set
of items is reflected in the other.
To assist you in editing a mapping template, this appendix includes the following topics:
“Overview” on page 189
“Mapping Template XML Elements” on page 190
“Mapping Template Example” on page 199
IMPORTANT The mapping templates included with Integrity are functioning examples and
should always be edited with care. If you are not familiar with XML, contact PTC -
Integrity Support for further assistance.
188
Overview
While the configuration is an XML file like an IIF document or the Wizard Configuration file, it is
more than a way of representing data. It is a small programming language that lets you define the
process of importing and exporting items from an external data source and Integrity internal
items.
The Gateway Configuration file processes items one at a time and determines the complete set of
mapping rules to apply to the item before actually applying any of them. This allows later steps to
change or negate previous mapping rules. It also means that regardless of what mappings are
scheduled to be applied, it is always the original values of the internal and external fields that are
used.
There are two other important concepts for configuration files: conditional mappings and levels.
Conditional mappings are mapping instructions that only apply when they are activated by a
<map-conditional> element (or the <map-translation> sub-element). These conditional
mappings are contained within <map> elements. Until mappings are activated, they are ignored.
Once a <map> is activated, the mapping instructions within that element become active. This can
include additional <map-conditional> elements and the corresponding <map> elements;
although such <map> elements are also ignored until they are activated.
Levels are a related concept. The process begins with the main instructions at level 1. Each time a
<map> element is activated, the process moves up a level and remains at that new level until the </
map> tag is reached. At that point, the process moves back to the previous level.
The importance of levels is in the way they interact with the <map-conditional> and <map>
elements. When a <map-conditional> element is attempting to find a matching <map>, only
<map> elements at the current level of processing are examined. This means that if you have a
<map-conditional> element within a <map> element, the corresponding <map> elements that can
be activated by that <map-conditional> must also appear within the same <map> element.
Additionally, once a <map-conditional> on a given level has activated a <map> element and its
contents, all other <map-conditional> elements at the current level are ignored.
189
Mapping Template XML Elements
This section describes the various XML elements of the mapping template, and provides
information on how to configure those elements.
<mapping>
The <mapping> element is the highest level XML element. As such, it contains all other
elements. There is only one <mapping> element in the file.
Attributes:
name
The name attribute specifies the name of the particular Gateway conversion process defined in
the file. This name is the identifier through which an Gateway configuration is selected for use
by the Gateway Wizard. It is expected to be unique across all known Gateway configurations.
template-version
The template-version attribute specifies the version of the XML template used for creating
the Gateway Configuration file. This documentation describes version 2.1. This value is
required for the proper operations of Gateway.
<description>
The <description> element specifies a description of the particular conversion process
defined in the file. The Gateway Wizard displays this description when prompting for the
selection of the Gateway configuration to use.
There is one <description> element in a configuration element.
Parent Element: <mapping>
Sub-Elements: none
<set-property>
The <set-property> element sets an item control property to a given value. For example:
<set-property name="owner" value="external"/>
When importing items into Integrity, there are a few common properties worth mentioning:
prototype
This property helps Integrity identify the type of item it is importing. Valid values include
DOCUMENT and CONTENT. Commonly, this prototype property is provided directly within
the definition of the item data being imported, but the Gateway configuration may be
used to override and set the item's prototype property.
owner
This property helps Integrity determine whether the item is externally or internally
owned. Valid values are "external" and "internal". In the case of a document, for
example, externally owned data would mean that Integrity should delete any content that
is no longer present within the data being re-imported.
190
prior-data-field
This property, in the case where a document is being re-imported, identifies to the
attachment field within which an IIF document representing the previously imported
data would be found. This property is only relevant to document items.
prior-data-name
This property, in the case where a document is being re-imported, identifies to the name
of the attachment file (an IIF document) that represents the previously imported data.
Previously imported data is used to help identify the set the changes to be performed on
the data.
Attributes:
name
The name attribute specifies the name of the property to set.
value
The value attribute specifies the value to which the property indicated by the name attribute is
to be set.
<link-field>
The <link-field> element automatically creates a link between a unique ID field in the
external data source and the internal data. By creating such a link, it is much easier to update
existing fields when re-importing previously imported data.
The <link-field> element has four basic forms. The first form is:
<link-field field-type="id">
When using this form, each item in the external data source has a unique identifier (similar to
the primary key of a database) which is then used as the Integrity identifier.
The second form is:
<link-field external="REQID" field-type="id">
In this form, a field in the external data named REQID contains the Integrity identifier for the
corresponding field in the internal data.
The third form is:
<link-field internal="DATA_KEY">
As with the first form, the external data source has a unique identifier but instead of using it as
the Integrity identifier, it is stored in the internal field named DATA_KEY.
Finally, the fourth form is:
<link-field external="REQ_ID" internal="DATA_KEY">
With this form, the external data field named REQ_ID is linked with the internal data field
named DATA_KEY.
191
Attributes:
external
The external attribute specifies the name of a field in the external data source.
internal
The internal attribute specifies the name of a field in the internal data.
field-type
The field-type="id" attribute specifies that a field is an id field.
hash-code
Some external data sources (for example, Oracle databases) do not allow database look-ups
using text strings, and only allow look-ups using integers. To accommodate such sources, you
can specify the hash-code attribute which specifies a field name in which a hash code based
on the identifier in question is stored.
<field>
The <field> element defines the mapping between fields in the external data source and
fields in the internal data. The simplest version of this tag names only the external and internal
fields. For example:
<field external="Type" internal="RQ_Share Category"/>
Attributes:
external
The external attribute specifies the name of a field in the external data source.
internal
The internal attribute specifies the name of a field in the internal data.
direction
The direction attribute specifies the direction of the relationship between the external data
field and the internal data field.
direction Description
When the direction attribute is not specified, the behavior is as though direction=both was
specified.
192
field-type
The field-type attribute identifies what type of content the field holds. Possible values
include:
field-type Description
attachment An attachment
data-type
The data-type attribute determines how the data in the field is to be interpreted. Possible
values include:
data-type Description
attachment
The attachment attribute is used when mapping fields containing rich content to identify the
Integrity attachment field that should be used to store images embedded in the rich content.
external-date-format
The external-date-format attribute specifies the date format used in the external data
source. For example, EEE MM/dd/yy.
This attribute is only meaningful if field-type="date" or field-type="date-time" is
also specified; otherwise, it is ignored.
clobber
The clobber attribute defines how existing attachments associated with the field are handled.
The clobber attribute is only meaningful when field-type="attachment" is also specified;
otherwise, it is ignored.
The clobber attribute can be set to true or false.
clobber Description
193
on-create-only
The on-create-only attribute can be set to true or false.
on-create-only Description
value-translation-type
In some cases, data in the corresponding external and internal fields are stored in two different
ways. For example, the external field may contain a range of integer values, while the internal
field simply contains string values of Low, Medium, and High. The
value-translation-type attribute specifies the relationship in such cases.
value-translation-type Description
<default>
The <default> element specifies a value that is assigned to a field when either only an
external or internal field name is named or the internal or external field from which it should
be updated does not exist.
The following example sets the RQ_Category field in the internal data to a value of Heading
when the internal data items are being first created.
<field internal="RQ_Category" direction="in" on-create-only="true">
<default>Heading</default>
</field>
194
Attributes: none
Parent Element: <field>
Sub-Elements: none
<value-translation>
When a <field> element has a value-translation-type attribute attached, the
<value-translation> element defines which values from the external data source
correspond to values in the internal data.
The following example shows how this can be used to define the correspondence between
ranges of integers in the external field and a single string value in the internal field.
<field external="Priority" internal="RQ_Priority" direction="both"
value-translation-type="intrange-string">
<value-translation external="0..250" internal="Low" />
<value-translation external="251..500" internal="Medium" />
<value-translation external="501..750" internal="High" />
<value-translation external="751..1000" internal="Critical" />
</field>
Attributes:
external
The external attribute defines which value (or range) in the external field corresponds to the
value or (range) in the internal field as defined by the internal attribute. The type of value (or
range) is specified by the value-translation-type attribute of the parent <field>
element.
internal
The internal attribute defines which value (or range) in the internal field corresponds to the
value or (range) in the internal field as defined by the external attribute. The type of value (or
range) is specified by the value-translation-type attribute of the parent <field>
element.
<map-conditional>
The <map-conditional> element specifies that the mapping of a field is conditional on the
value of a field or its properties. Based on the value of the field or property, a set of specialized
mapping rules (defined by a <map> element) is activated.
In its simplest form, the value of the specified field or property is used as the name of the
<map> to be activated. For example:
examines the value of the prototype property and looks for a <map> element with a name that
matches the value of prototype. If found, that <map> is activated and the specialized mapping
rules defined within that <map> are applied. Using this example, if the value of the prototype
property is CONTENT and a <map name="CONTENT"> element exists, that <map> is activated.
195
Once a <map-conditional> element has activated a <map>, all other <map-conditional>
elements at that level are ignored. For example:
<map-conditional external="Description" />
<map-conditional property="prototype" />
first looks for a <map> that has a name that matches the value of the external field name
Description. If such a <map> is found, it is activated and the second <map-conditional> is
ignored. However, if no such <map> is found, the second <map-conditional> is examined to
see if there is a <map> that matches the name of the prototype property.
If the field or property whose value is being compared to <map> names does not exist in the
current item, the <map-conditional> is ignored.
Attributes:
external
The external attribute specifies the name of a field in the external data source whose value is
tested to find a matching <map> element.
internal
The internal attribute specifies the name of a field in the internal data whose value is tested
to find a matching <map> element.
property
The property attribute specifies an item control property whose value is tested to find a
matching <map> element.
direction
The direction attribute specifies that a matching <map> is only to be activated if the direction
of the relationship between the external data source field and the internal data field matches the
specified value. Possible values include:
direction Description
For example:
<map-conditional property="prototype" direction="in">
only activates a matching <map> for the prototype value if the internal field is being updated
from the external field. That is, it is only activated if the mapping is an import operation.
default-map
The default-map attribute specifies the name (as defined by a <map> element) of a set of
specialized mapping rules that are to be applied when the value being matched to <map>
names matches no <map> elements and has no other recognized value (that is, it is a null value
or its value is not represented in any <map-translation> sub-element.
196
<map-translation>
The <map-translation> element is a sub-element of the <map-conditional> element. It lets
you specify a list of values (that do not match a <map> name) for the field or property being
examined in the <map-conditional> and associate them with a <map> element. The specified
<map> is activated if the examined field or property has the given value.
For example:
<map-conditional external="Category">
<map-translation external="Software" map-name="Application" />
<map-translation external="Utility" map-name="Application" />
</map-conditional>
<map name="Application">
...
</map>
In this case, if the value of the external field named Category is Application, then <map
name="Application"> is activated. If the value is not Application, the <map-translation>
sub-elements come into play and if the value of the Category field is either Software or
Utility, then the <map name="Application"> is also activated.
In this example, if the value of the Category field is either Application or Non-Application,
the <map> element with that name is activated. If the field has another value, the
<map-translation> sub-elements specify that a value of Software or Utility for that field
activates <map name="Application"> and any other non-null value activates <map
name="Non-Application">.
You can only specify one <map-translation> sub-element without an external attribute per
<map-conditional> element.
Attributes:
external
In a <map-translation> element, the external attribute does not refer to the name of a field
in the external data source, but rather it specifies a possible value for the field or property in the
197
parent <map-conditional> element that is being matched to <map> names. In the example,
the external attributes in the <map-translation> elements specify possible values for the
external field named Category.
map-name
The <map-name> attribute specifies the name (as defined by a <map> element) of a set of
specialized mapping rules that are to be activated when the field or property being matched in
the parent <map-conditional> has a value that matches the value specified by the external
attribute.
When no external attribute is specified and the field or property is being matched has a non-
null value, the specified <map-name> is activated regardless of the value of that field or
property. There can only be one such <map-translation> sub-element per
<map-conditional>.
<map>
The <map> element defines a specialized set of mappings (using <field> elements) that are
only performed when activated by a <map-conditional> element. When a <map> element is
not activated.
You can nest <map> elements, allowing you to specialize the mappings to be performed even
further.
For example:
<map-conditional property="prototype"/>
...
<map name="CONTENT">
<map-conditional external="Category"/>
...
<map name="Software Requirements">
...
</map>
<map name="Hardware Requirements">
...
</map>
</map>
In this example, the prototype property of the item is examined and the main level of the
Gateway Configuration file (the level where <map-conditional property="prototype"/>
resides) is searched looking for a <map> with a name that matches the value of the prototype
property. Thus, if prototype has a value of CONTENT, the <map name="CONTENT"> element is
activated. Within that <map>, the <map-conditional external="Category"> element
examines the value of the external data source field named Category, which in this example,
identifies a category of requirement and looks to activate a <map> with a name matching the
value of Category. Such a matching <map> must exist at the same level as that
<map-conditional> within the <map> element. In this case, the <map name="Software
Requirements"> or <map name="Hardware Requirements"> is activated if the Category
field has the value "Software Requirements" or "Hardware Requirements", respectively.
198
By using nested <map> elements, you can create complex AND/OR structures for your
conditionals. For example, the above example represents the following logic:
If the prototype is "CONTENT" AND the Category field is "Software Requirements",
use the Software Requirements mappings.
If the prototype is "CONTENT" AND the Category field is "Hardware Requirements",
use the Hardware Requirements mappings.
Attributes:
name
The name attribute specifies a name for this particular set of mapping rules. This is the name
specified with the default-map attribute of the <map-conditional> element or the
map-name attribute of the <map-translation> element.
199
<default>/Projects/Release2</default>
</field>
<!-- Note that the Description field's external name should not be changed and
the internal name should only be changed to reflect server and solution
settings -->
<field external="Description"
internal="ALM_Text"
on-create-only="false" />
<!-- Source Document / Segment Root -->
<map name="DOCUMENT">
<!-- Attribute is required so Excel will recognize this mapping as a
document mapping -->
<set-attribute name="rmtype" value="segment"/>
<!-- override the global Type field -->
<field internal="Type"
on-create-only="true"
field-type="type">
<default>ALM_Requirement Document</default>
</field>
<!-- Set the Shared Category value for a Document -->
<field internal="Shared Category"
on-create-only="false">
<default>Document</default>
</field>
<!-- Set a default Document Title -->
<field internal="ALM_Document Short Title"
on-create-only="true">
<default>Excel Created Document</default>
</field>
<!-- Note that the Description field's external name should not be changed
and the internal name should only be changed to reflect server and solution
settings -->
<!-- override the global Description field -->
<field external="Description"
internal="ALM_Shared Text"
on-create-only="false" />
</map>
<!-- Document Content -->
<map name="CONTENT">
<!-- Set a default Category value for document content. -->
<field external="Category" internal="Category" on-create-only="false">
<default>Comment</default>
</field>
</map>
</mapping>
200
201
Index
202
Sybase PowerBuilder 166 formulas, Excel 159
project sets, IBM Eclipse Platform 28
Sandbox G
CodeGear Delphi 11 glyphs
IBM Eclipse Platform 25 Microsoft Visual Studio SDK 62
Microsoft Visual Basic 104
Microsoft Visual C++ 108
Microsoft Visual Studio .NET 98
H
History view
Microsoft Visual Studio SDK 70
IBM Eclipse Platform 41
Sybase PowerBuilder 166
custom DSD, creating 135 HP Quality Center integration 169
adding user fields 176
custom fields
assumptions 171
HP Quality Center 174
attachment handling 181
D configure 178
configuring
date fields Document view 177
Microsoft Excel 159 Integrity 176
Microsoft Project 117, 123 Quality Center 173
date format considerations
Microsoft Excel 152 attachments 181
Microsoft Project 123 config files 179
deactivate integrations, with Integrity 4 running 183
IBM Eclipse Platform 23 creating project 174
Delphi Architect (see CodeGear Delphi Architect custom fields 174
integration) e-mail notification 181
detecting conflicts hs_err_pid.log 184
Microsoft Excel 159 ID field 174–175
Microsoft Project 128 installation overview 171
development paths installing 177
Microsoft Visual Studio .NET 92 log files 183
Document Structure Definition mapping config XML files 180
custom 135 mapping/config files 179, 180
importing 138 overview 170
importing, local 139 process config XML files 180
Document view process files 179, 180
HP Quality Center 177 QCDataMapper.log 181
Microsoft Word 132, 142 requirements user fields 175
drop member setting Type 176
Microsoft Visual Studio SDK 78 system requirements 171
dropped integrations 3 troubleshooting 183
dropping members hs_err_pid.log 184
IBM Eclipse Platform 36
DSD I
custom 135
importing 138 IBM Eclipse Platform integration 17
active change packages 33
importing local 139
active item 33
storage locations (Word) 138
adding members to project 36
E adding projects to source control 25, 27
advanced Integrity commands 37
Eclipse (see IBM Eclipse Platform integration) annotated subprojects 21, 31
e-mail notification best practices 46
general 2 checking in members 37
HP Quality Center 181 checking out members 37
enabling integrations comparing revisions 41
for IDE 3 configuring 19
IBM Eclipse Platform 3.4 19 configuring column sets 34
IBM Eclipse Platform 3.5+ 20 creating
Microsoft Visual Studio SDK 56 project sets 28
Endevor (see CA Endevor Change Manager) projects 25
Excel (see Microsoft Excel integration) Sandboxes 25
exporting displaying Integrity information 32
Word documents 141 dropping members from project 36
enabling for version 3.4 19
F enabling for version 3.5+ 20
fields, Excel enabling on Linux 19
date 159 History view 41
special 159 icon decorations 31
203
Implementer 35 Microsoft Project 117
importing project sets 29 Microsoft Word 134
importing projects 26 integrated workspace
installing 19 IBM Eclipse Platform 25, 30
Integrity commands 36 integrations, general
Integrity Worktray 34 configuring 3
label decorations 30 deactivating 4
limitations 47 dropped 3
Linux 19 new 3
online/offline mode 24 pre-steps 5
preferences 21 supported 3
pre-steps 18 tips 6
project sets using 3
sharing projects 28 Integrity SCM integrations
refactoring 40 CodeGear Delphi Architect 8
removing CodeGear JBuilder 14
projects 27 deactivating 4
setting up enabling 3
integrated workspace 25 IBM Eclipse Platform 17
preferences 21 IBM Rational Rose 49
Sharing Wizard 25, 27 Microsoft Visual Basic 103
submitting changes 37, 38 Microsoft Visual C++ 107
supported versions 18 Microsoft Visual Studio SDK 54
Synchronize Wizard 44 Sybase PowerBuilder 164
Synchronizer 42 Integrity Server
synchronizing project 42 configuration
Team Ignored directories 29 HP Quality Center 172
team synchronizing 42 Microsoft Excel 147
unassociating Microsoft Word 133
projects 27 requirements
uninstalling 23 HP Quality Center 171
upgrading/downgrading locks 33 Microsoft Excel integration 145
using 23 Microsoft Project 112
Worktray view 34 Integrity Server (see Integrity Server)
IBM Rational Rose integration 49 Integrity Synchronizer
adding members to project 51 IBM Eclipse Platform 42
browser 50 Integrity workflow integrations
checking in members 52 CA Endevor Change Manager 185
checking out members 52 HP Quality Center 169
commands 50 integrated workspace 30
configuring 50 Microsoft Excel 144
creating project 51 Microsoft Project 110
creating Sandbox 51 Microsoft Word 130
icon decorations Integrity Worktray
IBM Eclipse Platform integration 31 IBM Eclipse Platform 34
ID field, HP Quality Center column sets 34
creating 174 configuring 34
displaying 175 Integrity Worktray view
Implementer IBM Eclipse Platform 34
Change Package view 35 Integrity, roles 2
Implementer (see Implementer) item, active
importing IBM Eclipse Platform 33
DSD (Word) 138 Items view (see MKS Items view)
Enterprise Resources, Project 121 items, Visual Studio SDK
local DSD (Word) 139 creating 67
project editing 67
Visual Studio SDK 72 refreshing queries 67
project sets, IBM Eclipse Platform 29 re-running queries 67
projects, IBM Eclipse Platform 26 viewing 67
solution, Visual Studio SDK 70
template map J
Excel 150, 153 Java API libraries
installing Eclipse on Linux 19
HP Quality Center 177 JBuilder (see CodeGear JBuilder)
IBM Eclipse Platform 3.4 19
IBM Eclipse Platform 3.5+ 20 K
IDE integrations 3
keywords
Microsoft Excel 147
Microsoft Visual Studio SDK 58
204
L IBM Eclipse Platform 36
Microsoft Visual Studio SDK 78
label decorations member, moving
IBM Eclipse Platform 30 Microsoft Visual Studio SDK 79
limitations member, renaming
IBM Eclipse Platform 47 Microsoft Visual Studio SDK 79
Microsoft Excel 146 Mercury Quality Center (see HP Quality Center)
Microsoft Project 113 Microsoft Excel integration 144
Linux, IBM Eclipse integration 19 client requirements 146
locks, IBM Eclipse configuring server 133, 147
upgrading/downgrading 33 considerations 146
log files creating new list 154
excelint.log 152, 159 custom properties 151
excelintc.log 152 customizing 149
hs_err_pid.log 184 date fields/formats 159
mksvsi.log 84 date format 152
MSWord-APISession.log 143 detecting conflicts 159
projint.log 122 excelint.log 152, 159
QCDataMapper.log 181 excelintc.log 152
logging formulas 159
HP Quality Center 183 get items 154
Microsoft Excel 152 image attachments 159
Microsoft Project 122 importing
Microsoft Visual Studio SDK 84 template map 150, 153
Microsoft Word 143 installing 147
Integrity Server requirements 145
M logging 152
mapping levels 189 mapping templates 149
mapping template publishing data 155
conditional mappings 189 removing 148
levels 189 repairing 148
overview 189 retrieving items 154
XML elements 190–199 retrieving/publishing data 156
mapping_name.txt file (Word) 135, 137 setting server connection 147
master projects setting up
Microsoft Visual Studio .NET 89 Integrity Server 147
MCFG file, Word 136, 139 special fields 159
extracting 137 SSL communications 151
importing 138 synchronize 155
re-packaging 137 synchronize with query 156
member, adding system requirements 145
CodeGear Delphi 12 uninstalling 148
IBM Eclipse Platform 36 using 152
IBM Rational Rose 51 Microsoft Project integration 110
Microsoft Visual Basic 104 client requirements 112
Microsoft Visual C++ 108 components 112, 146
Microsoft Visual Studio .NET 99 configuring 119–123
Microsoft Visual Studio SDK 78 considerations 113
Sybase PowerBuilder 166 custom project fields 120
member, checking in custom properties 119
CodeGear Delphi 12 customizing Integrity 115
IBM Eclipse Platform 37 date fields 117, 123
IBM Rational Rose 52 date format 123
Microsoft Visual Basic 105 detecting conflicts 128
Microsoft Visual C++ 109 Enterprise Resources 121
Microsoft Visual Studio .NET 100 importing Enterprise Resources 121
Microsoft Visual Studio SDK 79 installing 117
Sybase PowerBuilder 167 Integrity Server requirements 112
member, checking out logging 122
CodeGear Delphi 12 MKS Integration ID 119
IBM Eclipse Platform 37 Project Server 121
IBM Rational Rose 52 projint.log 122
Microsoft Visual Basic 105 removing 119
Microsoft Visual C++ 108 repairing 119
Microsoft Visual Studio .NET 100 setting up 114
Microsoft Visual Studio SDK 79 integration template 116
Sybase PowerBuilder 167 Integrity 115
member, dropping permissions 116
205
SSL communications 121 incoming changes 64
synchronizing keywords 58
all tasks 126 limitations 83
by query 126 managing change packages 64
linked tasks 127 migrating solution from SCC 73
resources 126 MKS Items view 66
selected tasks 127 mksvsi.log 84
system requirements 111 moving members 79
task relationships 125 non-solution files 65
task types 124 online/offline mode 60
uninstalling 119 preferences 58
using 123 pre-steps 55
Microsoft Visual Basic integration 103 project/solution location 59
adding members to project 104 refreshing queries 67
checking in members 105 removing change package entries 65
checking out members 105 renaming members 79
creating project 104 re-running queries 67
creating Sandbox 104 resynchronizing solution 76
Microsoft Visual C++ integration 107 reverting solution 76
adding members to project 108 setting up 56
checking in members 109 sharing solution 67
checking out members 108 solution root 82
creating Integrity SCM project 108 toolbar 67
creating Sandbox 108 troubleshooting 84
Microsoft Visual Studio .NET integration 86 unassociated changes 65
adding members to project 99 viewing items 67
adding solution 88 viewing Sandbox 77
best practices 88 Work In Progress 63
checking in members 100 Work In Progress view
checking out members 100 displaying 63
creating Microsoft Word integration 130
project 98 active document export 141
Sandbox 98 assumptions 131
development paths 92 custom DSD 135
implementing 87 Document view 132, 142
joining solution 98 DSD storage locations 138
master projects 89 exporting documents 141
optimistic locking 91 importing
parallel development 91 DSD 138
preferences 90 local DSD 139
reusing code 88 importing DSD 138
solution root 87 importing local DSD 139
troubleshooting 101 installing 134
Microsoft Visual Studio SDK integration 54, 66 integration errors 143
active change packages 61 logging 143
adding files 78 mapping_name.txt file 135, 137
adding members 78 MCFG file 136, 139
adding project to shared solution 70 extracting 137
advanced commands 80 importing 138
best practices 81 re-packaging 137
branching solution 75 MSWord-APISession.log 143
checking in members 79 name.txt file 135, 137
checking out members 79 overview 131
checkpointing solution 77 process-items.xlst file 135, 141
configuring 56 rich content support 131
creating items 67 setting server connection 133
creating Sandbox 70 setting up
default solution location 58 Integrity Server 133
defining top-level projects 59 static.txt file 135, 137, 139
dropping members 78 system requirements 133
dropping project from shared solution 71 troubleshooting 143
editing items 67 understanding XML mapping 140
enabling plug-in 57 uninstalling 135
file status 64 MKS Integration ID
glyphs 62 Microsoft Project 119
ignoring entities 74 MKS Items view
importing project 72 displaying 66
importing solution 70 Microsoft Visual Studio SDK
206
toolbar 67 Microsoft Excel 148
MKS Work In Progress view (see Work In Progress view) Microsoft Project 119
MKS Worktray Microsoft Word 135
Microsoft Visual Studio SDK (see MKS Items view) removinging
moving member project
Microsoft Visual Studio SDK 79 IBM Eclipse Platform 27
renaming member
N Microsoft Visual Studio SDK 79
name.txt file (Word) 135, 137 repairing
new integrations 3 Microsoft Excel 148
Microsoft Project 119
O requirements, Quality Center
adding user fields 176
online/offline mode user fields 175
IBM Eclipse Platform 24
rich content, Word 131
Microsoft Visual Studio SDK 60
embedded images 132
optimistic locking embedded objects 132
Microsoft Visual Studio .NET 91
fonts 132
headings 132
P hyperlinks 132
parallel development lists 132
Microsoft Visual Studio .NET 91 tables 132
plug-ins roles, when using Integrity 2
Microsoft Visual Studio SDK 57
PowerBuilder (see Sybase PowerBuilder) S
preferences, setting Sandbox
IBM Eclipse Platform 21
creating
active change package 22
CodeGear Delphi 11
annotated subprojects 21
IBM Eclipse Platform 25
drop sandbox 22 IBM Rational Rose 51
Microsoft Visual Studio .NET 90
Microsoft Visual Basic 104
Microsoft Visual Studio SDK 58
Microsoft Visual C++ 108
process-items.xlst file (Word) 135 Microsoft Visual Studio .NET 98
understanding 141
Microsoft Visual Studio SDK 70
project
Sybase PowerBuilder 166
creating setup
CodeGear Delphi 11
Integrity
HP Quality Center 174
HP Quality Center 176
IBM Eclipse Platform 25 Microsoft Project 115
IBM Rational Rose 51
Integrity Server
Microsoft Visual Basic 104
HP Quality Center 172
Microsoft Visual C++ 108 Microsoft Excel 133, 147
Microsoft Visual Studio .NET 98
Microsoft Word 133
Microsoft Visual Studio SDK 70
Microsoft Project 114
Sybase PowerBuilder 166 integration template 116
removing
permissions
IBM Eclipse Platform 27
Microsoft Project 116
synchronizing shared subprojects
IBM Eclipse Platform 42
Microsoft Visual Studio .NET 88
unassociating
Sharing Wizard 25, 27
IBM Eclipse Platform 27 shortcut menu 66
Project (see Microsoft Project integration)
solution
project sets, IBM Eclipse Platform
Microsoft Visual Studio .NET 87, 88
creating 28 Microsoft Visual Studio SDK
importing 29
adding project 70
sharing 28
branching 75
projects, IBM Eclipse Platform checkpointing 77
importing 26
dropping project from shared 71
importing 70
Q migrating from SCC 73
QCDataMapper.log 181 resynchronizing 76
Quality Center (see HP Quality Center integration) reverting 76
sharing 67
R viewing Sandbox 77
Rational Rose (see IBM Rational Rose) solution root
refactoring Microsoft Visual Studio .NET 87
IBM Eclipse Platform 40 Microsoft Visual Studio SDK 82
removing special fields, Excel 159
207
SSL communications Microsoft Word 143
Microsoft Excel 151
Microsoft Project 121 U
static.txt file (Word) 135, 137 unassociating
understanding 139 project
submit changes IBM Eclipse Platform 27
IBM Eclipse Platform 37, 38 uninstalling
supported integrations 3 IBM Eclipse Platform 23
Sybase PowerBuilder integration 163 Microsoft Excel 148
adding members to project 166 Microsoft Project 119
checking in members 167 Microsoft Word 135
checking out members 167 user, described 2
creating
project 166 V
Sandbox 166
Visual Basic (see Microsoft Visual Basic)
enabling Integrity 166
Synchronize Wizard 44 Visual C++ (see Microsoft Visual C++)
Visual Studio .NET (see Microsoft Visual Studio .NET)
synchronizing
Visual Studio SDK (See Microsoft Visual Studio SDK)
IBM Eclipse Platform
project 42
Microsoft Excel
W
data 155 WebSphere (see IBM Eclipse Platform integration)
with query 156 Word (see Microsoft Word integration)
Microsoft Project Word documents
all tasks 126 exporting 141
by query 126 importing DSD 138
linked tasks 127 importing local DSD 139
resources 126 Work In Progress view
selected tasks 127 displaying 63
system requirements file status 64
HP Quality Center 171 incoming changes 64
Microsoft Excel 145 managing change packages 64
Microsoft Project 111 Microsoft Visual Studio SDK 63
Microsoft Word 133 non-solution files 65
removing change package entries 65
T shortcut menu 66
unassociated changes 65
task relationships
Worktray
Microsoft Project 125
task types Implementer Change Package view 35
Worktray (see Integrity Worktray)
Microsoft Project 124
Worktray view
team synchronization
running 44 Eclipse (see Integrity Worktray view)
Visual Studio (see MKS Items view)
symbols 43
Synchronize Wizard 44
team synchronizing X
IBM Eclipse Platform 42 XML files
Test Director (see HP Quality Center) HP Quality Center
toolbar mapping config 180
Implementer 35 process config 180
Integrity Worktray, Eclipse 34 XML mapping file, Word 140
MKS Items view 67 XML template
toggling 57 conditional mappings 189
troubleshooting elements 190–199
HP Quality Center 183 levels 189
Microsoft Visual Studio .NET 101 overview 189
Microsoft Visual Studio SDK 84
208