MKS Integrity Server 2009 Administration Guide

® 

Integrity 

MKS Integrity Server 

2009 

Administration Guide

MKS Integrity Server 2009 

Administration Guide 

Copyright © 2001–2009 MKS Software Inc.; in Canada copyright owned by MKS Inc. All rights reserved. 

MKS makes no warranty of any kind with regard to this material, including, but not limited to the implied warranties of merchant ability, 

performance, or fitness for a particular purpose. MKS shall not be liable for errors contained herein, or for any direct, indirect, incidental, 

or consequential damages resulting from the use of this material. 

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in 

any form by any means, without written permission from MKS. 

MKS, Implementer, MKS Toolkit, Sandbox, NuTCRACKER, and MKS Federated Server are trademarks of MKS Inc. All other trademarks 

are the property of their respective holders. 

Corporate Headquarters Worldwide Offices: 

410 Albert Street 

Waterloo, ON N2L 3V3 

Canada 

tel: 519 884 2251 

fax: 519 884 8861 

sales (toll free): 800 265 2797 

www.mks.com 

This document is uncontrolled when printed or copied. 

1815 South Meyers Rd. 

Suite 220 

Oakbrook Terrace, IL USA 

60181 

tel: 630 827 4900 

fax: 630 629 9167 

sales (toll free): 800 633 1235 

12701 Fair Lakes Circle 

Suite 350 

Fairfax, VA USA 

22033 

tel: 1 703 803 3343 

fax: 1 703 803 3344 

sales (toll free): 1 800 637 8034 

Martinstraße 42-44 

73728 Esslingen 

Germany 

tel: +49 711 351775 0 

fax: +49 711 351775 7555 

Third Floor, Duke’s Court 

Duke Street, Woking 

Surrey 

GU21 5BH 

United Kingdom 

tel: +44 (0)1483 733900 

fax: +44 (0)1483 733901 

sales: +44 (0)1483 733919 

3 Killiney Road 

#07-05 Winsland House 1 

Singapore 239519 

tel: +65-6732-8768 

fax: +65-6732-0768 

5th Floor, Unosawa Tokyu Building 

1-19-15, Ebisu, Shibuya-ku, 

Tokyo 150-0013, Japan 

tel: +81-3-5422-9503 

fax: +81-3-5422-9509

Table of Contents 

Chapters 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 

Assumptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

Setting Up and Using MKS Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

Workflows and Documents Setup. . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Configuration Management Setup . . . . . . . . . . . . . . . . . . . . . . . . . 7 

Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 

2 MKS Integrity Administration Client . . . . . . . . . . . . . . . . . . 9 

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 

Opening Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 

Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

Closing Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

Shutting Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

Application Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 

Quick Access Keys (GUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Common Dual List Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Filtering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Working With Favorites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

Display Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Server Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

Print Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 

MKS Integrity Server Alert Messages. . . . . . . . . . . . . . . . . . . . . . 32 

Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 

MKS Integrity Client Preferences . . . . . . . . . . . . . . . . . . . . . . . . . 35 

Server Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

MKS Integrity Administration Client Preferences . . . . . . . . . . . 38 

Setting MKS Integrity View Preferences . . . . . . . . . . . . . . . . . . . 41 

Authorization Administration Preferences . . . . . . . . . . . . . . . . . 41 

Deploy Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 

Administration Command Line Interface . . . . . . . . . . . . . . . . . . . . . . 42 

Defining Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 

Rule Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 

Working With Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 

Selecting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

Viewing Administration History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

i


ii 

3 ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 

Understanding ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 

Viewing ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

Basic ViewSet Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 

Creating ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 

Editing ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 

Copying ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

Deleting ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

Making ViewSets Available to Users . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

Process Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

Converting Personal ViewSet to Unpublished ViewSet . . . . . . 58 

Publishing ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

Testing ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 

Mandatory ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 

Administering Published ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 

Published ViewSet Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

Fetching Published ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 

Updating Published ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 

ViewSet Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 

Permission to Publish ViewSets. . . . . . . . . . . . . . . . . . . . . . . . . . . 66 

Published ViewSet Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . 66 

ViewSets FAQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 

4 Workflow Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 

Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 

Assessing Your Current Product Development Process . . . . . . . . . . 70 

Assigning Administrators for MKS Integrity . . . . . . . . . . . . . . . . . . . 74 

MKS Integrity Administration Permissions. . . . . . . . . . . . . . . . . 76 

Assigning Administrators Using Command Line Interface . . . 77 

States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 

Working in States View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 

Creating States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 

Editing States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 

Viewing States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 

Deleting States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

Moving States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

State Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 

Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 

Working in Types View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

Creating Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 

Configuring Type Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 

Editing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 

Copying Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 

Viewing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93


Deleting Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 

Moving Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 

Assigning Type Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 

Setting Up Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

Setting the Test Management Role for Types . . . . . . . . . . . . . . 112 

Setting Item Editability for Types . . . . . . . . . . . . . . . . . . . . . . . . 114 

Setting Type Visibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 

Setting Type Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 

Setting Field Visibility for Types . . . . . . . . . . . . . . . . . . . . . . . . . 120 

Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 

Working in Fields View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 

Using Display Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 

Creating Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

Editing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 

Viewing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 

Deactivating Picklist Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 

Deleting Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 

Moving Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

Managing Field Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 

Workflow View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 

Creating Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 

Configuring Self Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 

Viewing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 

Managing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 

Printing Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 

Saving Workflow as Image. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 

Testing Workflow With Admin Migration Wizard . . . . . . . . . 161 

Considerations When Modifying Visibility, Editability, and Types 178 

Deleting Admin Provided Objects and Items . . . . . . . . . . . . . . . . . . 179 

Deleting Admin Provided Objects . . . . . . . . . . . . . . . . . . . . . . . 179 

Deleting Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 

Setting Up E-mail Notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 

Permissions for E-mail Notification . . . . . . . . . . . . . . . . . . . . . . 181 

Troubleshooting E-mail Notification . . . . . . . . . . . . . . . . . . . . . 185 

5 Customizing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 

Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 

Customizing Item Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 

Understanding Template Designer. . . . . . . . . . . . . . . . . . . . . . . 189 

Creating New Presentation Template. . . . . . . . . . . . . . . . . . . . . 198 

Editing Presentation Template . . . . . . . . . . . . . . . . . . . . . . . . . . 203 

Copying Presentation Template . . . . . . . . . . . . . . . . . . . . . . . . . 214 

Viewing Presentation Templates. . . . . . . . . . . . . . . . . . . . . . . . . 214 

Deleting Presentation Template . . . . . . . . . . . . . . . . . . . . . . . . . 215 

iii


iv 

Customizing Rich Content Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 

Customizing Report Presentation Templates . . . . . . . . . . . . . . . . . . 219 

Report Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 

Report Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 

Customizing Test Verdicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 

Working in the Test Verdicts View . . . . . . . . . . . . . . . . . . . . . . . 234 

Creating a Test Verdict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 

Editing a Test Verdict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 

Deactivating Test Verdicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 

Configuring Attachment Size Limits . . . . . . . . . . . . . . . . . . . . . . . . . 237 

Configuring Limits for Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 

System Query Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 

Query Timeouts for Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 

Maximum Query Item Count . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 

Configuring Context Based Text Searching . . . . . . . . . . . . . . . . . . . . 240 

Setting Up Electronic Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 

Customizing Electronic Signature Trigger. . . . . . . . . . . . . . . . . . . . . 241 

Admin Provided Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 

Using Type Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 

6 Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 


Workflow and Document Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 

Projects View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 

Managing Metadata for Workflow and Document Projects . . 257 

Deactivating Workflow and Document Projects. . . . . . . . . . . . 259 

Assigning MKS Integrity Project Administrator. . . . . . . . . . . . 260 

Configuration Management Projects . . . . . . . . . . . . . . . . . . . . . . . . . 262 

Configuration Management Interfaces. . . . . . . . . . . . . . . . . . . . 263 

Organizing Your Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 

Working With Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 

Using Configuration Management Project Metrics . . . . . . . . . 280 

Working With Subprojects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 

Sharing Archives With Other Projects . . . . . . . . . . . . . . . . . . . . 287 

7 Computed Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 291 


Computed Expression Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 

Computed Expression Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 

General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 

Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 

Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 

Empty Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 

Dates, Times, and Time Zones. . . . . . . . . . . . . . . . . . . . . . . . . . . 295 

Timestamp Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295


Date Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 

User and Group Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 

Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 

Function Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 

Creating Computed Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 

Calculating Static Computed Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 315 

Using Computed Fields to Chart Historical Trends. . . . . . . . . . . . . 316 

Scheduling Computation Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 

Using Computed Fields to Calculate State Metrics . . . . . . . . . . . . . 319 

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 

Performance and Scalability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 

8 Change Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 

Where to Go From Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 

MKS Integrity Change Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 

Viewing Change Package Types . . . . . . . . . . . . . . . . . . . . . . . . . 325 

Changing Change Package Type Order . . . . . . . . . . . . . . . . . . . 326 

Editing Change Package Types . . . . . . . . . . . . . . . . . . . . . . . . . . 327 

Viewing Change Package Types . . . . . . . . . . . . . . . . . . . . . . . . . 330 

Creating Change Package Types . . . . . . . . . . . . . . . . . . . . . . . . . 331 

Deleting Change Package Types . . . . . . . . . . . . . . . . . . . . . . . . . 332 

Modifying Change Package Attributes . . . . . . . . . . . . . . . . . . . 333 

Modifying Change Package Entry Attributes . . . . . . . . . . . . . . 336 

User Operations for Created Change Package Types . . . . . . . 340 

Modifying CP Entries for Created CP Types. . . . . . . . . . . . . . . 342 

Configuration Management Change Packages . . . . . . . . . . . . . . . . . 343 

Using Change Package Reviews . . . . . . . . . . . . . . . . . . . . . . . . . 344 

How Change Package Review Works . . . . . . . . . . . . . . . . . . . . 345 

Review Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Change Package Review E-mail Notification . . . . . . . . . . . . . . 346 

9 Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 

Event Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 

About Trigger Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 

JavaScript Language Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . 351 

JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 

Overview of Workflow and Document Triggers . . . . . . . . . . . . . . . 355 

Workflow and Document Event Categories . . . . . . . . . . . . . . . 356 

Transactionality of Workflow and Document Event Triggers 357 

Planning Workflow and Document Triggers . . . . . . . . . . . . . . 358 

Script Library for Workflow and Document Triggers . . . . . . . 358 

Coding Workflow and Document Triggers . . . . . . . . . . . . . . . . 359 

Using Workflow and Document Event Triggers . . . . . . . . . . . 361 

Overview of Configuration Management Triggers . . . . . . . . . . . . . 374 

v


vi 

Overview of Configuration Management Server-Side Triggers. . . 

374 

Overview of Configuration Management Client-Side Triggers 383 

Planning Configuration Management Triggers . . . . . . . . . . . . 389 

Script Library for Configuration Management Triggers . . . . . 390 

Referencing Configuration Management Beans in Trigger Scripts 

390 

Coding Configuration Management Triggers. . . . . . . . . . . . . . 391 

Debugging Configuration Management Client-Side Environment 

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 

Error Handling Beans and Methods . . . . . . . . . . . . . . . . . . . . . . 392 

abortScript() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 

DEBUG Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 

Logging Trigger Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 

Logging Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 

Using the MKS API in Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . 396 

API Beans and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 

API Trigger Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 

Running Custom Java Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 

Using Java Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 

Tips and Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 

Appendixes A Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 

Gathering Important Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 

Running MKS Integrity Server as Application . . . . . . . . . . . . . . . . . 405 

Differencing MKS Integrity Server Properties Files . . . . . . . . . . . . . 406 

Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 

MKS Integrity Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 

MKS Integrity Client Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 

MKS Integrity Server Logging Levels. . . . . . . . . . . . . . . . . . . . . . . . . 407 

Miscellaneous Logging Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 

FLEXnet Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 

Dr. Watson Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 

Creating Integrations Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 

Running MKS Integrity Server Diagnostics. . . . . . . . . . . . . . . . . . . . 414 

Collecting Properties and Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . 421 

runstacktrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 

mksis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 

isutil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 

Starting Server in Safe Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 

Troubleshooting Database Repository . . . . . . . . . . . . . . . . . . . . . . . . 427 

Troubleshooting Kerberos and Kerberos Single Sign-On . . . . . . . . 428 

Troubleshooting Configuration Management Reporting . . . . . . . . 430


B Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 

C Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 

vii


vii

C HAPTER ONE 

Introduction 

Understanding This Guide 

1 

The MKS Integrity Server 2009 Administration Guide gives you the information you need 

to build a basic understanding of MKS Integrity, and to configure it for your 

organization. It also provides information on post-installation configuration and setup 

for workflows and documents; software management; and the associated access control 

lists and event triggers. 

Information on MKS Integrity Server installation, configuration, and security is not 

covered in this guide. For information on those tasks, see the MKS Integrity Server 2009 

Installation and Configuration Guide. 

In this guide, the person responsible for setting up MKS Integrity is referred to as the 

administrator. The administrator installs the MKS Integrity Server on a network, defines 

and customizes the software clients, and then creates the user accounts. Anyone who 

uses the MKS Integrity software to perform specific tasks is referred to as the user. 

For MKS Integrity, the person who sets up and configures MKS Integrity is referred to as 

the super administrator. The super administrator can also delegate certain tasks related to 

projects for workflows and documents, and types to a project administrator and type 

administrator. 

1

Chapter 1: Introduction 

About This Guide 

2 

For content that is essential and applicable to all guides, MKS provides a single location for 

you to access the information. See the MKS Integrity 2009 Getting Started Guide for 

information on the following topics: 

a complete list of related documentation 

descriptions of the typographical conventions used in this guide 

getting help from MKS Customer Care 

consulting MKS Professional Services 

how to provide feedback on this documentation 

detailed descriptions for base concepts used in MKS Integrity 

installing and configuring the MKS Integrity Client 

an overview of the interfaces available for the MKS 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. 

This guide is designed to provide administrators with all the information needed to 

configure and maintain MKS Integrity at their site. The guide is divided into the following 

chapters and appendixes: 

Chapter 2: “MKS Integrity Administration Client” on page 9 

Describes the MKS Integrity Server Administration interface and provides a general 

orientation to using the MKS Integrity Administration Client for setting up permissions; 

workflows and documents; and configuration management policies. 

Chapter 3: “ViewSets” on page 49 

Provides information on administering ViewSets for users to import from the 

MKS Integrity Server. 

Chapter 4: “Workflow Management” on page 69 

Describes how to construct an item workflow and its components. 

Chapter 5: “Customizing Workflow” on page 187 

Advanced information on customizing workflows used in your organization. 

Chapter 6: “Projects” on page 247 

Describes the types of projects available and how to use them effectively.

Assumptions 

Chapter 7: “Computed Expressions” on page 291 

Provides information on performing calculations between fields and their uses. 

Chapter 8: “Change Packages” on page 323 

Assumptions 

Describes the types of change packages available, how to customize them, and how to 

use them effectively. 

Chapter 9: “Event Triggers” on page 349 

Describes how to use event triggers with workflows and documents, and configuration 

management. 

Appendix A: “Troubleshooting” on page 401 

Describes available monitoring and diagnostic tools that can be used with assistance 

from MKS Customer Care. 

Appendix B: “Glossary” on page 431 

Defines many of the common terms used when talking about workflows and 

documents; configuration management; and the MKS Integrity Server. 

Before using MKS Integrity, understand that the content in this guide is based on the 

following assumptions of your knowledge and experience: 

Installing and Configuring the MKS Integrity Server 

You fully understand the hardware platforms and operating systems you are installing 

the MKS Integrity Server on, that is, Windows, Solaris, Linux, IBM AIX, or HP-UX. 

Depending on the database you are using, that you have already set up and tested: 

MS SQL Server database, and you are familiar with MS SQL Server Administration 

and MS SQL Enterprise Manager 

Oracle database, and you are familiar with Oracle administration and configuration 

procedures 

DB2 database, and you are familiar with DB2 Universal Database client 

administration and configuration procedures 

DB2 database for System i, and you are familiar with DB2 Universal Database client 

administration and configuration procedures 

You understand the native security realm of your system. For a complete list of security 

realms and their configuration, see the MKS Integrity Server 2009 Installation and 

Configuration Guide. 

3


4 

If you want to use LDAP, at a minimum you are familiar with Distinguished Names 

(DN), LDAP search filters, and LDAP schemas. 

You understand the character set encoding requirements of your e-mail system. 

Managing Workflows and Documents 

You understand HTML and XML, if you are creating custom report presentation 

templates for workflows and documents or making changes to the MKS Integrity Server 

home page. 

TIP For useful information on HTML, browse to www.w3.org/MarkUp. 

If you are implementing event triggers, you have experience with JavaScript and 

understand logical rules. 

You understand Cascading Style Sheets (CSS), if you are creating and editing screen and 

print styles for rich content fields and reports. 

Setting Up and Using MKS Integrity 

The administrator installs and/or configures, workflows and documents; configuration 

management; and the MKS Integrity Server. For MKS Integrity, the administrator also 

installs the database on a network, defines and customizes item types and workflow, and 

creates additional user accounts, allowing users to access the program. 

For MKS Integrity, the person who sets up and configures MKS Integrity is referred to as the 

super administrator. The super administrator can also delegate certain tasks related to projects 

for workflows and documents, and types to a project administrator and type administrator. 

A user is anyone who needs to work with one or both of MKS Integrity components. Users 

are assigned user permissions by the administrator. Users are also assigned to groups that 

have specific MKS Integrity group permissions assigned by the administrator. 

Other roles or responsibilities may also apply, depending on how you want to implement 

MKS Integrity and depending on your organization’s development process. The advantage 

of MKS Integrity is its flexibility to fit your organization.

Workflows and Documents Setup 


Additional tasks required of a super administrator for the workflows and documents 

component include: 

defining and creating item types 

customizing fields 

assigning users and user groups 

determining privileges 

defining workflow 

setting up any event triggers 

The super administrator can also restrict the visibility and editability of workflow and 

document objects. Before users start using the system, the administrator must inform them 

about the scope of their user privileges. 

MKS Integrity ships with some standard fields and values. Therefore, the super 

administrator needs to define other workflow and document objects (building blocks) before 

the rest of the application can be configured. 

MKS Integrity uses items to track changes. An unlimited number of items and relationships 

may be tracked. For example, MKS Integrity can be configured so that a problem item is 

associated with the item that resolves it for easy tracking and monitoring of both items. 

In workflow and document management, a project contains labels that help you sort and 

organize items in a hierarchical structure. 

Some items types may be configured to allow file attachments and a change package. File 

attachments may be sent by a customer to provide additional information. When attached to 

an item, file attachments and change packages allow tracking of items in a structured and 

organized manner. 

For each item type defined, a workflow must be established to effectively track and monitor 

the progress of work on an item. For example, if the process consists of design, 

implementation, and release stages, an enforced workflow allows you to know the number of 

items in each stage. 

Starting with an appropriate design for the workflow of items, the administrator configures 

MKS Integrity to reflect that workflow. For information on setting up workflow, “Workflow 

Management” on page 69. 

Workflow for an item must also take into account the resources responsible for that item at 

each stage of the development cycle. MKS Integrity allows users and user groups to assign 

responsibility for an item. 

MKS Integrity can also be configured to notify individuals by e-mail about a variety of 

conditions, including having items assigned to them or about an item state change. 

5


6 

The super administrator can also set up schedule- and rule-based event triggers to automate 

certain tasks. For example, when an item is closed, a rule-based event trigger can close all of 

the underlying tasks. If an item was in a development state after the required completion 

date had passed, a schedule-based event trigger could send an e-mail to the project manager. 

For more information on event triggers for workflows and documents, see “Event Triggers” 

on page 349. 

MKS Integrity allows you to define projects that help users sort all items in the database. 

Projects are folders that help you organize items in a hierarchical structure. To see the items 

specific to a project, a user must have privileges to view this project. As an administrator, you 

must assign permissions to user groups before they can see the project. 

The super administrator adds users, creates user groups and sets their access permissions, 

depending on the responsibilities given to the user. 

After defining the users and user groups responsible for processing items during the 

development cycle, additional fields can be created to support the workflow and to 

complement the standard fields. Some standard fields include Summary, State, Assigned 

User, Assigned Group, and Project. The customizable fields may be based on data types, 

values, visibility, relevance, editability, and description. Both standard and customized fields 

can be used to determine the mandatory fields users must fill in before changing the state of 

an item. 

The super administrator customizes the additional fields and defines mandatory fields while 

designing a workflow for an item. 

Besides being able to work with items, users can also use query, report, and chart features. 

A query is a request to select and list the items that meet specific selection criteria. 

Reports are summaries of the data in your project, based on the standard and custom 

fields of item types. 

Charts present trends over time or distributions of the data. The are also based on the 

standard and custom fields of item types. These include line graphs, pie graphs, bar 

graphs, XY (scatter) graphs, bubble graphs, and tables. 

Table charts show a summary of data with aggregate values. Graphical charts show 

users a summary of the data. 

You can run queries, reports, and charts on item data to monitor progress and evaluate the 

effectiveness of the problem resolution process. You can also create a dashboard that 

provides a high-level overview of the progress of a project. 

A dashboard is a static, user-definable view comprised of any combination of charts, reports, 

images, labels, and links to reports, queries and Web sites.

Configuration Management Setup 


Before using MKS Integrity to manage the configuration management projects in a 

development environment, the administrator is responsible for taking a careful look at how 

projects and directories are currently organized on the file system. This allows the 

administrator to make decisions about how best to organize projects, use subprojects, or 

share members between projects. 

One of the most important aspects of administering an MKS Integrity site is ensuring that 

only appropriate users can access certain features. MKS Integrity provides a number of 

different security features to help you keep your system safe and secure, and to complement 

security within MKS Integrity, including: 

available security realms 

user authentication based on an integration with existing authentication mechanisms 

such as UNIX and NT 

disabled guest authentication 

secure sockets layer (SSL) protocol 

access control lists (ACLs) 

file level security 

For information on setting up a secure system for the preceding listed items, see the 

MKS Integrity Server 2009 Installation and Configuration Guide. 

The overall security environment for configuration management is divided into three major 

components: 

a server-based authentication scheme for authenticating users and authorizing access 

based on permissions 

a data management subsystem realm for maintaining the underlying security database 

a distributed management application for providing a variety of administrative user 

interfaces to the security database 

If you are responsible for installing and setting up the MKS Integrity Server in your 

organization or if you are responsible for managing and maintaining the implementation of 

configuration management, you should set yourself up as an administrator. As 

administrator, you are responsible for assigning appropriate permissions to users and 

groups. 

Once the appropriate access permissions are assigned, the administrator organizes the 

configuration management environment by creating projects and subprojects. For more 

information on setting up projects, see “Configuration Management Projects” on page 262. 

MKS Integrity can also be configured to use server-side event triggers. Event triggers allow 

you to customize your configuration management environment further and to control the 

7


8 

way users may operate in that environment. For more information on event triggers, see 

“Event Triggers” on page 349. 

Where to Go Next 

The following table summarizes the steps you should follow to administer MKS Integrity: 

To Do This … See … 

Learn how to use the MKS Integrity 

Administration Client. 

Create ViewSets for users to download into their 

MKS Integrity Clients. 

Create the building blocks of your workflow such 

as fields, states, and a type. Then construct the 

workflow with state transitions. 

Customize the workflow by creating item 

presentation templates, as well as perform 

customization on other system provided objects. 

Create projects to manage workflow and 

document tasks and configuration management 

members. 

Create change packages for workflows and 

documents, and configuration management to 

control, record, and apply member operations. 

“MKS Integrity Administration Client” on page 9 

“ViewSets” on page 49 

“Workflow Management” on page 69 

“Customizing Workflow” on page 187 

“Projects” on page 247 

“Change Packages” on page 323

C HAPTER TWO 

MKS Integrity Administration 

Client 

Using the MKS Integrity Server Administration Interface 

2 

The MKS Integrity Administration Client allows you to manage Access Control Lists 

(ACLs), manage and distribute ViewSets, set up workflows and documents, configure 

configuration management policies, set up Deploy, and send alert messages through a 

GUI. The client interface provides a single, centralized access point for the most common 

administration tasks. 

In this guide, all procedures 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. 

This chapter describes the functionality available through the MKS Integrity 

Administration Client and explains how to navigate the interface. 

This chapter contains the following topics: 

“Introduction” on page 10 

“Preferences” on page 34 

“Administration Command Line Interface” on page 42 

“Defining Rules” on page 43 

“Viewing Administration History” on page 47 

9

Chapter 2: MKS Integrity Administration Client 

Introduction 

10 

A graphical user interface, or GUI, is a program interface that uses a number of visual 

components (such as icons, pointers, and pull-down menus) to execute commands. Working 

in a GUI allows the user to give instructions to the computer without having to learn a 

specific command language. The MKS Integrity Administration Client interface is a GUI 

designed for carrying out most administrative commands from a central location. 

In addition, you can connect to multiple MKS Integrity Servers in a single session and 

perform maintenance on each server. 

Opening Interface 

IMPORTANT If multiple administrators are working in the Permissions views, 

changes are updated dynamically as the server refreshes the changed view each 

time it is newly accessed by another user. 

If two administrators are concurrently editing the same entry, the view cannot be 

updated and the system processes the changes that are received first. 

After installation, the first step to using the MKS Integrity Administration Client is to open 

the interface. You can open the client from the program menu, desktop icon, or from a 

command line prompt. Once the interface is open, you are prompted to log on. 

NOTE When opening the MKS Integrity Administration Client, you may be 

prompted to download a client service pack if one is required. For more information 

on client service pack distribution, see the MKS Integrity Server 2009 Installation and 


To open the MKS Integrity Administration Client 

CLI EQUIVALENT integrity admingui 

1 From the Windows Program menu, select MKS Integrity > MKS Integrity Administration. 

From UNIX, open a shell and type integrity admingui. 

The MKS Integrity Client interface displays. You are prompted to log in.

Logging Out 

Closing Client 

Introduction 

2 Log in by entering your user ID and password. The MKS Integrity Administration Client 

displays the Administration window. 

NOTE You can open another instance of the MKS Integrity Administration Client by 

selecting Tools > Administration. 

Upon restarting the MKS Integrity Administration Client, view settings are 

automatically restored and you are prompted to connect to the server or servers 

used during the previous session. 

You can log out of the MKS Integrity Administration Client and log in as another user, or 

allow another user to log in. 

To log out of the MKS Integrity Administration Client 

CLI EQUIVALENT integrity disconnect 

1 Select File > Server Connection > Disconnect. 

Depending on your system preferences, a dialog box asks you to confirm that you want 

to close all current views and disconnect your server connection. To disable this dialog 

box, see “Server Connections” on page 29. 

2 To disconnect from the server, click Yes. The Confirm Disconnect dialog box displays. 

NOTE Disconnecting from the server closes all current views. 

3 To disconnect all clients that are connected to that server, click Yes. 

If multiple servers are available in your Server Connection list, all clients running 

automatically connect using the next available server for that product. For example, 

MKS Integrity connects to the next available MKS Integrity enabled server in the Server 

Connection list. 

You can close the MKS Integrity Administration Client so it is no longer displayed on the 

desktop, but leave it running in the background, logged in, and with client windows intact. 

To quit an MKS Integrity Administration Client session 

Do one of the following: 

Select File > Close Window. 

11


Shutting Down 

12 

Click the X at the top right-hand corner of the MKS Integrity Administration Client 

window. 

NOTE By default, these commands close the MKS Integrity Client; however, you can 

also configure them to shut down the MKS Integrity Client. For more information, 

see “To set MKS Integrity Client preferences from the GUI” on page 35. 

Even though the client is not displayed on the desktop, it is still running in the background. 

On Windows, a running client is indicated by an MKS Integrity Client icon in the system tray. 

Display the client by doing one of the following: 

Clicking the application shortcut (see “Opening Interface” on page 10). 

On Windows, right clicking the MKS Integrity Client icon in the system tray and 

selecting Open. 

On Windows, double clicking the MKS Integrity Client icon in the system tray. 

When you are finished using the MKS Integrity Administration Client, you can shut down 

the client completely in one action. 

To shut down the MKS Integrity Administration Client 

CLI EQUIVALENT integrity exit 

1 Do one of the following: 

From the MKS Integrity Administration Client, select File > Exit. 

On Windows, right click the MKS Integrity Client icon in the system tray, and select 

Exit. 

The Confirm MKS Integrity Client Exit dialog box displays. 

IMPORTANT Clicking Yes shuts down all clients, such as the MKS Integrity Client, in 

addition to the MKS Integrity Administration Client. 

2 To shut down all clients, click Yes. All MKS Integrity Clients close, all server connections 

disconnect, and the client process shuts down.

Application Window 

Title Bar 

Menu Bar 

Toolbars 

Application 

Window 

Tree Pane 

Status Bar 

Introduction 

The MKS Integrity Administration Client interface contains a number of common features 

explained in this section. 

Title Bar 

TIP You can access program functions through the menu items listed on the menu 

bar, as well as through the shortcut menu when you right click the mouse. 

The title bar is the uppermost component of the application window. On the left side, the title 

bar displays the name of the MKS Integrity Client. On the right side, the title bar displays the 

standard Windows buttons for minimizing, resizing, and closing the application window. 

Menu Bar 

Workspace Display Pane Shortcut Menu 

The menu bar is located directly below the title bar. Each menu contains available 

commands. When you first open the MKS Integrity Administration Client, there are four 

menus in the menu bar: File, Tools, Window, and Help. The list of available menus and 

13


14 

commands varies depending on the view or window that is active at any given time (for 

example, working with permissions or configuration management policies). 

Toolbars 

Immediately below the menu bar are the toolbars that provide easy access to the most 

commonly used administration commands. Toolbar functions are carried out by clicking the 

appropriate toolbar button with the left mouse button. 

Most toolbar buttons only become available when an item is selected in a certain window. 

For example, selecting Policies in the node tree displays the toolbar buttons for policy 

commands. 

Tooltips explain the function of each toolbar button and appear when you pause the mouse 

pointer over the button. 

Shortcut Menu 

The MKS Integrity Administration Client supports standard shortcut menus. To display the 

menu of actions you can perform on a selected item, select and right click the item. The menu 

that displays depends upon the item you have selected. 

Tree Pane 

The tree pane displays the configurable components in a node tree view. The visibility of 

nodes in the tree pane depends on the applications that are installed on the server. For 

example, if the workflows and documents component is not installed on the server, the 

Workflows and Documents node does not display in the tree pane. 

As administrator, your ability to work with subnodes in the tree pane depends on the 

permissions allowed to you. For example, if you are not allowed the EditPolicy and 

ViewPolicy permissions under mks:si, you cannot modify configuration management 

policies under the Configuration Management node. For more information, see the 


To work with the available sections in a node, you can double click the node name or click the 

expansion button (+) to expand the node. 

NOTE When working in the tree pane, you can also open a new window from any 

node by right clicking and selecting Open New Window from the shortcut menu.

The following table specifies where to find information on nodes in the tree pane. 

View Node Location 

MKS Domain See the MKS Integrity Server 2009 Installation and 


ViewSet Distribution See “ViewSets” on page 49. 

Configuration See the MKS Integrity Server 2009 Installation and 


Permissions See the MKS Integrity Server 2009 Installation and 


Workflows and 

Documents 

Users See the MKS Integrity Server 2009 Installation and 


Groups See the MKS Integrity Server 2009 Installation and 


Dynamic Groups See the MKS Integrity Server 2009 Installation and 


Projects See “Projects View” on page 249. 

States See “Working in States View” on page 77. 

Types See “Working in Types View” on page 83. 

Fields See “Working in Fields View” on page 125. 

Document Model See “Setting Up Documents” on page 97. 

Triggers See “Managing Event Triggers” on page 362. 

Change Package Types See “Viewing Change Package Types” on page 325. 

Test Verdicts See “Setting the Test Management Role for Types” on 

page 112. 

Charts See “Using Type Properties” on page 245. 

Dashboards See “Admin Provided Objects” on page 242. 

Queries See “Admin Provided Objects” on page 242. 

Reports See “Admin Provided Objects” on page 242. 





Server Diagnostics See “Running MKS Integrity Server Diagnostics” on 

page 414. 

Introduction 

15


View Node Location 

Configuration 

Management 

16 

Display Pane 

The display pane presents the configurable information for a selected node tree view. For 

example, if you select Global in the Permissions view, the display pane presents information 

on the global permissions granted to principals (that is individual users or groups) on the 

system. 

For options with check boxes: 

Status Bar 

Policies See the MKS Integrity Server 2009 Installation and 






Server Diagnostics See “Running MKS Integrity Server Diagnostics” on 

page 414. 

Deploy Staging Systems See the MKS Deploy 2009 Administration Guide. 





Alert See “MKS Integrity Server Alert Messages” on page 32. 

Check Box Description 

Option is not enabled. 

Option is enabled. 

Prompted to confirm or specify the option. 

When you select a command, a brief explanation of its purpose and status displays in the 

status bar. In addition, when you point to a toolbar button, you can see an explanation of its 

function. 

The status bar also displays the progress and status for commands launched from the 

interface.

Workspace 

Introduction 

Everything between the toolbar and the status bar is considered the workspace. This is where 

the MKS Integrity Administration Client displays administration windows. 

ToolTips 

A tooltip displays as a popup and in the status bar to provide additional details when you 

pause the mouse pointer over an item. Tooltips are available by placing the pointer over a 

button or field. Point to a button to display a description of the task associated with that 

button. The information you enter in the Description field for various workflow and 

document objects is also displayed as a Tooltip to users. 

Quick Access Keys (GUI) 

By default, this guide describes how to perform steps using the mouse. For your convenience, 

there is an alternate way to perform many of those same steps using the keyboard. 

Access Keys (GUI) 

Keyboard access keys appear as underlined letters on a menu command, or as a dialog box 

option, allowing you to access most items on the interface. You use the access keys by 

pressing and holding the ALT key, then the key indicated by the underlined letter. 

Access keys can also be used in a sequence, for example, ALT, F, V, R. This sequence means 

press down and hold ALT, and then press F, V, and R. 

Shortcut Keys (GUI) 

For some commands, shortcut keys are provided, as well as access keys. Shortcuts appear on 

menus opposite their command names, for example: 

Pressing the INSERT key is the same as selecting the Create command. 

Pressing the F1 function key is the same as selecting the Help command. 

Common Dual List Actions 

The following actions are common to all dual lists in the GUI and Web interfaces: 

To move entries between lists, highlight the entry and click the add () 

buttons. 

To move all entries between lists, click the add all () buttons. 

To reorder the entries in a list, select an entry and click the move up (^) or move down 

(v) buttons. 

17


Filtering Data 

18 

As the amount of data in MKS Integrity increases, such as users, queries, projects, and fields, 

it can be difficult and time consuming to find the data you want. To quickly find data 

whenever a selection is required, such as assigning a user to a user field or selecting a chart to 

view, MKS Integrity provides a data filter for fields, lists, and views in the GUI interface. 

MKS Integrity provides a data filter for fields in the Web interface. 

Results List 

Selection 

List 

A typical data filter 

Text Filter Attribute Filters 

All instances of the data filter include a text filter that allows you to type a text string, 

becoming more specific as you type, for example, Show users containing james. 

In some instances, the data filter includes attribute filters that allow you to narrow your 

search results by searching for specific attributes, for example, users that belong to a specific 

group. 

Using the data filter is analogous to constructing a sentence that tells MKS Integrity what you 

are looking for, for example, Show projects containing patch that are active.

Introduction 

Filters and corresponding results persist each time you open and close the GUI or Web 

interface. For fields and lists, previously selected data (active and inactive) is bolded in the 

results list and displays in the selection list. For views, selected data (active and inactive) 

displays in the results list. 

Filtering Data in Field 

When setting the default value for a field, the data filter displays as a pop-up panel when you 

click the field. 

Data filter when setting a default field value 

19


20 

Filtering Data in List 

For lists, such as the Default Selected Projects list in the Create Admin Dashboard dialog box, 

the data filter displays as a pop-up panel when you click the plus sign (+) to add data to the 

list. 

Data filter for the Default Selected Projects list 

Filtering Data in View 

For views or selection dialog boxes, such as the Fields view, the data filter is embedded in the 

view or dialog box.

Data filter for the Fields view 

Filtering Text 

Introduction 

Typically, results are sorted alphabetically regardless of case, for example, all results 

starting with e and E are grouped together. Exceptions to the rule include data that has a 

sort order specified by your administrator, for example, states or pick list items. 

When using the text filter in a view, such as the Manage Queries view, the text filter 

searches visible columns only. For example, if you search for queries created by jriley 

in the Manage Queries view and the Created By column is hidden, no results are 

returned. 

The order that strings are typed in is irrelevant. For example, typing james riley or 

riley james both return James Riley. 

As soon as the data filter appears, typing immediately shifts the focus to the text filter 

and returns results. 

Favorites 

Workflow and document objects (queries, charts, reports, and dashboards) can be marked as 

favorites, allowing you to find them more easily in the data filter. You can search for favorites 

or non-favorites using the my favorites or not my favorites filters. For more 

information, see “Working With Favorites” on page 27. 

Active and Inactive Values 

By default, the data filter displays active and previously selected inactive values. Active 

values are users, groups, projects for workflows and documents, and pick list items that 

21


22 

are currently active in MKS Integrity. Inactive values represent obsolete values in 

MKS Integrity. 

If a multi-valued field contains one or more inactive values and you attempt to change 

any values in the field, you are prompted to leave the field unchanged or clear the field 

of all inactive values. 

Blank Values 

In rules and multi-value fields, you can choose an unspecified or blank value by 

selecting Unspecified from the results list. 

In single-value fields where a value is already selected, choose an unspecified or blank 

value by selecting the current value and clicking X. 

Users and Groups 

To choose your name for a user value, select your name or Me (the currently logged in 

user) from the results list. 

TIP Specifying Me can be useful in queries, charts, reports, and dashboards you 

intend to share with other users. For example, if you specify Me in a query that 

shows all Defects assigned to you, other users can use the same query to show their 

assigned Defects without modifying or copying the query. 

To choose MKS Integrity as a user value, select System from the results list. Specifying 

System is useful when you want to view or be notified about items that MKS Integrity 

has created or modified, such as computed fields. For example, if you create an e-mail 

notification rule to send an e-mail when an item containing a computed field is updated, 

MKS Integrity sends an e-mail each time the computed field is calculated. Depending on 

how often the field is calculated, this can result in several e-mails. If you do not want to 

receive e-mails about items that have changed only because MKS Integrity re-calculated 

a computed field, you set the rule to not send e-mails when the item is modified by 

System. 

Users or groups with a or icon are no longer active or no longer in the security 

realm. 

If your system is using LDAP authentication, all MKS Integrity user lists display full 

user names. If the attribute for full user names is missing on the LDAP server or if a 

user’s full name entry is blank, the MKS Integrity Client interface displays only the user 

ID. 

Typing a user’s full name or user name returns the same results, for example, James 

Riley and jriley. 

Workflow and Document Projects 

Child projects appear in the following format: parent project > child project.

Configuration Management Projects 

You can only filter top-level projects; however, you can select top-level projects and 

subprojects. 

E-mail Notification Rules 

Introduction 

In an e-mail notification rule, Me refers to the user that the notification rule is created for. This 

is useful if you want to create a common notification rule and share it with other users. 

Common Filters 

Some of the common filters are: 

Filter Description 

active Displays active users, groups, workflow and document projects, or 

pick list values. 

inactive Displays inactive users, groups, workflow and document projects, or 

pick list values. 

in group Displays users belonging to a specific group. 

my favorites Displays charts, dashboards, queries, or reports configured by you 

as favorites. 

not my favorites Displays charts, dashboards, queries, or reports configured by you 

as non-favorites. 

system provided Displays charts, dashboards, queries, or reports configured as 

shared administrative objects. 

created by me Displays charts, dashboards, queries, or reports created by you. 

created by... Displays charts, dashboards, queries, or reports created by a 

specific user. 

modified in the last week Displays charts, dashboards, queries, or reports modified in the last 

week. 

modified on Displays charts, dashboards, queries, or reports modified during a 

specific time period. 

visible in item type Displays fields visible in the specified item type. 

visible in all types Displays fields visible in all types. 

of field type Displays a specific field. 

23


24 

Shortcut Keys 

The following shortcut keys perform data filter operations: 

Shortcut Key(s) Operation 

ESC Close the data filter. 

ENTER Apply the selected data and close the data filter. 

Up arrow Move up in the results list. 

Down arrow Move down in the results list. 

CTRL+ Add the selected data to the results list. 

CTRL- Remove the selected data from the results list. 

F12 Replace the selected data in the selection list with the selected data 

in the results list. 

CTRL+A Select all data in the results list. 

To filter data 

1 To filter data using a text search, type a string in the Show containing text 

filter. Data containing the string displays in the results list, becoming more specific as 

you type. 

To filter data using attribute filters (if available) or to further restrict your text filter with 

attribute filters, click the that are filter and select an attribute filter from the list. 

To clear the that are filter, select that are > Reset. 

To remove a filter, select > Remove. For example, if the active users filter is 

enabled, select active > Remove.

Introduction 

To select multiple groups or to search for one or more groups using the text filter in the 

GUI, select that are > in group > Other. The Specify 'in group' filter values dialog box 

displays. 

Type a name in the text filter. A list of groups displays in the results list, becoming 

more specific as you type. 

From the results list, select the group(s) you want to add to the selection list and 

click +. 

To remove groups from the selection list, select the groups, and click X. 

To replace all groups in the selection list with groups that are selected in the results 

list, click . 

To add the group(s) in the selection list to the list of groups, click OK or Enter. 

To cancel the group selection and close the data filter, click Cancel. 

The group(s) display as an active attribute filter, for example, in group 

'Development'. 

To select multiple groups in the Web interface, select that are > in group >... . The 

Select Groups dialog box displays. 

Select multiple groups and click OK. The groups display as an active attribute filter, 

for example, in group Development,... . 

2 If you are filtering view or selection dialog box data, select the data in the results list, and 

perform an operation specific to the view or dialog box, such as Query > Edit or OK. 

If you are filtering list data, select the desired data in the results list, and click Add. 

If you are filtering field data, select the desired data in the results list, and click +. 

25


26 

NOTE 

If you are selecting data for a single-value field, selecting the data from the 

results list automatically adds the data to the selection list, closes the data filter, 

and adds the data as the field value. 

If the search returns one result in the results list, the data is automatically added 

to the selection list, requiring you to confirm the selection by clicking OK or Add. 

To remove selected data in the selection list, click X. 

3 To apply the data in the selection list as the field value(s), click OK or Add. If the field is 

multi-valued, click Add. The data displays as the field value(s). 

To cancel the selection and close the data filter, click Cancel. 

To select a configuration management project in the GUI 


Open the Projects view. 

Perform an operation that requires a project selection, and click Select. The Select a 

Project dialog box displays. 

The view or selection dialog box is similar to the following. 

To hide the My projects list, click , and to display a hidden My projects list, click . 

2 If you are selecting subprojects, click + to display the subprojects for a project and select 

the subproject(s) required. Proceed to step 5. 

3 If you are searching for top-level projects, type a project name in the Show projects 

containing text filter. A list of projects displays in the search results list, becoming more 

specific as you type.

TIP Because project names include the project path, you can type in directory names 

to browse through the project directory structure. If you enter multiple names, 

separate each name with a space, for example, qa scripts. 

Introduction 

4 From the results list, select the project(s) that you want to add to the My projects list. 

5 To add the selected projects(s) or subproject(s) to the My projects list, click +. 

To remove the selected projects(s) or subproject(s) from the My projects list, click X. To 

replace all projects or subprojects in the My projects list with projects or subprojects that 

are selected in the results list, click . 

NOTE If you are selecting a project for a single-value field, the project automatically 

displays in the My projects list and the +, X, and buttons are disabled. 

6 If you are selecting a project for a field, to add the project or subproject in the My projects 

list to the field, click OK. The project or subproject displays in the field. 

Working With Favorites 

To find workflow and document objects (queries, charts, reports, and dashboards) that you 

created and use, you configure these objects as favorites. In the relevant view, favorites 

display with the my favorites filter (for more information, see “Filtering Data” on page 18). 

In the GUI and Web interface, favorites are indicated by and non-favorite objects by . By 

default, all objects created by you are configured as favorites. 

Key Considerations 

Objects can be shared; however, favorite settings are specific to each user or group. 

To configure an object as a favorite, it does not have to be shared or a system provided 

object. 

A Quick Query is a non-configurable favorite. 

For queries, the concepts of favorites and non-favorites replace the concepts of hidden 

and shown that existed in previous releases. In the GUI, you can run favorite and nonfavorite 

queries because the data filter allows you to select both types. In the Web 

interface, you can only run favorite queries because the data filter is not available for 

selecting queries. If you attempt to run a non-favorite query, you are prompted to 

configure the selected query as a favorite. Clicking Yes configures the query as a favorite 

and runs it. 

In the CLI, creating an object is the only way to configure it as a favorite. In addition, 

favorites and non-favorites are not indicated. 

27


Display Patterns 

28 

To configure an object as a favorite or non-favorite 

1 From the Charts, Dashboards, Queries, or Reports view, select the object. 

2 Select Add To Favorites or Remove From Favorites from the Query, Report, Chart, or 

Dashboard menu. 

Display patterns allow you to assign a format to numeric values, for example, to a computed 

expression used in a chart. Display patterns quantify numeric values, for example, as 

currency or percentages. The MKS Integrity Client automatically detects your locale, 

displaying the relevant currency symbol in the Display Pattern list, in addition to other 

sample display patterns. 

A display pattern used in a computed expression that assigns a dollar amount to the field 

value. 


Display patterns appear only when viewing items, charts, or reports. For items, 

MKS Integrity stores the integer field as an unformatted numeric value in the database. 

Query filters, rules, and trigger assignments display the unformatted, localized version 

of the numeric field value. 

If the display pattern is invalid, an error message displays. If no display pattern is 

specified, the field displays the value in a localized form.

To specify a display pattern 

Introduction 

Select a display pattern from the Display Pattern list and modify it, or create one by 

combining a currency symbol, text that represents a measurement, and/or one or more of the 

following characters: 

Symbol Description 

0 Displays as a zero in the output. For example, a display pattern of 000.00 displays an 

input value of 12.14 as 012.14 in the numeric field. 

# Displays as a digit in the output. If the digit is a zero and it is leading or trailing the 

input value, it is left out of the value displayed in the numeric field. For example, a 

display pattern of #0.00 displays an input value of 0.126 as 0.13 in the numeric 

field. 

. Locale specific decimal separator. For example, a display pattern of #,###.00 

displays an input value of 12345.123 as 12,345.12 in the numeric field. 

- Minus sign. For example, a display pattern of -#### displays an input value of 1234 

as -1234 in the numeric field. 

, Locale specific grouping separator. For example, a display pattern of $#,### 

displays an input value of 12345.123 as $12,345 in the numeric field of a U.S. 

locale and $12.345 in the numeric field of a German locale. 

E Scientific notation. For example, a display pattern of 0.###E0 displays an input value 

of 123456 as 1.235E5 in the numeric field. 

; Separates positive and negative patterns. For example, a display pattern of 

#, ###;(#,###) displays an input value of -12345 as (12,345) in the numeric 

field. 

% Multiplies by 100 and displays as a percentage. For example, a display pattern of 

"#.# '%'" displays an input value of 0.06 as 6% in the numeric field. To display 60%, 

select a display pattern of #% and type an input value of .6. 

‘ Escapes special characters. Use '' to create a single quote. 

Server Connections 

The MKS Integrity Administration Client permits connections to multiple MKS Integrity 

Servers, allowing you to manage and configure multiple servers in the same session. 

29


30 

To connect to an MKS Integrity Server 

CLI EQUIVALENT integrity admingui 

1 Select File > Server Connection > Connect. The Specify Server Connection dialog box 

displays. 

NOTE If your preferences are not set to prompt a server connection, the Specify 

Server Connection dialog box does not appear. 

2 In the Host Name field, type the name of the MKS Integrity Server you want to connect 

to. 

3 In the Port Number field, type the port number. 

4 To accept the server information, click OK. The Enter Credentials dialog box displays. 

5 In the User Name field, type your user name. Your user name displays by default in the 

User Name field. 

6 In the Password field, type your password. 

7 To accept the user information, click OK. A connection with the server is established. 

NOTE Once you connect to another server, you can open a new window for 

configuring permissions, Workflows and Documents, and Configuration 

Management on that server. To open a new window, select Tools > Administration. 

Upon restarting the MKS Integrity Administration Client, view settings are 

automatically restored and you are prompted to connect to the server or servers 

used during the previous session. 

To verify your connection, select File > Server Connection. If you are connected, your 

user name, server name, and port number appear in the Server Connection menu. 

IMPORTANT In the Server Connection menu, the active connection displays with a 

bullet next to the connection information. If the bullet does not appear, you are not 

connected to the server. 

In the lower right corner of the MKS Integrity Administration Client, the following three 

icons indicate the status of the server: 

Icon Type of Server Connection 

Connected to the MKS Integrity Server. 

You are logged in and have an active client session.

Print Functions 

Icon Type of Server Connection 

To disconnect from an MKS Integrity Server 

CLI EQUIVALENT integrity disconnect 

1 Select File > Server Connection, and select the target server from the list. 

Introduction 

2 Select File > Server Connection > Disconnect. A dialog box notifies you that other client 

applications may be using this connection and asks you to confirm that you want close 

all connected views and disconnect your server connection. 

NOTE When you disconnect, all views for that connection close. New views either 

use the current connection or ask for credentials as defined in the preferences. 

3 To disconnect from the server, click Yes. The target server disconnects. 

The MKS Integrity Administration Client provides print functionality for details in some 

views. When working in views, if the view can be printed the print function is available by 

selecting File > Print from the menu or by clicking the print button ( ) on the toolbar. 

To print view information from the GUI 

1 Display the view you want to print. 

Disconnected from the MKS Integrity Server. 

You have logged out and closed your client session. 

Offline from the MKS Integrity Server. 

The connection to the MKS Integrity Server has been dropped or the 

network connection is down. 

TIP When printing view information, resize the window width to fit columns, and 

resize the column widths to fit cell contents. 

2 With the desired information displayed in the window, select File > Print. The Print 

dialog box displays. 

3 If necessary, select the required options under the General, Page Setup, and Appearance 

tabs. 

31


32 

TIP To fit more information on a page, change the paper orientation to landscape to 

accommodate larger window widths, decrease page margins to fit more information 

on a page, and, if your printer supports multiple page sizes, select a larger paper 

size. 

4 Click OK to print. The displayed information prints. 

NOTE Information from rows is not split across multiple printed pages. 

Each printed page contains a header that displays the user ID of the person printing the 

document, the window title, and the printing date. Each printed page is numbered in the 

footer. 

MKS Integrity Server Alert Messages 

From the MKS Integrity Administration Client, you can send alert messages to all users 

currently logged in to the MKS Integrity Server. Sending alert messages is useful for 

notifying users about important information, such as an impending server upgrade in which 

the server will be shut down. 


You need the mks:AdminServer permission to create and clear alert messages. For a 

proxy server, you need the mks:im:AdminProxy or mks:si:AdminProxy permission. 

You can create one message for a given server at a single time. Creating a new message 

deletes the previous message. 

Alert messages are stored in the server’s memory. If the server shuts down, the message 

is deleted. 

If a user connects to the server after a message is sent, the user still receives the message. 

Alert messages are plain text only and allow a maximum 4000 KB. 

In the Web interface, the date displayed for an alert message is the server’s date, time, 

and time zone. In the GUI and CLI, the date displayed for an alert message is the client’s 

date, time, and time zone. 

To create an alert message in the GUI 

CLI EQUIVALENT integrity setserveralert 

1 From the tree pane, select the Alert node. The Server Alert pane displays.

Introduction 

2 To set the alert message, select Alert > Set. The Set Alert to Broadcast dialog box appears, 

displaying who the alert is from (the currently logged in user) and which server the alert 

is sent to (the currently connected server). 

3 In the text field, type the message you want to send. 

4 To send the alert, click OK. The alert is sent. 

To view an alert message in the GUI 

CLI EQUIVALENT im/si/aa viewserveralert, im/si/aa 

serveralerts 

If you are working in the MKS Integrity Client with the MKS system tray or Web interface for 

workflows and documents, alert messages appear in a window at the bottom of the interface. 

NOTE In the MKS Integrity Client with system tray, you can view alert messages for 

all of the servers you are currently connected to by right-clicking the system tray 

icon and selecting Server Alerts. 

The alert message displays who sent the message, the server it came from, when it was sent, 

and the message. Alert messages are plain text only and do not support rich content. If there 

is more than one message, the top of the alert message window indicates message # of #, with 

"previous" and "next" arrow buttons that cycle through the messages. To close the alert 

message window, click X or the Esc key. 

Users working in the CLI, Web interface for configuration management, and MKS Integrity 

Client without the MKS system tray must manually check for alert messages from the CLI. 

For more information, see the MKS Integrity 2009 CLI Reference Guide for Workflows and 

Documents, MKS Integrity 2009 CLI Reference Guide for Configuration Management, or 

MKS Integrity Server 2009 Administration CLI Reference Guide. 

TIP To avoid manually checking alert messages from the command line, launch the 

alert messages dialog box from the command line by specifying -g or --gui and 

keep the dialog box open. The dialog box automatically refreshes to display new 

alert messages. 

33


Preferences 

34 

To clear an alert message in the GUI 

CLI EQUIVALENT integrity setserveralert 

1 From the tree pane, select the Alert node. The Server Alert pane appears, displaying the 

current alert message. 

2 Select Alert > Clear. The alert message is removed from the Server Alert pane. 

NOTE If no alert message exists, the Clear command is unavailable. 

The MKS Integrity Client contains a common Preferences Configuration window that 

displays in the MKS Integrity Administration Client and MKS Integrity Client. The 

Preferences Configuration window allows you to configure preferences for each component 

installed on your local machine. 

Options that appear in bold are those set by you. You can reset the default settings by clicking 

the Clear Local Settings button (available only on the applicable panels). 

Select a component to configure: 

NOTE Regardless of which component(s) you installed, preferences for all 

components appear in the Preferences Configuration window. 

To configure MKS Integrity Client preferences, see “MKS Integrity Client Preferences” 

on page 35. 

To configure server preferences, see “Server Preferences” on page 37. 

To configure MKS Integrity Administration Client preferences, see “MKS Integrity 

Administration Client Preferences” on page 38.

Preferences 

To configure workflow and document preferences, refer to the MKS Integrity 2009 User 

Guide. 

To configure Deploy preferences, refer to the MKS Deploy 2009 Administration Guide. 

To configure workflow and document preferences, refer to the MKS Integrity 2009 User 


To configure Authorization Administration preferences, see “Authorization 

Administration Preferences” on page 41. 

Option Prompts 

If a command is configured to prompt you to confirm or specify an option, the confirmation 

dialog box that displays when you run the command allows you to save your response so 

that you are not prompted again. If necessary, the option can be modified again from the 

command’s main dialog box, wizard, or command options in the Preferences dialog box. 

MKS Integrity Client Preferences 

You can set the following preferences for the MKS Integrity Client, which are applied to each 

component you installed: 

look and feel of the GUI 

time delay for pop-up windows 

memory heap size 

commands 

To set MKS Integrity Client preferences from the GUI 

CLI EQUIVALENT integrity setprefs 

1 Select Tools > Preferences. The Preferences Configuration window displays. 

2 In the tree pane, under Integrity Client, select the General node. The General pane 

displays. 

To set the appearance of the GUI, select an option from the Look and Feel list. The 

available choices are System, Windows (available for windows clients only), Motif, 

and Metal. 

To set the time in milliseconds before a command’s status displays in the GUI, type 

a numeric value in the GUI field under Popup Status Delay, or use the up and down 

arrows to select a value. The default value is 2500. 

35


36 

To set the time in milliseconds that a command’s status displays in the CLI, type a 

numeric value in the CLI field under Popup Status Delay, or use the up and down 

arrows to select a value. The default value is 0. 

To close and shut down the MKS Integrity Client when using the Close Window 

command or clicking the X at the top right-hand corner of the MKS Integrity Client 

window, enable the option for Exit on Close. This option is disabled by default. 

To set the maximum amount of memory reserved for the MKS Integrity Client at 

run time, under Miscellaneous in the Maximum heap size field, enter a value in 

megabytes, or use the up and down arrows to select a value. The minimum value is 

5 MB, and the maximum value depends on your available system memory. The 

default value is 96 MB. 

CAUTION Changing the heap size setting may unfavorably affect the performance of 

the MKS Integrity Client and your system. Consult your administrator before 

making changes. 

On Windows, you can enable or disable an MKS Integrity Client system tray icon 

that indicates the MKS Integrity Client is running by toggling the Enable System 

Tray Icon option. When enabled, you can also perform some basic MKS Integrity 

Client commands by right clicking the MKS Integrity Client icon. The MKS Integrity 

Client system tray icon is enabled by default. 

3 To save your preferences, click OK. 

NOTE You must restart the MKS Integrity Client for the new preferences to take 

effect. 

To set MKS Integrity Client command preferences from the GUI 



2 In the tree pane, under Integrity Client, open the Commands folder and select a node: 

Disconnect From Server causes the MKS Integrity Client to confirm when you 

disconnect from the MKS Integrity Server. To enable this option, select Confirm 

Disconnect. 

Exit causes the MKS Integrity Client to confirm that all open MKS Integrity Client 

components (configuration management, workflow and document management, 

MKS Integrity Administration Client, and Authorization Administration) close and 

shut down. 

3 To save your preferences, click OK.

Server Preferences 

Preferences 

To address the needs of geographically dispersed organizations, the MKS Integrity Federated 

Server architecture (FSA) serves configuration management client requests through a 

proxy. The proxy provides access to project members residing on the MKS Integrity Server 

by retrieving information from its local cache or, if changes are detected, directly from the 

server. 

The Proxies node in the Servers folder allows you to configure proxy preferences. 

For a detailed discussion about using a proxy, see the MKS Integrity Server 2009 Installation 

and Configuration Guide. 

To set proxy preferences from the GUI 



2 In the tree pane under Integrity Client, open the Servers folder, and select the Proxies 

node. The Proxies pane displays. 

3 Configure the available options: 

NOTE The names direct and default in any case, or combination of cases, cannot 

be used as proxy host names. 

Spaces and commas are invalid characters in the Host Name field. 

Host names and port numbers must match to connect to a proxy successfully. If you 

provide an incorrect port number, MKS Integrity does not search for the correct one. 

a) Select Use same username and password for proxy and server if you want the same 

user name and password to be used when connecting to both the proxy and server. 

Selecting this option does not necessarily ensure that MKS Integrity prompts you 

only once for your user name and password. If the authentication schemes used do 

not match, MKS Integrity prompts you for your user name and password again. 

b) Select Always confirm proxy username and password if you want MKS Integrity to 

prompt you for the user name and password each time you connect to the proxy. 

c) Select Reuse current proxy username and password for all connections if you want 

to use the same proxy user name and password when connecting to multiple remote 

servers. 

d) Select Use default proxy for all unlisted connections if you want to specify the proxy 

server as the default server for unlisted connections. This option is only enabled 

when you complete the details for a default proxy described next. 

e) To specify a default proxy, under Default proxy complete the following: 

37


38 

In the Host Name field, type the name of the server, or the numerical IP address. 

In the Port field, type the port number. If you do not specify a port number, or 

use 0 as the port number, MKS Integrity assumes a direct connection. 

f) To configure multiple servers to connect to, under Server do the following: 

Click Add to display the Add new server connection dialog box. 

In the Host Name field type the name of the server or the numerical IP address. 

In the Port field, type the port number. 

g) Select the type of connection you want. 

Direct connection specifies connecting without a proxy. 

Use default proxy specifies connecting using the proxy specified as the default 

on the Proxy panel. 

To specify a different proxy, select Proxy and complete the Host Name and Port 

fields. 

h) Click OK to save the server details and return to the Proxy panel. The server displays 

in the Server list with the connection details that you selected displayed below it. 

You can review the server details for each server you configure by selecting it from 

the list. 

TIP To edit a previously configured server, select it from the Server list, and click Edit. 

Edit the server details as required, and click OK to save your changes. 

To delete a previously configured server, select it from the Server list, and click 

Delete. The server name is removed from the Server list. 


MKS Integrity Administration Client Preferences 

You can set the following preferences for the MKS Integrity Administration Client: 

restore desktop 

main toolbar 

server connection 

To set MKS Integrity Administration Client desktop preferences from the GUI 


1 Select Tools > Preferences. The Preferences Configuration window displays.

2 In the tree pane, select the Desktop node. The Desktop pane displays. 

Preferences 

3 To restore all active windows when you restart the MKS Integrity Administration Client, 

select the Restore Desktop option. 

IMPORTANT To activate the Restore Desktop option, you must restart the 

MKS Integrity Administration Client. 

The Restore Desktop option remembers which windows were open when you last exited 

the MKS Integrity Administration Client. When you restart the MKS Integrity 

Administration Client, the active windows appear automatically in the main view. 

Restore Desktop remembers up to ten windows. 


To set MKS Integrity Administration Client toolbar preferences from the GUI 


2 In the tree pane, select the Desktop node. The Desktop pane displays. 

3 Click Toolbar. The Configure toolbar for: Desktop View dialog box displays. 

4 Do the following if you want to customize the main toolbar: 

a) To add a button to the main toolbar: 

Under Available Buttons, select the desired button. 

Under Toolbar Contents, select the button you want the new button to appear 

beside. 

Click Add. The target button moves to the list of Toolbar Contents and displays 

on the main toolbar. 

b) To remove a button from the main toolbar: 

Under Toolbar Contents, select the target button. 

Click Remove. The target button moves to the list of Available Buttons and no 

longer displays on the main toolbar. 

c) To add a separator: 

Under Toolbar Contents, select the button you want the separator to appear 

beside. 

Under Available Buttons, select a separator. 

Click Add. A separator is added at the specified location under Toolbar 

Contents. 

On the main toolbar, the separator is positioned to the right of the existing button or 

separator. You can remove the separator the same way as removing a button. 

39


40 

d) To change the sequence of a button or separator: 

Remove it from the Available Buttons list. 

Add it to the desired location. 

5 To accept the changes, click OK. The Configure toolbar for: Desktop View dialog box 

closes. 

6 To save your preferences, click OK. Your changes display immediately on the main 

toolbar. 

To set MKS Integrity Administration Client connection preferences from the GUI 



2 In the tree pane, select the Connection node. The Connection pane displays. 

3 Configure the following options: 

a) Under Default Server Connection, specify the following options: 

To specify a default MKS Integrity Server to connect to, in the Host Name field 

type the name of the server or the numerical IP address. 


To be prompted for the MKS Integrity Server name and port number each time 

you log in to the MKS Integrity Administration Client, select the Prompt for 

Host Name and Port option. 

b) Under User, specify the following options: 

In the User Name field, type the user name you want to set as the default user. 

In the Password field, type a password for the user. 

To be prompted for the default user name each time you log in to the 

MKS Integrity Administration Client, select the Prompt for: User Name option. 

To be prompted for the password each time you log in to the MKS Integrity 

Administration Client, select the Prompt for: Password option. 

NOTE If the security realm at your site is Windows Single Sign-On (NTSS), the 

Prompt for: User Name and Prompt for: Password options are ignored, unless you 

specify a user name that is different than the logged in user name. For information 

on security realms, see the MKS Integrity Server 2009 Installation and Configuration 


4 To save your preferences, click OK.

Setting MKS Integrity View Preferences 

Preferences 

You can also modify MKS Integrity views by setting preferences through the MKS Integrity 

Client. 

To set view preferences in the MKS Integrity Client 


1 Open the MKS Integrity Client, and select Tools > Preferences. The Preferences 

Configuration panel displays. 

2 Expand the Views directory for a component, and choose the view you want to 

configure. 

3 Configure the options as required. For detailed information on Authorization 

Administration options, see “Authorization Administration Preferences” on page 41. For 

detailed information on other options, see the MKS Integrity Client 2009 Getting Started 



Authorization Administration Preferences 

For Authorization Administration, you can configure the default settings for connecting to 

the MKS Integrity Server. 

To configure Authorization Administration preferences from the GUI 



2 In the tree pane under Authorization Administration, select the Connection node. The 

Connection pane displays. 

3 Configure the following options: 

a) Under Default Server Connection, specify the following options: 

To specify a default MKS Integrity Server to connect to, in the Host Name field 

type the name of the server or the numerical IP address. 


To be prompted for the default MKS Integrity Server name and port number 

each time you log in to Authorization Administration, select the Prompt for 

Host Name and Port option. 

41


Deploy Preferences 

42 

b) Under User, specify the following options: 

In the User Name field, type the user name you want to set as the default user. 

In the Password field, type a password for the user. 

To be prompted for the default user name each time you log in to Authorization 

Administration, select the Prompt for: User Name option. 

To be prompted for the default password each time you log in to Authorization 

Administration, select the Prompt for: Password option. 

NOTE If the security scheme at your site is Windows Single Sign-On (NTSS), the 

Prompt for: User Name and Prompt for: Password options are ignored unless you 

specify a user name that is different than the logged in user name. For information 

on security schemes, see the MKS Integrity Server 2009 Installation and Configuration 



To use features set in the Deploy preferences, you must be licensed for Deploy. For more 

information, see the MKS Deploy 2009 Administration Guide. 

Administration Command Line Interface 

The CLI is a program that allows a user to enter keywords as instructions to a computer or 

device to perform specific tasks. (The MS-DOS® command prompt is an example of a CLI.) 

Results are typically output as simple text to the user’s terminal. More specifically, the CLI 

provides the means for you to enter MKS commands through a text-based interface. The 

primary use of the CLI is for scripting. The CLI is also useful for environments where no GUI 

is available. 

In addition to the functionality provided through the GUI for the MKS Integrity 

Administration Client, you can also perform certain tasks through the CLI. 

For a complete description of the commands and their options, see the MKS Integrity Server 

2009 Administration CLI Reference Guide.

Defining Rules 

Rule Format 


As administrator, you construct and manage rules that govern how items move through your 

development cycle. The logic that governs these rules is defined in a number of places within 

MKS Integrity: 

user notification rules 

group notification rules 

field editability and relevance 

rule-based event triggers 

rule-based field relationships. 

NOTE For information on defining rules for rule-based field relationships, see “To 

create a rule-based field relationship in the GUI” on page 148. 

A rule is a statement that sets a specified outcome when certain conditions are met. In the 

GUI, rules are composed of nodes and conditions. Nodes are the logical connectors that 

describe the relationship between two statements (or conditions). Conditions are a statement 

of the requirements that must be satisfied, and can involve either user or field values. 

The logical and node indicates that all of the specified conditions must be true to meet the 

requirements of the rule. 

The logical or node indicates that one or more of the specified conditions must be true to 

meet the requirements of the rule. 

The specific placement of the logical node is important to determining how it affects the 

meaning of the rule. 

Example 

The following example shows an e-mail notification rule that asks MKS Integrity to notify the 

user (administrator) each time a new change request is created or whenever a defect is 

assigned to the user. With the or node, the notification occurs whenever either of the events 

occurs. 

43


44 

The use of [New Value] in a rule condition indicates a change in a field value. One part of 

the condition indicates the field value before the change, and the other part indicates the 

value after the change. For example, in the rule above, Assigned User Assigned 

User[New Value] indicates that the new value of the Assigned User field is not equal to 

what it was before the item was saved. In other words, the value of the Assigned User field 

was changed during the item edit. 

Working With Conditions 

When working with conditions, the meaning of the operator depends on whether the field 

you are using in the rule is single or multi valued. 

Operator Description 

= Equals (single-valued fields) 

Contains (multi-valued fields) 

Valid Operators 

Does not equal (single-valued fields) 

Does not contain (multi-valued fields) 

> Greater than (single-valued fields) 

Contains at least one element greater than (multi-valued fields) 

>= Greater than or equal (single-valued fields) 

Contains at least one element greater than or equal to (multi-valued fields) 

< Less than (single-valued fields) 

Contains at least one element less than (multi-valued fields) 

To create a condition involving field values 

NOTE For information on creating conditions for rule-based field relationships, see 

“To create a rule-based field relationship in the GUI” on page 148. 

1 Open the dialog box or panel where you are defining the rule. 


2 Select And or Or, depending on the type of logical connector you want to use between 

conditions. 

NOTE If you are creating a rule with only one condition, you do not need to select 

And or Or. 

Swap replaces the selected node with the opposite node. For example, swapping an Or 

node replaces it with an And node. 

Remove deletes the selected node. 

3 Under Condition, select one of the following: 

Compare the value of a field with a constant 

Compare the value of a field with the value of another field 

4 Select the operator from the list. 

5 Specify fields and field values for the condition. 

NOTE You cannot specify MKS Integrity project and attachment fields in conditions. 

a) To choose a value for a date field, click Change. The Specify Date or Time dialog box 

displays. 

b) Do one of the following: 

Select a date from the calendar. If the date field is configured to display the time 

and you want to include it, select the Show time option (if not already enabled) 

and include a time from the calendar. The Show time option is enabled by 

default. 

Select now to specify the current date and time. This option displays only if the 

date field is configured to display the date and time. 

Select today to specify the current date and a time of 00:00:00 (midnight). This 

option can be specified for a date field or a date field configured to display the 

date and time. 

Select none to specify an empty value for the date field. 

6 For each field, specify an Existing Value or a New Value. 

45


46 

7 When you are finished constructing the condition, click Add. The condition displays 

under the selected node. 

NOTE You cannot specify configuration management project and attachment fields 

in conditions. 

For more information on operators, see “Valid Operators” on page 44. 

For more information on using the data filter to select fields, see “Filtering Data” on page 18. 

To create a condition involving user groups 

8 Under Condition, select Check the group membership of the user performing 

the action. 

9 Select is or is not from the list. 

10 Select a group name from the a member of list. For detailed information on using the 

data filter, see “Filtering Data” on page 18. 



To create a condition involving type properties 

NOTE This condition is commonly defined to view solution-specific item types. It 

can also be used in rules (except query rules) and expanded in report templates. To 

learn more about solution options and licensing, refer to the applicable solution 

guide. 

1 Under Condition, select Check a property associated with the item's type. 

2 Select a type property name from the filtered list. For information on using the data 

filter, see “Filtering Data” on page 18. 

3 Select the operator from the list (see “Valid Operators” on page 44). 

4 Enter a value for the property in the subsequent field. 



To create a pre-condition associated with a document 

1 Under Condition, select Check a pre-condition associated with a document. 

2 Select an item type from the filtered list of document item types. 

For information on using the data filter, see “Filtering Data” on page 17.

Selecting Rules 

Viewing Administration History 

3 When you are finished constructing the condition, click Add. The document model 

condition displays in the text box. 

To learn about the various document item types and artifact classification, for example, 

defining types as meaningful and non-meaningful, see “Setting Up Documents” on 

page 97. 

There is a full set of use cases associated with the creation of pre-conditions, rules, and 

triggers available in the ALM section of the MKS Customer Community Knowledge 

Base found at http://www.mks.com/community. 

To replace an existing condition with a new one 

1 Select the existing condition. 

2 Construct the condition as described earlier. 

3 Click Replace. A confirmation dialog box displays. 

4 To confirm the replacement, click Yes. 

When working with rules, you can copy them from other existing items, such as users, 

groups, fields, or triggers. 

The Rule Selection dialog box allows you to select an item to copy an existing rule from. 

To select a rule in the GUI 

NOTE The Rule Selection dialog box for Users and Groups includes options that 

change the item type that rules are copied for. This allows you to copy group rules 

to a user or copy user rules to a group. 

1 In the Objects with Rules list of the Rule Selection dialog box, select the item you want to 

copy conditions from. If the user has conditions, that user displays in the Preview area. 

2 Click OK. The rule displays in the panel. 

3 Repeat as necessary to add more rules. 

Viewing Administration History 

Setting up workflows and documents involves modifying a number of administrative objects 

to customize the configuration to suit your work environment. Workflow and document 

administrative objects are users, groups, dynamic groups, projects, states, types, fields, 

triggers, change package types, and change package attributes. Whenever changes are made 

47


48 

to these objects, MKS Integrity tracks the changes and then provides reports on the change 

history through the MKS Integrity Administration Client. 

Using the MKS Integrity Administration Client, you can view the record of changes through 

the History tab in the associated view for each administrative object. The administrative 

history displays when you are editing or viewing an administrative objects. 

You can also access information in the history through the CLI. To view the history, use the 

--showHistory option when viewing or editing administrative objects. By default, the view 

and edit commands do not display any history information. For more information on the 

CLI, see the MKS Integrity Server 2009 Administration CLI Reference Guide. 

In the MKS Integrity Administration Client, the History tab displays the changes in 

chronological order from the first to the most recent and lists the complete record of changes 

for that object. The record of changes is also stored in the MKS Integrity database. 

NOTE If you are upgrading from an earlier release, the history of changes is not 

shown from the previous installation. 

Information displayed under the History tab includes: 

user who made the change and the associated date/time information 

property of the object that was modified (for example, State object properties include 

name, description, image, capabilities, and the history of position or sequence changes) 

type of change that was made (one of Changed To, Added, or Removed) 

value associated with the modification 

NOTE Whenever a user is automatically created during logon, system is shown as 

the creator of that user.

C HAPTER THREE 

ViewSets 

Administering ViewSets for Users 

3 

This chapter provides information on administering ViewSets for the purpose of making 

them available to users from the MKS Integrity Server. 

For information on how users make use of ViewSets in the MKS Integrity Client, see the 

MKS Integrity Client 2009 Getting Started Guide. 


“Understanding ViewSets” on page 50 

“Viewing ViewSets” on page 51 

“Basic ViewSet Operations” on page 54 

“Making ViewSets Available to Users” on page 56 

“Administering Published ViewSets” on page 62 

“ViewSet Permissions” on page 66 

“ViewSets FAQ” on page 67 

49

Chapter 3: ViewSets 


50 

The following table summarizes the steps you should follow to set up MKS Integrity 

ViewSets:. 


Learn about what ViewSets are, and why they 

are used by users. 

Learn how to use the ViewSets view, types of 

ViewSets, and default samples. 

Perform basic ViewSet operations, such as 

creating, editing, copying, and deleting. 

Publish ViewSets to the MKS Integrity Server so 

that they are available to users. 

Manage and configure properties for ViewSets 

residing on the MKS Integrity Server. 

Specify permissions for modifying, publishing, 

and importing ViewSets. 

Troubleshoot problems you are encountering 

with administering ViewSets. 

Understanding ViewSets 

“Understanding ViewSets” on page 50 

“Viewing ViewSets” on page 51 

“Basic ViewSet Operations” on page 54 

“Making ViewSets Available to Users” on 

page 56 

“Administering Published ViewSets” on page 62 

“ViewSet Permissions” on page 66 

“ViewSets FAQ” on page 67 

A ViewSet is a collection of views in a specific configuration that persists each time the user 

opens and closes the MKS Integrity Client. As an administrator, you have the ability to 

control the configuration of ViewSets. Each ViewSet can be designed around one or more 

tasks, often corresponding to a specific role, such as a developer or project manager. For 

example, a developer ViewSet might contain views and actions for items and queries, while a 

project manager ViewSet might contain views and actions for charts, reports, and 

dashboards. 

It is the ability to specify not just open views, but available menu items (and toolbar buttons) 

that launch views, that gives the ViewSet its effectiveness with users. As an administrator for 

the ViewSet, you can even limit the level of customization that users are able to perform and 

what they see as available to customize. 

Depending on your work environment, one of your responsibilities as an administrator may 

be creating ViewSets for specific roles in your organization. Once you create a ViewSet, you 

can make it available to other users by publishing it on the MKS Integrity Server (see 

“Publishing ViewSets” on page 59). Users can then import the ViewSet using the 

MKS Integrity Client. Users cannot import ViewSets that reside on other MKS Integrity

Viewing ViewSets 

Clients. In addition, you can create mandatory ViewSets that are automatically imported into 

each user’s MKS Integrity Client when it connects to the MKS Integrity Server (see 

“Mandatory ViewSets” on page 61). 

MKS Integrity saves published ViewSet files in XML format in the database. 

MKS recommends creating and editing ViewSets in the GUI; however, you can retrieve 

published ViewSets from the database for manual editing. Once you are finished editing 

these files, you can store them in the database. 

As an alternative to using the Admin Migration Wizard, you could also retrieve a published 

ViewSet from a server, modify it, and place it in another server’s database for use. 

To retrieve published ViewSets from the database, use the integrity/im getdbfile 

command. 

To put published ViewSets in the database, use the integrity/im putdbfile command. 

NOTE The integrity putdbfile and getdbfile commands require the 

mks:AdminServer permission. The im putdbfile and getdbfile commands 

require the mks:im:AdminServer permission. 

For more information on using these commands, see the MKS Integrity Server 2009 

Administration CLI Reference Guide. 

You can also specify which users and groups are permitted to import, edit, and publish 

specific ViewSets (see “ViewSet Permissions” on page 66). 

For troubleshooting problems associated with ViewSets, see “ViewSets FAQ” on page 67. 


The ViewSets view is the primary location for administering ViewSets. While you can 

perform modifications to some ViewSets from the MKS Integrity Client, the ViewSets view 

provides complete administrative functionality. 

NOTE To see the ViewSets view, you need the PublishNewViewSet permission or 

permission to modify any server (published) ViewSet. See “ViewSet Permissions” 

on page 66. 

To open the ViewSets view from the MKS Integrity Administration Client, select the ViewSet 

Distribution > ViewSets node. The ViewSets view displays. 

51


52 

The ViewSets view displays the following information by default: 

Name Description 

Published State Displays what type of ViewSet it is, and consequently where the 

ViewSet is located (see “ViewSet Types and Locations” on 

page 52). The type of the ViewSet determines what operations 

you can perform on it. 

Name Displays the name of the ViewSet. The system is able to work 

with different ViewSets using the same name. 

Creator Displays the name of the user who published the ViewSet. 

Modified Date The meaning of modified date varies based the type of ViewSet: 

ViewSet Types and Locations 

Personal ViewSets, is the modified date of the ViewSet on 

the server at the time it was installed on the MKS Integrity 

Client. 

Unpublished ViewSets, is the date the ViewSet was last 

edited. 

Published ViewSets, is the date the ViewSet was either 

published, or its properties edited on the server. 

Description Displays a description of the ViewSet, if one was provided for it. 

To provide a description for a ViewSet, see “Editing ViewSets” 

on page 54 or “Editing ViewSet Attributes” on page 63. 

Mandatory Specifies if the ViewSet is mandatory for users who have 

permission to import it (see “Mandatory ViewSets” on page 61). 

This field only applies to published ViewSets (see 

“Administering Published ViewSets” on page 62). 

Customizable Specifies if the ViewSet can be customized by users. Note: If a 

ViewSet is mandatory, it cannot be set to customizable. 

To administer ViewSets, it is important to understand the types of ViewSets and where they 

are located. 

There are three types of ViewSet: personal, unpublished, and published. A ViewSet changes 

type based on the operation performed in the ViewSets view (see “Viewing ViewSets” on 

page 51). The following table describes each type of ViewSet: 

Type Location Description 

Personal MKS Integrity Client ViewSets stored on (and available to) the 

MKS Integrity Client installed on the same 

machine a MKS Integrity Administration 

Client you are viewing the ViewSets view 

from. 

Personal ViewSets are only displayed in the 

ViewSets view for the purpose of converting 

to unpublished ViewSets.

Type Location Description 

Unpublished MKS Integrity 

Administration Client 

Default ViewSets 


By default, the MKS Integrity Server includes the following role-based ViewSets that may be 

useful in your organization: 

Configuration Manager 

ViewSet for performing advanced software configuration functions. This ViewSet 

includes views and actions for projects, Sandboxes, members, change packages, items, 

queries, and time entries. 

Release Manager 

ViewSet for managing deployment. This ViewSet includes views and actions for change 

packages, items, queries, and staging and deploy. 

Deploy Administrator 

ViewSet for staging and deploy administrators. This ViewSet includes views and actions 

for projects, and for staging and deploy. 

Developer 

ViewSet for software developers. This ViewSet includes views and actions for projects, 

Sandboxes, members, change packages, items, queries, and time entries. 

Integrity User 

ViewSets modified through the MKS Integrity 

Client for the purpose of publishing to the 

MKS Integrity Server. These ViewSets have 

not yet been published (or have not been 

published since they were last fetched or 

edited). 

Created when a personal ViewSet is edited or 

copied from the ViewSets view. Also created 

when a published ViewSet is edited, copied, 

or fetched. 

Important: Unpublished ViewSets are stored 

locally on your MKS Integrity Administration 

Client machine. Until the ViewSets are 

published to the MKS Integrity Server, like 

any other locally stored data they are subject 

to local system failure. 

Published MKS Integrity Server ViewSets that have already been published to 

the MKS Integrity Server, and are available to 

specified users (see “Administering Published 

ViewSets” on page 62). 

ViewSet for creating, updating, and monitoring items. This ViewSet includes views and 

actions for change packages, items, queries, charts, reports, and dashboards. 

53


54 

IBM i Developer 

ViewSet for reviewing System i source changes. This ViewSet includes views and limited 

actions for projects, members, change packages, items, and queries. For more 

information on working with Implementer and source management, see the 

MKS Implementer 2009 User Guide. 

Basic ViewSet Operations 

This section covers basic operations that you can perform on ViewSets: 

“Creating ViewSets” on page 54 

“Editing ViewSets” on page 54 

“Copying ViewSets” on page 55 

“Deleting ViewSets” on page 56 

Creating ViewSets 

Creating a ViewSet from the MKS Integrity Administration Client saves you the step of 

converting a personal ViewSet (created from the MKS Integrity Client) to an unpublished 

ViewSet. 

Editing ViewSets 

To create a ViewSet using the MKS Integrity Administration Client interface 

1 From the ViewSets view (see “Viewing ViewSets” on page 51), select ViewSet > Create. 

The Create ViewSet dialog box displays. 

2 In the Name field, type a name for the ViewSet. A name is mandatory, but ViewSet 

names do not need to be unique. MKS Integrity tracks the ViewSet independently of the 

name you assign it. 

3 To create the ViewSet, click OK. The ViewSet displays in the ViewSets view. 

The created ViewSet is empty. To configure it with menus, views, and toolbars, edit the 

ViewSet (see “Editing ViewSets” on page 54). The Edit ViewSet GUI is automatically 

launched so you can customize the ViewSet (see “Editing ViewSets” on page 54). 

Editing a personal or published (server) ViewSet from the ViewSets view creates a local 

duplicate and converts it to an unpublished ViewSet. That means that if you edit a published

Basic ViewSet Operations 

ViewSet, a local duplicate is created to be edited as an unpublished ViewSet. That 

unpublished ViewSet must then be published to replace the original one you edited. 

IMPORTANT Unpublished ViewSets are stored locally on your MKS Integrity 

Administration Client machine. Until the ViewSets are published to the 

MKS Integrity Server, like any other locally stored data they are subject to local 

system failure. 

To edit a ViewSet using the MKS Integrity Administration Client 

Copying ViewSets 

1 From the ViewSets view (see “Viewing ViewSets” on page 51) select the ViewSet you 

want to edit. Then select ViewSet > Edit. The Edit ViewSet GUI displays. 

The Edit ViewSet GUI provides you with a way to see and interact with ViewSet 

elements to ensure that they appear and behave the way you intended. The Edit ViewSet 

GUI saves changes you make to the layout of the tabbed views. For more information on 

using the Edit ViewSet GUI, see the documentation for Test ViewSet GUI (see “Testing 


NOTE If you fetch or delete a ViewSet while it is open in the Edit ViewSet GUI, the 

EditViewSet GUI closes and your changes are lost. 

2 To specify what elements are included in the ViewSet, select ViewSet > Customize. The 

Customize ViewSet dialog box displays. For information on customizing a ViewSet, see 

the MKS Integrity Client 2009 Getting Started Guide. 

IMPORTANT The customizing ViewSet documentation in the MKS Integrity Client 

2009 Getting Started Guide specifies which functionality is only available through the 


You can copy existing ViewSets to reuse them for new ViewSets you want to create. You can 

also create copies of ViewSets as backups, to restore later if you choose to discard changes 

you make to a ViewSet. 

To copy a ViewSet using the MKS Integrity Administration Client 

1 From the ViewSets view (see “Viewing ViewSets” on page 51), select the ViewSet you 

want to copy. 

2 Select ViewSet > Copy ViewSet. The Copy dialog box displays, where 

is the name of the ViewSet you are copying. 

55


Deleting ViewSets 

56 

3 In the Name field, enter a name for the ViewSet copy. The default name is Copy of 

. 

To copy the views currently open in the selected ViewSet, enable Copy Open Views. 

4 To create the copy, click OK. The new ViewSet copy is created and displays in the 

ViewSets view as an unpublished ViewSet. The Edit ViewSet GUI is automatically 

launched so you can customize the ViewSet (see “Editing ViewSets” on page 54). 

You can delete ViewSets that are no longer needed. Published and unpublished ViewSets can 

each be deleted using the ViewSets view. 

NOTE Personal ViewSets cannot be deleted using the ViewSets view. 

To delete a ViewSet using the MKS Integrity Administration Client 

1 From the ViewSets view (see “Viewing ViewSets” on page 51), select the ViewSets you 

want to delete. 

2 Select ViewSet > Delete. The Delete ViewSet confirmation dialog box displays. 

CAUTION You cannot recover a ViewSet once it is deleted. 

3 To confirm deletion, click Yes. The ViewSet is deleted and no longer appears in the 

ViewSets view. 

NOTE Clicking Yes to All only deletes all ViewSets of that particular type. 

Making ViewSets Available to Users 

There are default ViewSets included on the MKS Integrity Server for users to download 

(“Default ViewSets” on page 53). However, you can customize those ViewSets (or create your 

own) and then make them available to users to download. 

Some examples of why you might want to distribute ViewSets to users are as follows. 

Scenario 1: New MKS Integrity Client Installation 

James Riley has just joined the development team, and he is required to set up his own 

development machine. This includes installing the MKS Integrity Client and using something 

called a Developer ViewSet to create a sandbox so he can work on getting the code base to


compile. James has no idea what a ViewSet is or where to get one. James hopes the ViewSet 

comes with the client he is about to install. 

Solution: A pre-configured Developer ViewSet is available on the MKS Integrity Server for 

specified users, and it is automatically installed for them on their MKS Integrity Clients (see 

“Default ViewSets” on page 53) when the ViewSet is configured to be mandatory (see 

“Mandatory ViewSets” on page 61). 

Scenario 2: New Specialized Role 

A new performance team has been created with a specialized role that did not previously 

exist in your organization. You decide the team can benefit from its own Performance 

ViewSet, so that the needed information and functionality is available to the performance 

team members. 

Solution: Create a Performance ViewSet (see “Creating ViewSets” on page 54) and then 

publish it to the MKS Integrity Server, specifying the group that contains the team members 

so they have access to import the ViewSet. 

Scenario 3: Process Changes to Existing Role 

Your organization has been using the Integrity User ViewSet for some time, but now a 

new process must be implemented. Much of the original ViewSet can still be used though. 

Solution: Fetch the Integrity User ViewSet from the server, edit it to represent your new 

process, and then publish it back to the server so that users can import it (thereby updating 

their existing ViewSet) to get the new process changes. 

Process Overview 

The following overviews describe publishing a new ViewSet and a personal ViewSet. 

Publish New ViewSet 

The proceeding diagram shows the general process for publishing a new ViewSet. All 

functionality is accessed through the ViewSets view (see “Viewing ViewSets” on page 51). 

ViewSets View 

Create Unpublished Publish 

Published 

ViewSet 

ViewSet 

The following is the general process for publishing a new ViewSet. 

1 From ViewSets view, create an unpublished ViewSet (see “Creating ViewSets” on 

page 54). 

57


58 

2 Publish the ViewSet to the MKS Integrity Server (“Publishing ViewSets” on page 59). 

Once the ViewSet is published, users then have access the ViewSet to download and 

import into their MKS Integrity Client. 

To update an existing ViewSet already located on the MKS Integrity Server, see “Updating 

Published ViewSets” on page 64. 

Publish Personal ViewSet 

The proceeding diagram shows the general process for taking a client-side ViewSet and 

uploading it to the server for users to access. All functionality is accessed through the 

ViewSets view (see “Viewing ViewSets” on page 51). 

Personal 

ViewSet 

Convert 

Unpublished 

ViewSet 

Publish 

Published 

ViewSet 

The following is the general process for taking a MKS Integrity Client ViewSet and 

publishing it to the MKS Integrity Server (so users can access the ViewSet to import): 

1 Convert the personal ViewSet to an unpublished ViewSet (see “Converting Personal 

ViewSet to Unpublished ViewSet” on page 58). 

2 Publish the ViewSet to the MKS Integrity Server (see “Publishing ViewSets” on page 59). 

Once the ViewSet is published, users then have access to the ViewSet to download and 

import into their MKS Integrity Client. 

To update an existing ViewSet already located on the MKS Integrity Server, see “Updating 

Published ViewSets” on page 64. 

Converting Personal ViewSet to Unpublished ViewSet 

If you want to publish a ViewSet you created as (or modified from) a personal ViewSet in 

your MKS Integrity Client, it must first be converted to an unpublished ViewSet. For 

information on the kinds of ViewSets, see “ViewSet Types and Locations” on page 52.


To convert a client ViewSet to an unpublished ViewSet, create a copy of the ViewSet from the 

ViewSets view (see “Copying ViewSets” on page 55). Any ViewSet created (including 

created through copying) is an unpublished ViewSet. 

NOTE Personal ViewSets must to be located in the MKS Integrity Client on the same 

machine as the MKS Integrity Administration Client to be available for converting to 

unpublished ViewSets. 

Alternatively, any ViewSet you edit from the ViewSets view in the MKS Integrity 

Administration Client is copied and converted to an unpublished ViewSet for editing (and so 

can be published to the MKS Integrity Server). 

Publishing ViewSets 

Only unpublished ViewSets can be published to the MKS Integrity Server. For information 

on the kinds of ViewSets, see “ViewSet Types and Locations” on page 52. To convert a 

personal ViewSet to an unpublished ViewSet, see “Converting Personal ViewSet to 

Unpublished ViewSet” on page 58. 

To publish a ViewSet using the MKS Integrity Administration Client 

CLI EQUIVALENT integrity publishviewset 


want to publish. 

2 Select ViewSet > Publish ViewSet. The Publish ViewSet wizard displays Step 1. 

Edit the ViewSet attributes as needed. For information on the fields and options, see 

“Editing ViewSet Attributes” on page 63. 

IMPORTANT MKS Integrity tracks the ViewSet independently of the name you assign 

it. Even if you rename a ViewSet, that same ViewSet is updated (overwritten) when 

you publish it again. If you want to retain the original, create and edit a copy of the 

ViewSet instead (see “Copying ViewSets” on page 55). 

To advance to the next step, click Next. 

59


60 

3 Specify how users are able to use the ViewSet. 

IMPORTANT 

If the ViewSet has been previously published, the permissions default to those of 

the ViewSet version on the server. 

If the ViewSet has not been previously published, the permissions default to 

include your user ID (as the user publishing the ViewSet). 

For more information on setting and using ViewSet permissions, see “ViewSet 

Permissions” on page 66. 

To advance to the next step, click Next. 

4 Views that are open in the ViewSet have default settings you may want to impose on the 

user. Specify the settings to include (or clear to exclude) in the ViewSet for the view 

named in the View Name field by enabling (or clearing) the selection in the Include 

column. This process may take several steps because there is a separate panel in the 

wizard for each view open in the ViewSet. 

NOTE Only settings that correspond to a command are available. 

The following information is depicted in the panel: 

View Name displays the name of the view, for example Items. 

View Title displays the title that appears in the view tab, such as 

Query: Quick Query. 

Include specifies if to include the setting value in the field. 

Setting Name displays the name of the setting. 

Setting Value displays the value the setting is currently set to. 

TIP To include all settings, click Select All. To clear all settings, click Clear All. To 

advance to the panel for each view step, click Next. 

5 When you have advanced through all of the settings panels for views, a panel displays 

that provides you with the means to test your ViewSet. To test the ViewSet, click Test 

ViewSet (see “Testing ViewSets” on page 61). The ViewSet is launched in the 

Test ViewSet GUI using the settings changes made in the previous wizard steps.

Testing ViewSets 

6 When you are finished with the Publish ViewSet wizard, click Finish. 


If the ViewSet is replacing an existing published ViewSet, The Confirm Overwrite 

Existing Server ViewSet dialog box displays. To update the existing ViewSet with your 

changes, click Yes. 

The ViewSet is published to the MKS Integrity Server, and the unpublished ViewSet 

duplicate is deleted (no longer appears in the ViewSets view). 

After you have advanced through the Publish ViewSet Wizard (see “Publishing ViewSets” 

on page 59), you can test your ViewSet before finally publishing it to the MKS Integrity 

Server for users to download and import. 

To test a ViewSet, from the Publish ViewSet Wizard click the Test ViewSet button. The 

Test ViewSet GUI displays. 

The Test ViewSet GUI provides you with a way to test the ViewSet to see how it appears and 

functions, just as it would in the MKS Integrity Client; however, the Test ViewSet GUI has the 

following restrictions: 

You can only test one ViewSet at a time. 

You can only customize the ViewSet, not perform other ViewSet modifications. 

You cannot perform any client customization. For example, there is no preference 

editing or integration editing. 

You cannot save changes you make to the open ViewSets 

Part of testing how a ViewSet appears to users is viewing the Customize ViewSet dialog box. 

It is the same dialog box that users see and use from the MKS Integrity Client. This can be 

useful to ensure that the correct editability settings have been specified for ViewSet actions 

and action groups. For information on customizing the ViewSet, see MKS Integrity Client 2009 

Getting Started Guide. 

Mandatory ViewSets 

In combination with permissions for which users are able to download and edit specific 

ViewSets (see “ViewSet Permissions” on page 66), you can ensure that the specified users get 

the ViewSets by configuring them to be mandatory. 

Mandatory ViewSets bypass the user acceptance process for downloading new (or updated) 

ViewSets from the MKS Integrity Server (see the MKS Integrity Client 2009 Getting Started 

Guide for information on the user acceptance process). Instead, mandatory ViewSets are 

automatically downloaded and imported into each user’s client at the time the MKS Integrity 

Client connects to the server. Users are not notified that the mandatory ViewSet has been 

61


62 

imported or updated and are not able to refuse the new or updated ViewSet. Once installed, 

mandatory ViewSets are automatically opened in the MKS Integrity Client and their actions 

and actions groups cannot be customized. 

Mandatory ViewSets, in combination with ViewSet permissions, provide your organization 

with another key component to producing a consistent process across or within groups. 

IMPORTANT Only published ViewSets can be specified as mandatory. 

You can specify if a ViewSet is mandatory in the following operations: 

“Editing ViewSet Attributes” on page 63 

“Publishing ViewSets” on page 59 


Users are not notified that a mandatory ViewSet has been updated and cannot refuse (or 

observe) its import. 

Mandatory ViewSets display Mandatory in parenthesis in the MKS Integrity Client title 

bar. 

Users cannot close mandatory ViewSets. 

Users can delete mandatory ViewSets, but the ViewSets are imported and opened the 

next time the MKS Integrity Client is run. 

Updated mandatory ViewSets are only opened the next time the MKS Integrity Client is 

run. 

Users may extensively customize optional ViewSets stored in their clients. If you 

configure the corresponding published (server) Viewset to be mandatory, all of the users 

customizations are silently lost. 

Mandatory ViewSets are intended to be an enforcement mechanism to provide uniform 

use of a ViewSet by users. They are not intended to be a ViewSet distribution mechanism 

only. 

Administering Published ViewSets 

Published ViewSets have properties and capabilities that personal and unpublished 

ViewSets do not. The subsequent sections provide information on administering published 

ViewSets

Published ViewSet Properties 


You can configure properties for published ViewSets, such as attributes and permissions. 

MKS Integrity provides a way to view and edit the properties of published ViewSets without 

having to create a local unpublished ViewSet duplicate. 

Viewing ViewSet Properties 

You can view the attributes and permissions of ViewSets residing on the MKS Integrity 

Server. To edit ViewSet attributes and permissions, see “Editing ViewSet Attributes” on 

page 63. 

TIP You can also view (but not edit) attributes of personal and unpublished 

ViewSets. 

To view ViewSet properties using the MKS Integrity Administration Client 


want to view properties for. 

2 Select ViewSet > View ViewSet Properties. The ViewSet dialog box 

displays, where is the name of the ViewSet you are viewing properties 

for. For information on the fields displayed on the Attributes panel, see the table in 

“Viewing ViewSets” on page 51. 

To view user and group permissions for the ViewSet, click the Permissions tab. For 

information on using the Permissions tab, see “ViewSet Permissions” on page 66. 

Editing ViewSet Attributes 

You can edit the attributes for ViewSets located on the MKS Integrity Server. Editing 

published ViewSet attributes (through editing properties) does not require a local 

unpublished ViewSet duplicate. 

TIP You can also edit ViewSet attributes when publishing a ViewSet (see 

“Publishing ViewSets” on page 59). 

From the ViewSets view (see “Viewing ViewSets” on page 51), select the ViewSet you want 

to edit attributes for. Select ViewSet > Edit ViewSet Properties. The Edit ViewSet Properties 

dialog box displays. Click the Attributes tab. 

For information on using the Permissions tab, see “ViewSet Permissions” on page 66. 

63


64 

The following attributes are editable: 

Attribute Description 

Name Contains the name for the ViewSet. ViewSet names are not required to be 

unique. MKS Integrity tracks the ViewSet independently of the name you assign 

it. However, no two published ViewSets on the same server may have the same 

name. 

Description Contains an optional description for a ViewSet. For example, tell users why and 

how they should use the ViewSet. 

Optional Specifies that the ViewSet is optional to users. Users who have permission to 

import the ViewSet may do so at their discretion, but they are not required to do 

so. When importing ViewSets, users can see if a change to this ViewSet is 

made and then can choose to import the updated ViewSet. 

Mandatory Specifies that the ViewSet is mandatory to users who have permission to import 

it. Users do not have a choice if the ViewSet is imported. Instead, the ViewSet is 

automatically downloaded and installed for the user when the MKS Integrity 

Server connects to the MKS Integrity Administration Client. For more 

information, see “Mandatory ViewSets” on page 61. 

Customizable Specifies if users can customize the ViewSet. Users cannot customize 

mandatory ViewSets. 

Fetching Published ViewSets 

To customize (edit) a published ViewSet, you must download it from the server to the 

MKS Integrity Administration Client, and save it as an unpublished ViewSet (see “ViewSet 

Types and Locations” on page 52). Editing a ViewSet (see “Editing ViewSets” on page 54) 

automates that process for you. However, you can manually fetch the published ViewSet 

without editing by creating a local duplicate (as an unpublished ViewSet) to be modified at a 

later date. 

To fetch a published ViewSet using the MKS Integrity Administration Client 

1 From the ViewSets view (see “Viewing ViewSets” on page 51), select the published 

ViewSet you want to fetch. 

2 Select ViewSet > Fetch ViewSet. The selected published ViewSet is fetched to the 

MKS Integrity Administration Client, and it appears in the ViewSets view as an 

unpublished ViewSet. 

Updating Published ViewSets 

ViewSets stored on the MKS Integrity Server (available for users to download and import 

into their MKS Integrity Clients) can be modified and updated as needed. The following 

diagram illustrates the process of updating a Server ViewSet.

Edit Server 

ViewSet 

Need to modify a 

Server ViewSet 

Creates 

Unpublished ViewSet 

Copy 

Publish ViewSet 

Server ViewSet 

Updated 

Fetch Server 

ViewSet 

1 Identify a need to modify a published ViewSet. 


2 To update a published ViewSet, get an unpublished ViewSet duplicate of the published 

ViewSet (see “ViewSet Types and Locations” on page 52). 

You can get the unpublished ViewSet duplicate by editing the published ViewSet (see 

“Editing ViewSets” on page 54) or by fetching the ViewSet (see “Fetching Published 


ViewSets can then be modified by editing or by making changes through the 

Publish ViewSet wizard. 

3 Publish your modified ViewSet back to the MKS Integrity Server (see “Publishing 

ViewSets” on page 59). The published ViewSet is updated by the publish operation, and 

users are then able to download and import it. 

IMPORTANT MKS Integrity tracks the ViewSet independently of the name you assign 

it. Even if you rename a ViewSet, that same ViewSet is updated (overwritten) when 

you publish it again. If you want to retain the original, create and edit a copy of the 

ViewSet instead (see “Copying ViewSets” on page 55). 

65


ViewSet Permissions 

66 

There are two kinds of permissions that govern ViewSets. ACL permissions regulate the 

publishing of ViewSets for the first time. Non-ACL permissions regulate if users can edit or 

publish a published ViewSet. 

IMPORTANT Users with Admin, AdminServer, and DebugServer permissions can 

modify, edit, and publish ViewSets without the required permissions documented 

in the later sections. 

Permission to Publish ViewSets 

To publish an unpublished ViewSet to the MKS Integrity Server, you need to have the 

PublishNewViewSet ACL permission assigned to you or your group. To set the permission, 

from the MKS Integrity Administration Client select the ViewSet Distribution > Permissions 

node, then highlight Global. The display pane then shows the global permission information 

for the mks:system:viewsets ACL. The default ACL entry is a group named everyone. 

ACL entries consist of principals and permissions. 

For more information on ACL principals and permissions, see the MKS Integrity Server 2009 


Published ViewSet Permissions 

ViewSet permissions control how users interact with the ViewSet. The permissions can be 

modified from the Permissions tab on the Edit ViewSet Properties dialog box (see “Editing 

ViewSet Attributes” on page 63) or from the Publish ViewSet Wizard (see “Publishing 

ViewSets” on page 59). To view permissions without editing them, see “Viewing ViewSet 

Properties” on page 63. 

NOTE The published ViewSet permissions are unrelated to ACL permissions. 

The following are available permission settings: 

Users specifies the users (and groups) permitted to import the ViewSet from the 

MKS Integrity Server. Only users specified in this field see the ViewSet as available for 

import. However, there is no requirement for users to import the ViewSet if it is not 

mandatory. To make a ViewSet mandatory for users, see “Mandatory ViewSets” on 

page 61. 

Administrators specifies the users permitted to edit the ViewSet, as well as to publish the 

changed ViewSet back to the MKS Integrity Server.

ViewSets FAQ 

For information on filtering data (in this case users and groups) see “Filtering Data” on 

page 18. 

ViewSets FAQ 

The following are frequently asked questions (FAQ) for ViewSets: 

Q. Why do I not see the ViewSets view? 

A: To see the ViewSets view, you need the PublishNewViewSet permission or a 

permission to modify any server (published) ViewSet. See “ViewSet Permissions” on 

page 66. 

Q. How can I move a ViewSet from one server to another server? 

A: Connect to the first server, and display the ViewSets view. Fetch the ViewSet from that 

server (see “Fetching Published ViewSets” on page 64). Then connect to the second 

server (displaying the ViewSets view for that server) and publish the ViewSet to that 

server (see “Publishing ViewSets” on page 59). 

Q. I have a client ViewSet, but I do not see it in my ViewSets view. Why? 

A: Ensure that the MKS Integrity Administration Client you are using to display the 

ViewSets view is located on the same machine as the MKS Integrity Client you used to 

create the client ViewSet. 

Q. Because I am always working with an unpublished ViewSet duplicate of the published ViewSet, 

how then can I rename the published ViewSet? 

A: MKS Integrity tracks the ViewSet independently of the name you assign it. Even if you 

rename a ViewSet, that same ViewSet is updated (overwritten) when you publish it 

again. You can rename a published ViewSet by editing its properties (see “Editing 

ViewSet Attributes” on page 63). 

Q. I renamed my unpublished ViewSet and then published it back to the server, hoping it would be 

treated as a new ViewSet with a different name. Why did it overwrite my old ViewSet that had 

the original name? 

A: MKS Integrity tracks the ViewSet independently of the name you assign it. Even if you 

rename a ViewSet, that same ViewSet is updated (overwritten) when you publish it 

again. Instead of renaming a ViewSet, create a copy of ViewSet instead (see “Copying 


67


68 

Q. I edited a published ViewSet, and now I have an unpublished ViewSet by the same name. Why is 

it there? 

A: Editing a ViewSet requires a local duplicate of the ViewSet in the MKS Integrity 

Administration Client. The unpublished ViewSet is that local duplicate, and it must be 

published back to the MKS Integrity Server for your changes to be available to users. 

Q. I published my unpublished ViewSet and the unpublished ViewSet disappeared. Where did it go? 

A: The unpublished ViewSet is considered unnecessary once a ViewSet is published to the 

MKS Integrity Server. You can get an unpublished ViewSet duplicate again by editing or 

fetching the ViewSet (see “Editing ViewSets” on page 54 or “Fetching Published 


Q. Why are users reporting that ViewSets I published are automatically imported into their 

MKS Integrity Clients? 

A: You have set the ViewSets to be mandatory (see “Mandatory ViewSets” on page 61). 

Q. Why can I edit but not publish a particular ViewSet? 

A: You do not have permission to publish that ViewSet. An administrator who does have 

permission to publish that ViewSet must assign you permission (see “ViewSet 

Permissions” on page 66). 

Q. Users lost their custom changes to their ViewSets. Why? 

A: Check to see if you configured the ViewSet to be mandatory. See “Mandatory ViewSets” 

on page 61. 

Q. I logged into the MKS Integrity Administration Client on a different machine, and my 

unpublished ViewSets were gone. Where did they go? 

A: Unpublished ViewSets are only stored locally on the same machine they were created 

on. You must publish the ViewSet to edit (customize) it on a different machine.

C HAPTER FOUR 

Workflow Management 

Creating Workflow to Manage Change 

Every item type follows a workflow, which is followed by every item of that type. 

Workflow is the process established by an administrator to capture and track 

information and steps during your software development cycle. 

4 

Each item type has its own set of states to advance through the development cycles. For 

example, a change request might go through the states: submitted, work started, tested, 

reviewed, and closed. 

States can also be shared across several workflows. Items and their current states 

provide change management information necessary to support business decisions. 


“Assessing Your Current Product Development Process” on page 70 

“Assigning Administrators for MKS Integrity” on page 74 

“States” on page 77 

“Types” on page 82 

“Fields” on page 121 

“Workflows” on page 152 

“Considerations When Modifying Visibility, Editability, and Types” on page 178 

“Deleting Admin Provided Objects and Items” on page 179 

“Setting Up E-mail Notification” on page 180 


The following table summarizes the steps you should follow to set up a workflow 

69

Chapter 4: Workflow Management 

Assessing Your Current Product Development 

Process 

70 


Manage states, including creating and editing 

states. 

Manage types, including creating and editing 

types. 

Set up a document model with types and 

attributes 

Manage fields, including creating and editing 

fields. 

Manage field relationships, including creating, 

editing, and deleting field relationships. 

Design a workflow, including creating, managing, 

and printing a workflow. 

Understand the considerations for modifying 

visibility rules, editability rules, and types. 

Creating and testing your workflow using the 

Admin Migration Wizard. 

This assessment involves no direct interaction with the software. Instead, you need to spend 

some time evaluating the product development process currently followed in your 

organization and map it out so you can customize your project for workflows and documents 

to suit your needs. 

This may take longer for some than for others. But the purpose of the assessment is to avoid 

the time-consuming task of redesigning a project that was not well-planned in the first place. 

When undertaking this assessment, you should focus on these areas: 

your workflow and project state transitions 

your current tracking mechanism 

the scope of implementation within your organization 

the relevant teams and user groups 



“Setting Up Documents” on page 97 


“Managing Field Relationships” on page 143 


“Considerations When Modifying Visibility, 

Editability, and Types” on page 178 

“Testing Workflow With Admin Migration Wizard” 

on page 161

Assessing Your Current Product Development Process 

To assess your workflow and project state transitions, consider the following 

questions 

1 What project states (or stages) are followed from the inception of a project to its 

completion? 

conceptualization 

design 

development 

review 

testing 

production 

2 Are approvals considered as separate stages or are they a prerequisite for moving to the 

next stage? 

Define a sequential state model for your projects. 

3 Does the workflow follow in sequence from one state to the next, or are there provisions 

for repeating certain steps? 

Consider the state transitions in your workflow. 

4 Is the workflow the same for each type of project? 

one workflow is used 

one workflow is used for each item type 

workflow depends on the urgency of the work 

In MKS Integrity, you may define a workflow for each item type. 

To assess your current tracking mechanism, consider the following questions 

1 How do you currently log defects and enhancements? 

manually, using forms 

in-house database 

no current method 

other tracking product 

Think about what items you want to track. 

71


72 

2 Who assigns work? 

team leader 

self 

Do you want only team leaders to assign the work, or can anyone assign the work? 

3 How are developers notified of work assigned to them? 

meetings, verbally 

e-mail from team leader, other team members 

through an in-house defect tracking system 

4 How do developers indicate their work is complete? 

through their configuration management / revision control system 

by e-mail 

combination of the preceding options 

through an in-house defect tracking system 

Users can promote items to states defined in the workflow. 

5 Who do developers notify when their work is complete? 

team leader only 

team leader and the submitter of the item 

the developers who are responsible for the function or module 

Users can also use the e-mail notification option. 

To assess the scope of implementation, consider the following questions 

1 Is MKS Integrity to be used in different areas of your organization? 

in development 

development and client services (including technical support) 

marketing 

Define the tracking objectives for each group. 

2 Is the workflow the same for each group? 

one workflow is used 

one workflow is used for each item type 

workflow depends on the urgency of the work 

In MKS Integrity, you may define a workflow for each item type.

Assessing Your Current Product Development Process 

To assess your teams and user groups, consider the following questions 

1 Which groups are currently involved in your tracking process? 

Are those groups to use workflows and documents? 

2 Can you predict requiring different privileges for users in these groups? 

everyone is required to administer the project for workflows and documents 

one administrator, with the rest of the team having a subset of the administrator’s 

privileges 

What workflow and document privileges do you grant to your users? 

3 What are the user groups you can identify? 

workflow and document users 

developers 

contractors 

testers/QA 

other 

You may use these groups to start defining user groups in MKS Integrity. 

4 Are your user groups defined by team, or do some user groups include members from 

different teams? 

Is your user groups to be defined by your organization structure, or by process? 

With your assessment answers in hand, you can now proceed to customizing your 

installation, described in the next section. As you go, you can refer to your assessment of 

your current tracking mechanism, your teams and user groups, and your scope of 

implementation. 

Working With MKS Integrity 

Consider the following when setting up your admin provided objects in MKS Integrity: 

The MKS Integrity Administration Client does not lock admin provided objects, making 

it possible for two or more administrators to edit a common object at the same time. The 

final state of the option is the state set by the administrator who last saved the option. 

For example, if two administrators are creating workflows at the same time, only the last 

saved workflow takes effect. This behavior should be considered if you assign multiple 

administrators for MKS Integrity. For more information on the MKS Integrity 

Administration Client, see “Introduction” on page 10. 

If your MKS Integrity system is using a DB2 database for System i, read/write 

operations to the database table must be synchronized. Therefore, administration work 

73


74 

that affects the database should be performed only when the system is not in use by 

other users. 

Assigning Administrators for MKS Integrity 

For MKS Integrity, the person who sets up and configures MKS Integrity is referred to as the 

super administrator. The super administrator can also delegate certain tasks related to projects 

for workflows and documents and types to a project administrator and type administrator. 

As the super administrator responsible for setting up MKS Integrity, you have access to all 

admin provided objects. For day-to-day management, once MKS Integrity is configured you 

may want to delegate a subset of administrative responsibilities by allowing certain users to 

manage projects and types. MKS Integrity allows you to limit access to these two key 

workflow and document objects and, in this way, delegate responsibilities for the associated 

management tasks. 

You can delegate certain administrative tasks by assigning project administrators and type 

administrators. You assign an MKS Integrity project administrator through the Create Project 

or Edit Project function. You assign an MKS Integrity type administrator using the Create 

Type or Edit Type function. For more information on project administrators, see “Assigning 

MKS Integrity Project Administrator” on page 260. For more information on type 

administrators, see “Assigning Type Administrator” on page 94. 

MKS Integrity then limits access according to the specific projects and types you have 

assigned the administrators to. The following table summarizes the functionality available to 

the MKS Integrity super administrator, project administrator, and type administrator: 

Workflow and 

Document Object 

Super Administrator Project Administrator Type Administrator 

Users Create 

Edit 

View 

Delete 

Import 

View View 

Groups Create 

Edit 

View 

Delete 

Import 

View View

Workflow and 


Dynamic Groups Create 

Edit 

View 

Delete 

Edit project membership 

Projects Create 

Edit 

View 

Delete 

Assign project or type 

administrators 

States Create 

Edit 

View 

Delete 

Type Overrides 

Types Create 

Edit 

View 

Delete 

Create/edit presentation 

templates 

Assign project or type 

administrators 

Fields Create 

Edit 

View 

Type Overrides 

Triggers Create 

Edit 

View 

Delete 

Admin Charts Create 

Edit 

View 

Delete 

Assigning Administrators for MKS Integrity 


View 

Edit project membership 

Create subprojects a 

Edit 

View 

Delete subprojects1 View 

View 

No access Create 

Edit b 

View 

Delete2 Type Overridesc No access Edit 

View 

Create/edit 

presentation 

templates 

No access Create 

Edit 2 

View 

Type Overrides 3 

No access No access 


75


MKS Integrity Administration Permissions 

76 

Workflow and 


Admin Dashboards 

Create 

Edit 

View 

Delete 

Admin Queries Create 

Edit 

View 

Delete 

Admin Reports Create 

Edit 

View 

Delete 





a Project administrators can only create and delete subprojects. They cannot create top level projects. 

b 

Type administrators can only delete/modify a field or state if they are an administrator of all types that refer to it. 

c 

Type administrators can only modify the overrides for the type they administer. Other overrides for the field cannot be 

modified. 

The MKS Integrity super administrator is set by allowing the Admin permission under the 

mks:im ACL. Any user granted the Admin permission has access to all workflow and 

document admin provided objects, including users, groups, dynamic groups, projects, states, 

types, fields, and triggers. Project and type administrators are not granted the Admin 

permission, and MKS Integrity limits their access to the specific projects and types they are 

assigned to. 

As super administrator, you can extend the capability of a project or type administrator by 

granting certain ACL permissions. The following ACL permissions extend the capability of 

the assigned administrator: 

The CreateProject permission allows the user to create a new top level project for 

workflows and documents and allows the project administrator to assign another 

MKS Integrity project administrator. 

The CreateType permission allows the user to create a new type and allows the type 

administrator to assign another type administrator. 

NOTE For more information on setting ACL permissions in MKS Integrity, see the 

MKS Integrity Server 2009 Installation and Configuration Guide.

Assigning Administrators Using Command Line Interface 

States 

Functionality for assigning MKS Integrity project and type administrators is also available 

through the CLI using commands createProject, editProject, createType, and 

editType. 

To assign a project administrator from the CLI, use the createProject or editProject 

commands with the --permittedAdministrators option. Similarly, to assign a type 

administrator, use the createType or editType commands with the 

--permittedAdministrators option. For more information on these commands, see the 

MKS Integrity Server 2009 Administration CLI Reference Guide. 

States 

In MKS Integrity, item types can each have their own set of states to advance through. They 

can also follow a state model defined by the project administrator, giving greater control over 

who has access to a specific item type at a given time, as well as who has responsibility for 

approving the advancement of the state. 

Throughout the development lifecycle, items submitted in MKS Integrity go through a 

workflow. You can customize the workflow and the stage the item is in. These stages are 

called states in MKS Integrity. For example, your process may include resource allocation, 

research, coding, and testing, or your process can be more elaborate. 

Example 

Possible states for a typical development environment are Submitted, In Review, Rejected, 

In Development, Unit Test, Development Done, Built, In QA, Passed, Failed, In Production, 

and Released. 


You can only create one state at a time. 

States can be referenced by more than one workflow. For example, you could set the 

Submit state as the starting step for all your workflows. 

Working in States View 

Using the MKS Integrity Administration Client, you can manage states from one convenient 

location. Managing states is carried out through the States view. 

CLI EQUIVALENT im states 

77


78 

To open the States view from the MKS Integrity Administration Client, expand the 

Workflows and Documents node, and select States. The States view displays. 

By default, the data filter in the States view displays all existing states. You can search for a 

specific state by typing in the text filter. For more information, see “Filtering Data” on 

page 18. 

Throughout your development lifecycle, items submitted in MKS Integrity go through a 

workflow. You can customize the workflow and the stage the item is in. These stages are 

called states in MKS Integrity. For example, your process may include resource allocation, 

research, coding, and testing, or your process can be more complex. 

Available Menu Commands for States 

Through the States view, you can: 

edit the details for existing states 

view the details for existing states 

delete states 

Creating States 

create a new state for use in your workflow 

reposition or change the sequence for an existing state in the workflow 

Any changes you make in the States view have an immediate effect on your MKS Integrity 

database. 

You can create states for use in an item type’s workflow. You can only create one state at a 

time. 

To create a state in the GUI 

CLI EQUIVALENT im createstate 

1 From the States view (see “States” on page 77), select State > Create. The Create State 


2 In the Name field, type a name for the state. This is the name the state is referred to in 


3 Under the Description tab, type a more detailed textual description of the state, such as 

the state’s meaning in your workflow. To do this, click the Description tab. 

4 Under the Position tab, specify where the new state displays in the State list within an 

item. Use the Move Up and Move Down buttons to change the position of the new state.

States 

5 Under the Image tab, associate a custom icon image with the state. To do this, select Use 

Custom Image, and click Select to browse for the image file. To have no image associated 

with the type, select No Image. 

If you choose to use your own custom icon image, the image must be in GIF or JPEG 

format, and no larger than 24 by 16 pixels. 

6 Under the Capabilities tab, define state-based capabilities. In MKS Integrity, state based 

capabilities allow change packages that are under review or change packages that are 

open to exist while an item is in a given state. For more information on the change 

package review and approval process, see the MKS Integrity 2009 User Guide. 

If the item state does not allow open change packages, MKS Integrity prompts users to 

close the item’s change package before they move any item to that state. In addition, if an 

item state does not allow open change packages, users cannot create new change 

packages for any items in that state. 

To define a state-based capability, do one of the following: 

To display only enabled state-based capabilities, from the Filter list select 

. 

To display all available state-based capabilities, from the Filter list select . 

To display only the state-based capabilities related to workflows and documents, 

select MKS Integrity. Then to allow time entries in the selected state, enable the 

Allows time entry in this state option. For more information on creating, editing, 

viewing, and deleting time entries, see the MKS Integrity 2009 User Guide. 

To display only the state-based capabilities related to configuration management, 

select MKS Source. Then select one or more of the following capabilities: 

To allow change packages under review in the selected state, enable the Allows 

SI change packages under review to exist in this state option. 

To allow open change packages in the selected state, enable the Allows open SI 

change packages to exist option. 

To display only the state-based capabilities related to test management, select MKS 

Test. To allow test results to be created and modified when a test session item is in 

the selected state, enable Allow test results to be created and modified in this state. 

For more information on using MKS Integrity to create and edit test results, see the 

MKS Integrity 2009 User Guide. 

NOTE If you are using the Implementer integration with MKS Integrity, additional 

state-based capabilities are available. 

7 When you are finished setting the properties, click OK. 

79


Editing States 

Viewing States 

80 

You can edit state details, but you can only edit one state at a time. You cannot edit the 

Unspecified state; you can only view it. 

To edit a state in the GUI 

CLI EQUIVALENT im editstate 

1 From the States view (see “States” on page 77), select the state you want to edit. 

2 Select State > Edit. The Edit State dialog box displays. 

3 Edit the information as required. For more information about the fields that display in 

this dialog box, see “To create a state in the GUI” on page 78. 

4 To determine which states are referenced by any given type, click the Usage tab for the 

state in question. 

The Usage panel shows what types refer to the state and what attributes have been 

overridden for that type. 

5 To determine all objects that reference the state, click the References tab. For information 

on the contents of the tab, see “To manage admin provided objects in the MKS Integrity 

Administration Client” on page 244. 

6 To view a history of administrative changes for the selected state, click the History tab. 

The record of changes displays. 

7 To save your changes, click OK. 

You can view detailed information for existing states. You cannot edit any of the details, and 

you can only view the details for one state at a time. 

To view a state in the GUI 

CLI EQUIVALENT im viewstate 

1 From the States view (see “States” on page 77), select the state you want to view. 

2 Select State > View. The View State dialog box displays. For more information about the 

fields in this dialog box, see “To create a state in the GUI” on page 78. 

TIP You can double click a state in the States view to view it.

Deleting States 

Moving States 

3 To determine which states are referenced by any given type, click the Usage tab for the 

state in question. 

The Usage panel shows what types refer to the state and what attributes have been 


States 

4 To determine all objects that reference the state, click the References tab. For information 



5 To view a history of administrative changes for the selected state, click the History tab. 

The record of changes displays. 

6 When you are finished viewing, click Close. 

You can only delete a state if it is unreferenced, that is, if no one has used this state in any 

item. 

To delete a state in the GUI 

CLI EQUIVALENT im deletestate 

1 From the States view (see “States” on page 77), select the state(s) you want to delete. 

2 Select State > Delete. A confirmation dialog box displays. 

3 To confirm the deletion, click Yes. 

You can customize the order the states display in. The order in the Reposition States dialog 

box is also the order used in MKS Integrity. 

To change the order of the states in the GUI 

CLI EQUIVALENT im editstate 

1 From the States view (see “States” on page 77), select State > Reposition. The Reposition 

States dialog box displays. 

2 Select the state you want to move, and use Move Up or Move Down buttons to change its 

position. 

3 Click OK. 

81


State Metrics 

Types 

82 

In addition to recording information in fields, MKS Integrity can also perform arithmetic 

operations between fields, storing the result as a read-only value in an item’s computed field, 

or displaying it as a value when you run a chart or report. Using external information 

functions in computed fields, you can generate state metrics. State metrics are useful for 

determining item responsiveness and workflow progression. For example, you could use the 

DaysInState(state-name) function in a computed expression to calculate how many days a 

Defect item was in state In Development. The computed value is then stored in the 

computed field. For more information on state metrics, see “Using Computed Fields to 

Calculate State Metrics” on page 319. 

In MKS Integrity, a type represents a category of items that share a specific development cycle 

or workflow. Individual types are required whenever an independent workflow is needed. 

As part of creating a customized workflow, type permissions allow you to control more 

precisely which users can work with an item according to the type the item is associated 

with. Type permissions allow you to create a unique set of permissions for a specified type, 

allowing the membership of the group to change based on the value of the type identifier. 

When you create a new type, visibility is allowed to the everyone group by default (that is, 

all users can see the new type). You can later restrict visibility as required. 

When creating a type in MKS Integrity, you can also designate users or groups as 

MKS Integrity type administrators for that type. For more information on type 


Example 

In a software development environment, a request for a new software feature may follow one 

workflow, while work to fix a defect may follow a different workflow. In such a scenario, the 

administrator creates two distinct types: Feature Request and Defect. 


Individual types are required whenever an independent workflow is needed. 

Type permissions allow you to create a unique set of permissions for a specified type. 

The super administrator can designate users or groups as MKS Integrity type 

administrators for a given type. 

Type properties are used to define solution-specific ViewSets that licenses are required 

for.

Requirements management and test management utilize specific document item types 

that control the behavior of documents and promote reuse and versioning. To learn 

about document types, including how to manage and create them, see “Setting Up 

Documents” on page 97. 

Working in Types View 

Using the MKS Integrity Administration Client, you can manage types from one convenient 

location. Managing types is carried out through the Types view. 

CLI EQUIVALENT im types 

To open the Types view from the MKS Integrity Administration Client, expand the 

Workflows and Documents node, and select Types. The Types view displays. 

By default, the data filter in the Types view displays all existing types. You can search for a 

specific type by typing in the text filter. For more information, see “Filtering Data” on 

page 18. 

You can categorize items into various types, for example, problems, proposals, solutions, or 

requests for change. 

Any changes you make in the Types view have an immediate effect on your MKS Integrity 

database. From the Types view you can access other type-related functions including Field 

Relationships and Workflow. For more information on these functions, see “Managing Field 

Relationships” on page 143 and “Workflows” on page 152. 

Available Menu Commands for Types 

Through the Types view, you can: 

edit the details for an existing type 

view the details for an existing type 

delete a type 

create a new item type 

copy a type 

reposition, or change the order of presentation for a type 

The workflow view is used to graphically view and create a workflow for an item type. The 

workflow view cannot be used to import users and groups, or to create projects, types, and 

fields. Only one workflow for one type can be opened in the workflow view. 

NOTE To launch the workflow view, a user must have administrator permissions. 

Types 

83


Creating Types 

84 

Access to workflow functionality occurs in the Workflow view, which is contained in the Edit 

Type dialog box. 

You can categorize items into various types, for example, problems, action items, bugs, 

proposals, solutions, or change requests. Individual types are required whenever an 

independent workflow is needed. 

When creating a type in MKS Integrity, you can also designate users or groups as 

MKS Integrity type administrators for that type. For more information on type 


To create a type in the GUI 

CLI EQUIVALENT im createtype 

1 From the Types view (see “Types” on page 82), select Type > Create. The Create Type 


2 In the Name field, enter a name for the type. This is the name MKS Integrity uses to refer 

to the type. The Name field allows up 100 alphanumeric characters. 

3 Select a node to perform a task on the Type. The following nodes are available: 

Administrators

See “Assigning Type Administrator” on page 94. 

Attributes 

See “Configuring Type Attributes” on page 87. 

Properties 

See “Using Type Properties” on page 245. 

Change Packages 

Specify how change packages are used with the type. To allow change packages to 

be created for items of this type, select Allow Change Packages. Then select which 

users can create change packages against items of this type. 

If you select Anyone, any user can create a change package for the item. 

Types 

If you select a User Field, only users selected in that field on the item can create 

a change package. 

If you select a Group Field, only users who belong to groups selected in that 

field on the item can create a change package. 

If you select Groups, only users who belong to the groups selected in the list can 

create a change package. 

NOTE 

Custom user fields and any group fields first must be made visible for the type. 

Field relationships are set after Visible Fields are configured. 

Test Management 

Defines the type as part of Test Management. 

See “Setting the Test Management Role for Types” on page 112. 

Documents 

Define the model for item types that utilize documents. 

See “Setting Up Documents” on page 97. 

Editability 

See “Setting Item Editability for Types” on page 114. 

Field Relationships 

See “Managing Field Relationships” on page 143. 

Notification Fields 

Specify the notification fields you want to include in every e-mail notification 

related to this type. All visible fields for this item type are available. All users 

85


86 

receive e-mail notifications with the notification fields you select, even if the fields 

are normally invisible to them. 

NOTE For the selected type, only fields visible to at least one group are listed. 

By default, the e-mail notifications include the item ID, type, and summary, as well 

as a hyperlink to the item, the date the item was edited, the user who performed the 

edit, and the fields that were modified. 

Overrides for Fields and Overrides for States 

The Overrides for Fields and Overrides for States nodes are type 

overrides and are configured as required after the type is created. For more 

information on type overrides for fields and states, see “Setting Type Overrides” on 

page 115. 

Permissions 

Specify the groups that have access to the type. In the right pane under Available 

Groups, select the desired groups and move them to Permitted Groups. 

As part of a customized workflow, type permissions allow you to control more 

precisely which groups can work with an item according to the type the item is 

associated with. Type permissions allow you to create a unique set of permissions 

for a specified type, allowing the membership of the group to change based on the 

value of the type identifier. 

By default, the everyone group is included in the list of Permitted Groups. This 

means that by default all users have access to created types in MKS Integrity. To 

limit access to a type, move the everyone group to the Available Groups list. 

Position 

Customize the order that types display in. The order you select is the order the type 

appears in the Create Item list. Use the Move Up or Move Down buttons to change the 

position of the new type. 

Copy Fields 

Define which fields are copied when items of this type are copied. In the Copy Fields 

list, select the fields to be copied. The fields must be visible to the user in both the 

original item and the new item in order to be copied. 

Visible Fields 

Define which fields are visible for particular groups. In the Fields list, select a field 

to define visibility for. 

CAUTION A type can contain a maximum of 1000 fields. Exceeding the maximum 

number of fields results in exception errors when creating, editing, or viewing the 

item type in the GUI.

Types 

In the Selected Field Is Visible For list, select the groups that can see this field. By 

default, the everyone group is selected. In this list, use the Select All button to select 

all the groups list, and use the Unselect All button to clear all the groups in the list. 

For more information on field visibility for types, see “Setting Field Visibility for 

Types” on page 120. If there are no fields defined for your installation, see “Creating 

Fields” on page 127. 

Workflow 

Design the workflow for the type. For more information, see “Workflows” on 

page 152. 

Presentations 

Customize the item presentation using the presentation template designer. For more 

information, see “Customizing Item Presentation” on page 188. 

History 

View a record of all changes made to the type object. 

References 

Determine all objects that reference the type. The References pane displays the 

following information: 

Object Type displays the type of object referencing the type. Possible objects 

include: Type (item), Field (includes computed fields, as well as editability, 

relevance, and visibility rules), Trigger (includes trigger and notification rules), 

User Notification Rule, Chart, and Query. 

Name displays the actual name of the object referencing the type. 

Creator displays the user ID that was logged as creating the object reference. 

NOTE Fields or states containing overrides display in the References pane regardless 

of whether the fields are visible or the states are included in the workflow. 

4 To save your settings and create the type, click OK. 

Configuring Type Attributes 

Type attributes are general configurable settings for the type such as version control, its icon 

image, and description. 

To configure type attributes in the GUI 

CLI EQUIVALENT im createtype or im edittype 

87


88 

From the Create Type or Edit Type dialog box (see “Creating Types” on page 84 or “Editing 

Types” on page 91), in the tree pane, select Attributes. The Attributes view displays. 

Under General, you can permit the following: 

Display Workflow in Item displays the Workflow tab to the user in the Create Item, Edit 

Item, and Item Detail views. The tab also displays copying an item and when creating a 

related item. The Workflow tab contains a read-only display of the item type workflow to 

the user. 

NOTE Users in the Web interfaces do not have a client-side user preference to 

override the display of the Workflow tab. Users launching the GUI view from the 

CLI can override the display of the Workflow tab on a per command basis, if the tab 

is enabled for the type. 

To display phases in the Workflow tab, select a phase field from the Phase Field list. Only 

phase fields that are enabled in the Visible Fields node appear in the Phase Field list. 

For more information on phases, see “Phase Fields” on page 130. 

Under Items of this type, you can permit the following: 

Allow Time Tracking allows one or more users to allocate time spent working on items of 

this type. When enabled, a Time Entries tab displays in the Edit Item and Item Detail 

views. You can use time entries to develop metrics (in the form of queries, charts, and 

reports) that measure the amount of effort spent on projects.

NOTE 

To create, edit, and delete time entries on behalf of other users, the 

TimeTrackingAdmin ACL permission is required. 

The ability to create, edit, and delete time entries is governed by state-based 

capabilities. For more information, see “Creating States” on page 78. 

Types 

Back Projects enables the type to back a project, allowing you to create a link between an 

item of this type and a project in the Project field. Backing a project with an item allows 

you to link the current project to a specific item that stores project metadata and metrics. 

For more information, see “Managing Metadata for Workflow and Document Projects” 

on page 257. 

NOTE 

To make this option available, the Project field must be selected as a visible field 

for this type. 

If you enable the Back Projects option, creating items of this type and linking 

them to projects is useful only to certain users. You may want to prevent most 

users from being able to create items of this type, for example, you can allow only 

users in the ProjectManagers group to create Project items. To restrict type 

visibility, see “Setting Type Visibility” on page 114. 

May have their tree copied allows items of this type and all related items within the 

hierarchy to be copied. Copy tree is disabled by default and is available primarily for the 

use of MKS solution templates. 

When this option is selected, the Rule for Copy Tree button is enabled. Selecting this 

button displays the Edit Copy Tree Rule dialog box, which closely resembles the Item 

Editability dialog box. 

To learn more about item editability, see “Setting Item Editability for Types” on 

page 114. To learn more about rules, see “Defining Rules” on page 43. 

May be branched allows items of this type to be branched by users who have applicable 

project visibility based on the branching rules you set up for item types. A branch is an 

identical copy of the original item and is added to the project history based on a current 

or historical date. 

Branches are created when users want to begin new divergent work off of a current or 

historical version of an item. For more information about what is visible to the user in the 

MKS Integrity Client after an item is branched, see the MKS Integrity 2009 User Guide. 

Branching is disabled by default and is available primarily for the use of MKS solution 

templates. 

When this option is selected, the Rule for Branching button is enabled. Selecting this 

button displays the Edit Branch Rule dialog box, which closely resembles the Item 

89


90 

Editability dialog box. This rule allows you to define the rules for the branching specific 

item types for users and user groups. 



May have labels applied allows items of this type to have labels applied. 

Labels allow users to associate a particular point in time of an item or group of items 

with a name, for example, items belonging to a prior release, or those marking project 

milestones or document baselines. Labeling is disabled by default and is available 

primarily for the use of MKS solution templates. 

For more information about what the user sees in the MKS Integrity Client after an item 

is labeled, see MKS Integrity 2009 User Guide. 

IMPORTANT You must set up a rule to enforce the permissions for labeling before 

you enable labels on a type. 

When you select this option, the Rule for Add Label and Rule for Delete Label buttons are 

enabled. Selecting a button displays either the Edit Label Rule or the Edit Delete Label 

Rule dialog box. Each closely resembles the Item Editability dialog box. 



May be deleted, controlled by rule allows items of this type to be deleted, as defined by a 

rule. Users or groups defined in the rule that are allowed to delete items of this type 

require the ModifyDeleteItemRule permission. 

IMPORTANT The ModifyDeleteItemRule permission differs from the 

DeleteItem permission, which allows users or groups to delete items of any type 

without a defined rule. To define strict item deletion rules in your organization, 

MKS recommends defining a delete item rule and assigning the 

ModifyDeleteItemRule permission to the appropriate users and groups. 

When you select this option, the Rule for Delete Item button is enabled. Selecting this 

button displays the Edit Delete Item Rule dialog box, which closely resembles the Item 

Editability dialog box. This rule allows you to define the rules for deleting specific item 

types for users and user groups. 

To learn more about deleting items, see the MKS Integrity 2009 User Guide. To learn more 

about item editability, see “Setting Item Editability for Types” on page 114. To learn 

more about rules, see “Defining Rules” on page 43. 

To associate a custom icon image with the type, under Image select Use Custom Image, and 

browse for the image file. When you select an image for the type, it displays with the type. To 

have no image associated with the type, select No Image.

Editing Types 

Types 

If you choose to use your own custom icon image, the image must be in GIF or JPEG format, 

and no larger than 24 by 16 pixels. 

In the Description field, type a descriptive statement about the type if necessary. 

You can edit the details of an item type, but you can only edit one type at a time. 

To edit a type in the GUI 

CLI EQUIVALENT im edittype 

1 From the Types view (see “Types” on page 82), select the type you want to edit. 

2 Select Type > Edit. The Edit Type dialog box displays. 

3 Edit the type as required. Details on the individual nodes are provided as follows: 

Administrators, see “Assigning Type Administrator” on page 94. 

Attributes, see “To configure type attributes in the GUI” on page 87. 

Properties, see “Using Type Properties” on page 245. 

Change Packages, see “To create a type in the GUI” on page 84. 

Documents, see “Setting Up Documents” on page 97. 

Test Management, see “Setting the Test Management Role for Types” on page 112. 

Item Editability, see “Setting Item Editability for Types” on page 114. 

Field Relationships, see “Managing Field Relationships” on page 143. 

Notification Fields, see “To create a type in the GUI” on page 84. 

Overrides for Fields and Overrides for States, see “Setting Type 

Overrides” on page 115. 

Permissions, see “To create a type in the GUI” on page 84. 

Position, see “To create a type in the GUI” on page 84. 

Visible Fields, see “To create a type in the GUI” on page 84. 

Workflow, see “Workflows” on page 152. 

Presentations, see “Customizing Item Presentation” on page 188. 

References, see “To create a type in the GUI” on page 84. 

History, see “Viewing Administration History” on page 47. 

91


Copying Types 

92 


You can copy a type and rename it to create a new type. Copying a type is useful for quickly 

creating a new type that shares common details with an existing type. 

When naming a copied type, you cannot use a name that already exists. 

To copy a type in the GUI 

CLI EQUIVALENT im copytype 

1 From the Types view (see “Types” on page 82), select the type you want to copy. 

2 Select Type > Copy. The Copy Type dialog box displays. 

3 In the Name field, type a new name for the type. This is the name MKS Integrity uses to 

refer to the type. The Name field allows 100 alphanumeric characters. 

4 Edit the type as required. Details on the individual nodes are provided as follows: 





Documents, see “Setting Up Documents” on page 97. 











References, “To create a type in the GUI” on page 84. 

History, see “Viewing Administration History” on page 47.

Viewing Types 


You can view the details of an item type, but you can only view the details for one type at a 

time. 

To view a type in the GUI 

CLI EQUIVALENT im viewtype 

1 From the Types view (see “Types” on page 82), select the type you want to view. 

2 Select Type > View Definition. The Type dialog box displays. 

3 Details on the individual nodes are provided as follows: 





Types 

Test Management, see “Setting the Test Management Role for Types” on page 112. 

Document, see “Setting Up Documents” on page 97. 











References, “To create a type in the GUI” on page 84 

History, see “Viewing Administration History” on page 47. 

4 When you are finished viewing the information, click Close. 

93


Deleting Types 

Moving Types 

94 

If you decide you no longer need a particular type, you can delete it, as long as no items of 

that type have been created. You can delete more than one type at a time. 

To delete a type in the GUI 

CLI EQUIVALENT im deletetype 

1 From the Types view (see “Types” on page 82), select the type(s) you want to delete. 

2 Select Type > Delete. A confirmation dialog box displays. 


NOTE You can delete a type only if it is not used by other admin objects and it has 

not appeared in your history, that is, if no one has created an item of that type. To 

view references to the type, see “Viewing Types” on page 93. 

You can customize the order the types display in. MKS Integrity uses the order displayed in 

the Reposition Types dialog box. 

To change the order of the types in the GUI 


1 From the Types view (see “Types” on page 82), select Type > Reposition. The Reposition 

Types dialog box displays. 

2 Select the type you want to move, then click Move Up or Move Down as required. 

3 Click OK to save your changes. 

Assigning Type Administrator 

As the super administrator for MKS Integrity, you can designate groups or individual users, 

or a combination of them, to be type administrators for the selected type. 

MKS Integrity type administrators are allowed to edit and view types. Type administrators 

are not allowed to assign themselves as administrators to any other types, or to edit types 

that are assigned to other type administrators.

TIP If you have multiple type administrators, MKS recommends as a best practice 

that you isolate the administration objects that each type interacts with, for example, 

dynamic groups. This prevents type modifications made by one administrator 

affecting another type. 

NOTE To determine which fields and states are referenced by any given type, 

administrators can view the Usage panel for the field or state in question. The Usage 

panel shows the types that refer to the field or state and the attributes that have been 


If the assigned type administrators are granted the CreateType ACL permission, then they 

are allowed to create new types, as well as delete any types. MKS Integrity type 

administrators who are granted the CreateType permission can also assign other type 

administrators. For more information on the CreateType permission, see the MKS Integrity 

Server 2009 Installation and Configuration Guide. 

Types 

The list of available users and groups contains all active and inactive members that have been 

imported into MKS Integrity; however, the available list does not necessarily include all users 

and groups available in the realm. For more information, see the MKS Integrity Server 2009 


The following table summarizes the capabilities and limitations of the type administrator: 

Type administrators can: Type administrators cannot: 

Create fields and states. 

Create new type in MKS Integrity (if 

CreateType permission is granted). 

Edit and view existing types where they are 

assigned type administrator. 

Edit and view fields and states referenced by 

corresponding type if they are also type 

administrator for all types that reference those 

fields. 

Edit field overrides for type they administer. 

Delete type (if the CreateType permission is 

granted). 

View users, groups, dynamic groups, projects, 

states, and fields. 

View assigned type administrators. 

Create, edit, view, and delete custom 

presentation templates. 

Example 

Edit fields (fields cannot be deleted) or states 

that reference types assigned to another 


Delete states that reference type assigned to 

another administrator. 

Edit users, groups, dynamic groups, projects, 

or triggers. 

Create/import or delete users, groups, 

dynamic groups, projects, or triggers. 

Create new type in MKS Integrity (unless 

CreateType permission granted). 

Assign another type administrator (unless 

CreateType permission granted). 

Mary is the type administrator for the Feature type and Neil for the Defect type. The types 

reference the following fields: 

95


96 

With this arrangement, Mary can modify the ReleaseID field and Neil can modify the 

Priority field; however, neither administrator can modify the Date or Description fields 

because these are shared between the two types. Type administrators cannot make edits to 

fields or states that affect other types not administered by them. 

Only the super administrator is automatically allowed to modify fields that are referenced by 

multiple types. To modify fields or states that are referenced by multiple types, the user must 

be assigned as a type administrator for all types referencing those fields. For example, if Mary 

is added as a type administrator for the Defect type then she can modify all three fields (Date, 

Description, and ReleaseID), assuming no other types referenced these fields. 

A type administrator can add an existing field to his or her type; however, if the selected field 

is already referenced by another type, no type administrator is then allowed to make changes 

to that field. For example, if Mary added the Priority field to the Feature type, then Neil is 

no longer able to modify the Priority field. 


Only the super administrator is automatically allowed to assign a type administrator in 

MKS Integrity. Type administrators can assign another type administrator only if they 

are first granted the CreateType permission. 

Through the Create Type window, the super administrator can also assign a type 

administrator while creating a new type. 

To assign an MKS Integrity type administrator 


Type Fields Referenced 

Feature Date 

Description 

ReleaseID 

Defect Date 

Description 

Priority 

1 From the Types view, select the type you want to create a type administrator for, then 

select Type > Edit. The Edit Type window displays. 

NOTE Only the super administrator is automatically allowed to assign a type 

administrator in MKS Integrity. Type administrators can assign another type 

administrator only if they are first granted the CreateType permission. 

Through the Create Type window, the super administrator can also assign a type 

administrator while creating a new type.

2 Click the Administrators node. 

To assign a specified user or group as a type administrator, see “Filtering Data” on 

page 18. You can assign more than one user or group as a type administrator. 

Types 

3 Click OK to accept the changes. The selected user or group is assigned as a type 

administrator. Users and groups displayed in the Assigned column are then allowed to 

manage the selected type in MKS Integrity. 

Setting Up Documents 

Documents are containers for content items in MKS Integrity. Each document is composed of 

three types: Segments, Nodes, and Shared items, as well as two specific relationships: 

Contains/Contained By and References/Referenced By. Together, these types and 

relationships form a document model. 

Document models control the behavior of documents and content modified by users across 

and between domains. A domain is an area of discipline or other logical grouping of like 

documents; for example, requirements management and test management. The root of each 

document is called a segment root and it has a set of Node types that are its content. Shared 

items are referenced by nodes and represent shared content in a document model. 

As an administrator, it is your task to create new and modify existing document models from 

the MKS Integrity Administration Client. To learn the specific definitions for all of the terms 

mentioned above, see “Key Terms and Concepts in Documents” on page 98. 

The following graphic illustrates how segments, nodes, and shared items interact in a typical 

document model: 

Typical Document Model with relationships 

This section describes how to create document types that control the behavior of documents 

modified using the Document view in MKS Integrity. 

97


98 

As an administrator you are responsible for: 

creating all three document types (segment, node, shared item) and assigning the 

applicable permissions to users and groups 

adding the document type to the Category list users will see in the Document view by 

editing the Shared Category field 

making the associated segments and/or nodes meaningful or non-meaningful 

defining field relationships for the fields you want to make traces as well as any other 

relevant field relationships 

defining additional attributes on the document types the same way you would any type 

in MKS Integrity, for example, triggers and queries 

The MKS Application Lifecycle Management (ALM) solution template contains sample 

document types with associated sample configurations. To learn more about the ALM 

template, which includes requirements management and test management concepts and case 

studies specific to the operation of the document model in MKS Integrity, see the ALM 

section of the MKS Customer Community Knowledge Base found at http://www.mks.com/ 

community. 

Key Terms and Concepts in Documents 

This section discusses document model terms and concepts at a high level. It gives you the 

basis for understanding these concepts so you can create typical document types using the 


For more details and diagrams on the concepts in this section, including use cases, best 

practices, and other relevant information, see the ALM section of the MKS Customer 

Community Knowledge Base found at http://www.mks.com/community.

MKS Integrity 

Term 

Architectural 

Term 

Document (root) Segment 

(root) 

Document Segment/ 

Subsegment 

Definition 

Types 

Container for nodes that reference shared items or other documents. 

A root document is also considered a segment. 

Represented by the top-level node in the Outline panel of the Document 

view. 

May be related to the item backing the project via the Documents 

relationship. The subsegment refers to the node that references a segment 

root. 

Segments: 

are documents or subdocuments that contain content. 

can include or reference other segments. 

Subsegments: 

are segments that are a part of another document. If they are independent of 

another document they are considered segments. 

are included or inserted into a document which creates a References/ 

Referenced By relationship between nodes/segment respectively. 

can be nested within segments or other subsegments. 

Content Node Content: 

is the term used in MKS Integrity for a node/shared item pair; the node 

references the shared item. 

can be meaningful, for example, a requirement, test case, segment or 

subsegment. It can also be non-meaningful; for example a heading or a 

comment. These criteria are defined by your system administrator on the 

Shared Category field. 

Nodes: 

are references to individual content items (can also be subsegments 

containing their own nodes) that belong to a document and contain 

document-specific metadata. 

Contents n/a All node/shared item pairs that are contained within a document. 

Shared Item n/a MKS Integrity items that represent shared content in your document model. 

Transparent during the creation or modification of content. 

Shared Items: 

are referenced by nodes. 

track modifications to content and reflect them in the node. 

Section n/a A grouped hierarchy of nodes in a document, for example: section 1.4 and its 

children, 1.4.1, 1.4.2 or section 3.4.2 and its children 3.4.2.1, 3.4.2.2. 

Reference mode n/a Setting available on a node within a document that controls how the system 

behaves when content is reused and modified. Options are: Author, Reuse, 

Share. 

99



Term 

100 

Architectural 

Term 

Category n/a Pick field exposed on a node or segment type which allows for the 

categorization of content items, for example: Heading, Comment, Requirement, 

Test Case. 

You can select a segment or node type from the Category pick list value when 

you create or modify a segment or a node. 

Available options are defined by your administrator on the Shared Category 

field. 

Group document n/a A read-only document used for grouping content. You cannot create or edit 

meaningful content in a group document. 

How Segments and/or Nodes Are Exposed to Users 

Editable Field Value Attributes (FVAs) are the mechanism used to expose data contained on 

the shared item to the user through the node in a document. 

When you are creating a field that contains common data across all instances of its use, you 

create it on the shared item and create a paired FVA on the node. If the field is project-specific 

it only needs to be created on the node. 

To learn how to edit built in FVA fields to expose data to users on the shared item after 

creating item types, see “Document Set Up Tasks” on page 103. 

To learn how to create a node/shared item relationship by editing FVAs, see “Editing Field 

Relationships” on page 151. 

Document Relationships 

There are three classes of relationships that work with the segment, node and shared item 

types to complete the document model within MKS Integrity. 

Structural 

The structural relationship is used to construct the tree hierarchy or document structure. 

Each parent in the hierarchy can have one or more children. Conversely, each child can 

have only one parent. 

The main structural relationship is between the segment and the node, or the node and a 

node and is called Contains/Contained By. 

Couplet 

Definition 

The couplet relationship is used to connect the node(s) to the shared item. This 

relationship, in combination with the Reference Mode field, controls how content is 

versioned, branched, and reused within a document model. 

The node/shared item relationship is called References/Referenced By.

Trace 

Types 

Trace relationships are used to link document content to other items for a specific 

purpose. 

Users can create trace relationships between two items in the document model 

repository, for example, between a requirement and a test case, or between a higher-level 

requirement and a lower-level requirement. 

Trace relationships connect nodes, not shared items, together and are tied to the 

Category field rather than to the type of the object itself (not MKS Integrity item types) 

for content. Using type properties, you can control the relationships between the various 

types and categories of items. Although the number of trace relationships is not 

constrained, generally there is one relationship between each type of object in the 

system, for example: high level requirements, marketing requirements, test cases, and 

components. As an administrator, you can define which relationship fields act as trace 

fields relationships between document content items. 

To learn how to create a trace relationship field, see the ALM section of the MKS 

Customer Community Knowledge Base found at http://www.mks.com/community. 

To learn how users create trace relationships, see your MKS Integrity 2009 User Guide. 

Trace relationships are often used in the context of the ALM template. To learn more 

about these another other relationships in ALM, see the ALM section of the MKS 


Customizing Document Content 

Document content is a general term used to describe all of the items contained within a 

document or all nodes and shared items contained in a segment. Since all of the nodes of a 

given document are of the same MKS Integrity type, you need a way to differentiate between 

headings, comments and other more specific content items. The fields Category and Shared 

Category are used for this differentiation and field relationships are used to limit the choices 

for the field in each domain. 

Categories 

Categories are defined on the shared item or segment root via the Shared Category field. The 

value of the category is exposed to the end user via the FVA Category field on a node. In 

addition to this field pair, field relationships help constrain which values are available on 

each type in a document mode. For example, users are prevented from assigning a category 

value of Business Requirement to a test case through the use of field relationships. 

Meaningful and Non-Meaningful Content 

Meaningful and non-meaningful content are the terms used in MKS Integrity to differentiate 

types of content for the purposes of reporting and metrics. By default, content is meaningful 

if it is not of category Comment or Heading. 

101


102 

For example, a node with a category of Performance Test may be meaningful to your 

metrics, but the headings contained in the content items may not be. You define content as 

meaningful or non-meaningful on the Shared Category field after you create document types. 

You can define content as meaningful or non meaningful when you edit the Shared Category 

field. Similar to Category values, you can create queries and triggers that operate based on 

meaningful and non-meaningful definitions for document content. 

To learn how to create document model queries, see MKS Integrity 2009 User Guide. 

For sample document model triggers, see the ALM section of the MKS Customer Community 

Knowledge Base found at http://www.mks.com/community. 

Significant Fields 

Defined for the segment, node, and shared item. Significant fields are fields that, when 

modified by users, result in an update to the contents revision identifier, by default the 

Revision Date or Input Revision Date fields. 

Changes are reflected to the user in the item history and can be viewed through the History 

tab of the individual items of via reports defined within your configuration. Each type has 

default associated significant edit fields. 

Setting up a document model within MKS Integrity, you must define significant fields for 

each document type. 

The ALM template has sample built-in significant fields by type, for details see the ALM 

section of the MKS Customer Community Knowledge Base found at http://www.mks.com/ 

community. 

Reference Modes 

Reference mode is a system-defined field on nodes that contributes to controlling how 

content is shared and reused within a document model. 

The following are valid reference mode values, some of which users can set and others are 

controlled by the system: 

Author 

The content belongs to the current document. Any user or group with permissions to do 

so can modify the content. A new version or branch is not created when content with a 

reference mode value of Author is modified. 

Reuse 

The content belongs to another document and is being referenced by the current 

document. Any user or group with permissions to do so can modify the content and any 

modification do not affect any other reference to the same shared item. Should a change 

be made, the system branches the item and the branched item then has an author 

reference to it.

Share 

The content belongs to another document and is being referenced by the current 

document. The content cannot be modified directly but shows all changes made by the 

author. 

MKS Solution Global Type 

The MKS Solution global type contains system-defined type properties that control the 

behavior of the documents and content across and between domains as well as some 

Document view behaviors. 

Type properties within this type that should never be modified are denoted with MKS Only. 

Details about type properties and other specific tasks related to the modification of the MKS 

Solution global type is contained in the MKS Customer Community Knowledge Base 

found at http://www.mks.com/community. 

Types 

For more information about how types are created and modified in general in MKS Integrity, 

see “Types” on page 82. 

Creating a Document Domain 

This section contains the procedures required in order to set up a typical document model, 

using the options available under Workflow and Documents in the MKS Integrity 


To understand how to create a document model using three types in the MKS Integrity 

Client, in this section you create a sample document domain called Requirements that has 

sample document types and sample attributes, for example: states, projects, visible fields, 

field relationships. 

The example in this section assumes you are setting up a document model for the first time. 

You can also copy existing document domain by copying and modifying the three document 

types (segment, node, and shared item) the way you would any type in MKS Integrity. 

Document Set Up Tasks 

The following table outlines the steps required to define a typical document model. 

Step Task Procedure(s) 

1 Create a project with the applicable permissions to 

back your document items. 

2 Create a state to use as the Initial State when you 

create document types. The initial state is selected 

for each document type when you create them. You 

may want to define different states for documents 

and nodes. 

“Workflow and Document Projects” on page 248 

“Creating Projects” on page 265 


“Creating States” on page 78 

103


Step Task Procedure(s) 

3 Create a Shared Attachment field to support rich 

content. 

4 Create a Shared Text field to support rich content. 

Set the Default Attachment Field to the newly 

created Shared Attachment field. 

5 Create the following two FVA fields and make them 

editable; they use the References relationship to the 

shared fields you created in step 3 and 4: 

Attachment 

Text 

6 Create a Shared_Requirement type with the 

applicable attributes. 

7 Create a node type called Requirement with the 

applicable attributes. 

8 Create a segment type called Requirement_ 

Document with the applicable attributes. 

9 Edit the References relationship field. For type 

Requirement, allow type Requirement_ Document. 

10 Make the applicable nodes and/or segments 

meaningful or nonmeaningful by editing the Shared 

Category field. 

104 

Creating Document Types 


“Creating Fields” on page 127 



CLI EQUIVALENT im createtype or im edittype 


“Field Value Attribute Fields” on page 129 

“To create a shared item type in the GUI” on 

page 105 

“To create a node type from the GUI” on page 106 

“To create a segment type from the GUI” on 

page 108 

“To edit the References field relationship to add the 

Requirement Document type” on page 110 

“Meaningful and Non-Meaningful Content” on 

page 101 

This step is included as a part of “Creating 

Document Types” on page 104. 

11 Create trace relationships fields. This step is included as a part of “Creating 

Document Types” on page 104. 

In order to set up a domain for managing Requirements, a segment, a node, and a shared 

item type need to be created using the various options on the Document Model node in the 

Create Type dialog box. These types need to be set in order to interact and control the 

behavior of the documents users create and modify. None is the default value for all domain 

types that do not utilize a document model. 

The following table lists the examples you will create in this section and their associated 

relationships:

Name Type Relationship 

Shared_Requirement Shared Item Represented by the Reference relationship which is pre-defined 

in MKS Integrity. 

Requirement Node Represented by the Contained By relationship to the segment 

and Referenced By relationship to the shared item. 

This relationship is pre-defined in MKS Integrity. 

Requirement_ Document Document 

(segment root) 

To create a shared item type in the GUI 

In this example, you create a shared item type called Shared_Requirement. 

1 Ensure you have completed steps 1–5 in “Document Set Up Tasks” on page 103. 

2 From the Types view (see “Types” on page 82), select Types > Create Type. The Create 

Type dialog box displays. 

3 Type Shared_Requirement in the Name field. 

4 In the tree pane, select Attributes (see “Configuring Type Attributes” on page 87). The 

Attributes view displays. Enable the following: 

May have their tree copied 

May be branched 

May have labels applied 

5 Define the following as Visible Fields (see “Setting Field Visibility for Types” on 

page 120): 

State 

Shared Attachments 

Shared Text 

6 Define a workflow (see “Creating Workflow” on page 158) with the following 

transitions: 

Unspecified–Active 

Active–Active 

To create the type that fulfills the role of Shared Item: 

Represented by the Contains relationship. This relationship is 

pre-defined in MKS Integrity. 

7 In the tree pane, select Document Model. The Document Model view displays. 

Types 

105


106 

8 Select Shared Item from the drop list at the top of the dialog box. Settings for Shared Item 

displays. 

To learn more about shared items in the document model, the MKS Customer 

Community Knowledge Base found at http://www.mks.com/community. 

Define the Significant Edit Fields setting for the shared item. Specify the significant fields 

for this type (see “Significant Fields” on page 102). To learn how to create and modify 

fields, see “Fields” on page 121. 

9 Define the following field relationships (see “Managing Field Relationships” on 

page 143): 

Type=Shared_Requirement 

Shared Category=Heading, Comment,System Requirement, .... 

10 Define additional type attributes using the tree pane. Refer to the following sections for 

complete details about the options included with the node: 





“Customizing Item Presentation” on page 188 

“MKS Integrity Administration Permissions” on page 76 

11 Click OK to finish creating the Shared_Requirement type and its associated attributes. 

You will now create a node type for the shared item to reference. 

To create a node type from the GUI 

In this example, you create a node type called Requirement. 




3 Type Requirement in the Name field. 


Attributes view displays. 

5 Enable the following: 



May have labels applied


transitions: 



Types 

7 Define the following Visible Fields (see “Setting Field Visibility for Types” on page 120): 

Project 

State 

Text 

Text Attachments 

To create the type that fulfills the role of node: 

8 In the tree pane, select Document Model. The Document Model view displays. 

9 Select Node at the top of the dialog box. Settings for Node displays. 

To learn more about nodes in the document model, see the MKS Customer Community 


Select the Shared Item Type you want to reference from the node from the list. In this 

example, the Shared Item type has already been created and is called 

Shared_Requirement. 

Previously created shared item types display in this list if any were created or 

installed via the ALM template. The ALM template comes with built in sample 

types. To learn more about the ALM template, see the MKS Customer Community 


Significant Edit Fields 

10 Click OK. 

Specify the significant fields for this type. See “Significant Fields” on page 102. 

To learn how to create and modify fields, see “Fields” on page 121. 

11 Create a Property (see “Configuring Type Attributes” on page 87) called 

MKS.PrimaryTextField. This property cannot be specified using the MKS Solution 

global type property. It must be specified on all nodes when there is more than one long 

text field on the shared item. 


page 143): 

Type=Requirement 

Shared Category=Heading, Comment, System Requirement 

107


108 

13 Define additional type attributes using the tree pane, see the following sections for 








14 Click OK to finish creating the Node type and its associated attributes. 

You will now create a segment type to contain the node type you just created. 

To create a segment type from the GUI 

In this example, you create a segment type called Requirement_Document. 





Attributes view displays. 

4 Enable the following: 



May have labels applied 


transitions: 



6 Define the following as visible fields (see “Setting Field Visibility for Types” on 

page 120): 

Project 

State 

Shared Attachment 

Shared Text 

7 In the tree pane, select Document Model. The Document Model view displays.

To create the type to fulfill the role of segment: 

8 Select Segment from the list. The Settings for Segment dialog box displays. 

Types 

9 Select the Node Type you want to reference the node from the list. In this example, select 

the Requirement node type that you created previously. 

This list is empty if you did not create a node type. Previously created node types 

display in this list if you created or installed any via the ALM template. The ALM 

template comes with built in sample types. To learn more about the ALM template, see 

the MKS Customer Community Knowledge Base found at http://www.mks.com/ 

community. 

10 Define the following settings for the segment: 

a) Add or remove Significant Edit fields. 

Specify the significant fields for this type. See “Significant Fields” on page 102. 

To learn how to create and modify fields, see “Fields” on page 121. 

b) Select a Print Report to use as the format you want for the printed output the user 

sees when they print a document of this type in MKS Integrity. Reports should be 

designed to print the entire document. 

Any administration report can be used for printing a document. However, MKS 

recommends you use the Document Content report that is included with the ALM 

template. 

To learn more about the ALM template, see the MKS Customer Community 


For additional information, refer to “Defining the Format of Printed Documents” on 

page 111. 

c) Check Group Document if you use this item type to group content. You cannot 

create or edit meaningful content in a group document. 

For example, the ALM template uses Test Group to collect test cases for test 

execution. Tests can be authored in test suites, based on functional or architectural 

structures, and linked to the requirements that they verify. This grouping of tests 

makes it easy for the author to ensure complete testing coverage. But in some testing 

environments not all tests in a suite are executed at the same time. The Test Group 

can be used to organize a subset of test cases for each environment, with special 

testers and scripts. For more examples of using grouping in test management, see 

the MKS Customer Community Knowledge Base found at http://www.mks.com/ 

community. 

d) Specify the default reference mode to apply to nodes after they are branched. To 

understand the differences between reference modes, see “Reference Modes” on 

page 102. 

109


110 


page 143): 

Type=Requirement_Document 

Shared Category=Document 

12 Define additional type attributes using the tree pane, see the following sections for 








13 Click OK to finish creating the Segment type and its associated attributes. 

IMPORTANT If you have a node type referenced by a segment, you cannot change the 

document type of the node to shared item or segment. 

To edit the References field relationship to add the Requirement Document type 

1 From the Fields view (see “Fields” on page 121), select References > Edit. The Edit Field 


2 Click the Field Relationships node. 

3 In the Types box, select the Requirement node type add Requirement Document to the 

Allowed SubSegment Types list. 

If the segment allows more than one valid Shared Category, then you should set the 

MKS.RQ.Domain property to include additional categories. If the segment allows only one 

valid Shared Category, for example, the default Document you do not need to augment 

MKS.RQ.Domain property. 

To learn how about the MKS.RQ.Domain property, see the MKS Customer Community 


4 Click OK. 

This section of the procedure is optional to add Shared Category pick values and make them 

meaningful or non meaningful: 

1 From the Fields view (see “Fields” on page 121), select Shared Category > Edit. The Edit 

Field dialog box displays. 

2 Click Add. The Add Pick dialog box displays.

3 Type a Label for the Shared Category value you want to add. 

4 Select meaningful or non-meaningful from the list. 

5 Define images as applicable (“Editing Fields” on page 140). 

6 Click OK twice. 

To learn how to create a trace relationship field, see the MKS Customer Community 


7 Click OK to finish creating your document model. 

After you have created your document domain, you need to make the Document and 

Content menus visible to users. To learn how to activate menus on ViewSet, see “Updating 

Published ViewSets” on page 64. When a user selects Document > Create, the categories 

become visible in the Document view. 

Types 

You may want to limit the categories associated with the shared item (field relationships) to a 

list applicable to your application. 

You can configure additional type attributes, for example, define document items to be a part 

of test management. See “Setting the Test Management Role for Types” on page 112. 

To see how the document types you created translate to the structure of a document that 

users create and modify, see your MKS Integrity 2009 User Guide. 

Defining the Format of Printed Documents 

You can define the printed output users will see when they print documents by creating a 

report and defining it on the Segment type. Reports can only be set on segment types and a 

segment type does not require a print report definition. 

The ALM template ships with sample reports. To learn more about what those reports are, 

and where you can find them, see the MKS Customer Community Knowledge Base found at 

http://www.mks.com/community. 

To define a print report format for a Segment type in the GUI 

1 Create a report to use with segment types using the report feature. To learn how to use 

the report feature, see your MKS Integrity 2009 User Guide. 

NOTE A sample report is available if you are using documents in an ALM template 

environment. To locate the sample report, the MKS Customer Community 


111


112 

2 From the Create Type or Edit Type panel, with the Segment mode button enabled, 

choose a report from the Print Report pick list. 

Any administration report can be used for printing a document. However, MKS 

recommends you use the Document Content report that is included with the ALM 

template. 

To learn more about the ALM template, see the MKS Customer Community Knowledge 

Base found at http://www.mks.com/community. 

3 Complete the rest of the panel depending on the document model definition you require. 

4 Click OK. The report is attached to the segment for this Document type. 

When a user selects Document > Print in the Document view, the document prints 

using the report specified for the segment. If no report is defined and the user prints 

using this method, the table on the right is sent to the printer. 

When a document is selected in the Item view and a user selects View > Print, you are 

presented with an option to print Selected Document. This option only exists if an 

item type is a document segment and there is a print report associated with the type. 

NOTE Multiple document printing is not supported in MKS Integrity 2009. If 

multiple documents are selected in the Item view, this option is disabled. 

To learn more about item printing options, see MKS Integrity 2009 User Guide. 

Setting the Test Management Role for Types 

If you are using MKS Integrity for test management, you can specify the role that the type has 

in the test management process. 

To set test management roles for types in the GUI 

1 From the Create Type, Copy Type, or Edit Type dialog box, click the Test Management 

node. (For more information on the dialog box, see “Creating Types” on page 84, 

“Copying Types” on page 92, or “Editing Types” on page 91.) 

2 Specify whether this item type can be related to test results. For example, you might 

want a defect item type to be able to be related to a test result. 

3 Select one of the following test management roles for the item type: 

None 

The item type does not have a role specific to test management. 

Test Suite 

A test suite is a grouping of test cases. Typically, tests are authored in test suites. Test 

suites can vary from small groupings that test an individual feature, to large

Types 

groupings that test an entire product or perform stress or load testing. Test suites 

can contain other test suites. Test suites must have a document model of Segment 

since test suites are containers of content. For more information on the document 

model, see “Setting Up Documents” on page 97. 

If you select this role, proceed to step 7. 

Test Case 

A test case describes the test conditions and provides a container for adding test 

results from the test session. Test cases can be specified for different types of tests, 

including functional, performance, automated, or manual tests. Test cases must 

have a document model of Node since test cases provide the content for test suite or 

test group documents. For more information on the document model, see “Setting 

Up Documents” on page 97. 


Test Step 

A test step is a specific testing operations performed as part of a executing a test case. 

A test case contains an ordered list of steps to follow in order to complete the test. 

Test steps can be shared across test cases. Test steps must have a document model of 

None. For more information on the document model, see “Setting Up Documents” 

on page 97. 


Test Session 

A test session is a concrete run or execution of a group of test cases. The group of 

tests to be run can be based on a test suite or test group. During the test session each 

test suite or test group is executed, (which in turn means that each test case in each 

of the test suites or test groups is executed) and test results are collected. Test 

sessions must have a document model of None. For more information on the 

document model, see “Setting Up Documents” on page 97. 

4 Specify who is able to modify the test results for the test session: 

Anyone 

The user in the specified User Field on the test session. 

Any user in the group in the specified Group Field on the test session. 

Any user in the specified Groups. 

Proceed to step 7. 

5 Select Test Steps will be enabled on items of this type if you want test steps to display on 

the test case. A test step is a specific test for a test case. A test case can contain an ordered 

list of steps to follow in order to complete the test. Test steps can be shared across test 

cases. 

6 Specify the Fields on the test case that you want to display in the Test Results view. 

113


114 

7 Click OK. 

For more information on using MKS Integrity for test management, see the MKS Customer 

Community Knowledge Base found at http://www.mks.com/community. 

Setting Item Editability for Types 

You can define the conditions that give users permission to edit items of a specific type. 

To define item editability for a type in the GUI 

CLI EQUIVALENT im createtype, im copytype, or im edittype 

1 From the Create Type, Copy Type, or Edit Type dialog box, click the Item Editability 

node. (For more information on the dialog box, see “Creating Types” on page 84, 

“Copying Types” on page 92, or “Editing Types” on page 91.) The Item Editability panel 

displays. 


Under Condition, define the conditions this type should be editable under. 

For information on the available operators and rule structure, see “Defining Rules” 

on page 43. For information on using the data filter, see “Filtering Data” on page 18. 

Under Copy, do one of the following: 

Click Add to copy editability rules from another type. The copied rules are 

appended to any existing rules. 

Click Replace to copy editability rules from another type to replace any existing 

rules. 

The Rule Selection dialog box displays. 

In the Objects with Rules list, select the type that you want to copy a rule from. 

If the type has a rule, that type displays in the Preview area. 

Click OK. The rule displays in the Editability panel. 

3 Click OK to save the item editability rule(s) for the type. 

Setting Type Visibility 

Type visibility allows you to control access to information throughout your organization. 

Through MKS Integrity, you can manage the types that reflect your product development. 

You can use type visibility to ensure that sensitive information from one group is not viewed

or modified by another group. All items and e-mail notification are subject to type visibility 

rules. 

Types 

When you create a type, you can select which user groups can see the type and all items 

assigned to the project. You can also define which user groups can see all types in the 

database and which ones are restricted to see only certain types. If a user is not a member of 

at least one group allowed to view the type, that user cannot view any items of that type. 

Based on type visibility, users are allowed to query the database only for items of the types 

that are visible to them. Items of types not visible to users are not displayed in the query 

results. If users try to view an item of a type that is not visible to them, an error message 

displays. 

If an item in one project is related to an item in a project not visible to the user, the related 

item does not display in the Relationship view. In the History view, the user can see only that 

an edit occurred (Modified by on ). Users do not see the related item 

ID, and cannot see if the edit was an addition or removal of a related item. 

If an item, previously invisible to users, is reassigned to a type that is visible to users, they do 

not see the previous type name in the History view. Instead, a symbolic “Restricted Type” 

value displays. 

Setting Type Overrides 

Type overrides allow you to set certain attribute values that apply only for the selected type. 

MKS Integrity allows two varieties of type overrides: overrides for fields and overrides for 

states. Overrides for fields and states can be set while editing a type. 

When you set a type override, you are effectively customizing the applicable field or state 

attribute to suit the type(s) you administer. MKS Integrity then applies the new attribute 

value only for the type you are editing. The customized value supersedes the global settings 

for the target attribute when referenced by the selected type. 

NOTE Type overrides can also be set through the CLI using the im editfield and 

im editstate commands. For more information, see the MKS Integrity Server 2009 


Overrides for Fields 

Once a type is created, you can set overrides for certain field attributes. Overrides can be set 

for all fields referenced by that type; however, only the following field attributes are available 

for override: 

Relevance 

Editability 

Description 

115


116 

Ranges 

Phases 

Display pattern 

Default value 

Parameter substitution 

Overriding field relevance allows you to define, for the selected type, specific conditions that 

make a field applicable to users, groups, or items with certain field values. For example, if the 

global setting meant that the selected field was generally relevant and you wanted to 

simplify the information presented for the majority of users, you could set an override that 

made the field relevant only to the primary users of the selected type. For more information 

on the relevance attribute, see “Setting Field Relevance” on page 133. 

Overriding the field’s editability allows you to define, for the selected type, the conditions 

where users have permission to edit a field. For example, if the global setting means that the 

selected field is generally editable and you want to simplify the tasks required for the 

majority of users, you could set an override that makes the field editable only by the primary 

users of the selected type. For more information on the editability attribute, see “Setting Field 

Editability” on page 135. 

Overriding the field description allows you to customize the description that MKS Integrity 

uses for the type you are administering. This new description supersedes the global 

description for the selected field and is applied only when the field is referenced by the 

selected type. For example, the global description for the Submit field might be “Initial 

stage“. When referenced by the Feature Request type, you could set this description to 

“Feature request submission“. For more information on the description attribute, see 

“Setting Field Description” on page 137. 

Overriding the field default value allows you to have multiple types share a field with 

different field defaults for each type. For example, if you shared the Assigned Group field 

across multiple types, you could override the default Assigned Group field value and replace 

it with a new default field value for the type, or just remove the existing default. 

To set a type override for fields 



2 Select Type > Edit. The Edit Type dialog box displays. 

3 In the tree pane, select the Override for Fields node. The display pane shows the 

fields referenced by the selected type. A checkmark indicates the attribute has been 

overridden.

Column headers display the field attributes that are available for override, including 

Description, Relevance, Editability, Ranges, Display Pattern, and Phases. 

4 To set an override for a field, highlight the field in the list, and click Edit. The Edit Field 

Overrides For Type dialog box displays. 

TIP To view the existing overrides for a field, highlight the field, and click View. 

If the Override the global rule option is not selected, an editable attribute displays the 

global value. A checkmark in the tab indicates an override. You can set the following 

overrides: 

Types 

To set an override for a numeric field’s global display pattern, click the Values tab (if 

not already displayed), select the Override the global display pattern option, and 

make the required changes. For more information on display patterns, see “Display 

Patterns” on page 28. 

To set an override for global range values, click the Values tab (if not already 

displayed), select the Override the global range values option, and make the 

required changes. For more information on ranges, see “Range Fields” on page 130. 

To set an override for global phases, click the Values tab (if not already displayed), 

select the Override the global phases option, and make the required changes. For 

more information on phases, see “Phase Fields” on page 130. 

To set an override for the default value, click the Values tab (if not already 

displayed), select the Override the default value option, and change the Set Default 

Value option. If the field is an integer, float, or date field, you can also change the Set 

Minimum Value and Set Maximum Value options. If you do not want to use a default 

or minimum/maximum value for the type, disable Override the default value. 

To set an override for parameter substitution in a text field, click the Values tab (if 

not already displayed), select Override "Substitute Parameters" Value and change 

the Substitute Parameters option. When parameter substitution is not enabled for a 

field, you see parameter entries in the following format: {{}}. 

When parameter substitution is enabled for a field, the parameter name is replace 

with a parameter value when you view the item through a view or report that 

supports parameter substitution. 

To set an override for default columns in a relationship field, click the Default 

Columns tab, select the Override the global default columns option, and make the 

required changes. For more information on setting default columns, see “Specifying 

Default Columns” on page 133. 

To set an override for the relevance attribute, click the Relevance tab, select the 

Override the global rule option, and make the required changes. For more 

information on the relevance attribute, see “Setting Field Relevance” on page 133. 

117


118 

To set an override for the editability attribute, click the Editability tab, select the 

Override the global rule option, and make the required changes. For more 

information on the editability attribute, see “Setting Field Editability” on page 135. 

To set an override for the description attribute, click the Description tab, and select 

the Override the global description option. In the text field, type the text description 

you want to apply to this field only when referenced by this type. 

NOTE 

To view the existing sequence of fields referenced by this type, click the Position 

tab. The list of fields displays. 

To view the administrative changes made to fields referenced by this type, click 

the History tab. A list of administrative changes, if any, displays. 

Position and History information is for information purposes only and is not 

editable. 

5 When you are finished setting the overrides, click OK. 

Overrides for States 

Once a type is created, you can set overrides for certain state attributes. Overrides can be set 

for all states referenced by that type; however, only the following state attributes are 

available for override: 

Description 

Image 

Capabilities 

Overriding the attribute allows you to set a unique description, image, or capability that 

supersedes the global setting used by MKS Integrity. The override you set is then used by 

MKS Integrity only when that state is referenced by the selected type. For example, for the 

Build state, the state capability rule does not allow open change packages. However, you 

could set an override that allowed open change packages in the Build state only when 

referenced by the Web Development type. 

For more information on state attributes, see “Creating States” on page 78. 

To set a type override for states 



2 Select Type > Edit. The Edit Type dialog box displays.

3 In the tree pane, select the Overrides for States node. The display pane shows the 

states referenced by the selected type. A checkmark indicates the attributes have been 

overridden. 

Column headers display the state attributes that are available for override, including 

Description, Image, and Capabilities. 

4 To set an override for a state, highlight the state in the list, and click Edit. The Edit State 

Overrides For Type dialog box displays. 

If the Override the global rule option is not selected, an editable attribute displays the 

global value. A checkmark in the tab indicates an override. 

TIP To view the existing overrides for a state, highlight the state, and click View. 

Types 

5 To set an override for the description attribute, click the Description tab, and select the 

for Override the global description option. In the text field, type the text description you 

want to apply to this state only when referenced by this type. 

6 To view the existing sequence of states referenced by this type, click the Position tab. The 

list of states displays. Details displayed under the Position tab is for information 

purposes only and cannot be edited. 

7 To set an override for the image attribute, click the Image tab, select the Override the 

global image option, and make the required changes in the image selection. 

You can associate a custom icon image with the state. To do this, select Use Custom 

Image, and browse for the image file. To have no image associated with the type, select 

No Image. If you choose to use your own custom icon image, the image must be in GIF or 

JPEG format, and no larger than 24 x 16 pixels. 

8 To view the administrative changes made to states referenced by this type, click the 

History tab. A list of administrative changes, if any, displays. Details displayed under the 

History tab is for information purposes only and cannot be edited. 

9 To set an override for the state capability attribute, click the Capabilities tab, select the 

Override global capabilities option, and make the required changes to define state-based 

capabilities. In MKS Integrity, state-based capabilities allow time entries to exist while an 

item is in a given state. For more information on creating, editing, viewing, and deleting 

time entries, see the MKS Integrity 2009 User Guide. 

In MKS Integrity, state-based capabilities allow change packages that are under review 

or change packages that are open to exist while an item is in a given state. For more 

information on the change package review and approval process, see the MKS Integrity 

2009 User Guide. 

If the item state does not allow open change packages, MKS Integrity prompts users to 

close the item’s change package before they move any item to that state. In addition, if an 

119


120 

item state does not allow open change packages, users cannot create new change 

packages for any items in that state. 

To define a state-based capability, do one of the following: 

To display only enabled state-based capabilities, from the Filter list select 

. 

To display all available state-based capabilities, from the Filter list select . 

To display only the state-based capabilities related to MKS Integrity, select 

MKS Integrity. Then to allow time entries in the selected state, enable the Allows 

time entry in this state option. 

To display only the state-based capabilities related to MKS Integrity, select 

MKS Integrity.Then select one or more of the following capabilities: 

To allow change packages under review in the selected state, enable the Allows 

SI change packages under review to exist in this state option. 

To allow open change packages in the selected state, enable the Allows open SI 

change packages to exist option. 

NOTE If you are using the Implementer integration with MKS Integrity, additional 

state-based capabilities are available. 

10 When you are finished setting the overrides, click OK. 

Setting Field Visibility for Types 

When you create a type, you can select which groups can see the fields and the values within 

the fields. Field visibility, based on the type definition, allows you to control access to 

information within an item. You can use field visibility to ensure that sensitive information 

from one group is not viewed or modified by another group. All items, attachments, and 

queries are subject to field visibility rules. 

If users do not have visibility for a field (in a specified type), they cannot: 

see the value(s) assigned to that field for an item of the specified type 

use queries to search on fields that are not visible to them 

IMPORTANT In the Create Query dialog box, users are able to see the field name. If 

the field is a picklist, users are able to see all possible values within the field. 

The standard fields Type, ID, Created By, Created Date, Modified By, and Modified Date are not 

subject to field visibility rules and are always visible for all item types. Other standard fields 

are always visible for specific types, based on their document model or test role. Fields that 

are always visible are displayed with a gray checkmark.

Fields 

Field visibility applies to the Fields, History, Attachments, and Relationships sections in an 

item. In addition, because queries are subject to field visibility, reports and charts do not 

include data from invisible fields. 

NOTE Field visibility is not field relevance. Relevance allows you to create subsets of 

information that make it easier for users to create and edit items. Field visibility is a 

security mechanism that restricts user access to information in MKS Integrity. For 

more information on relevance, see “Setting Field Relevance” on page 133. 

Fields 

MKS Integrity comes with a standard set of default fields that are visible to all item types and 

all users. Fields are categories of data that can be associated with items. You can also create 

custom fields in MKS Integrity. 

When naming a field, MKS Integrity also allows you to use a secondary name to be displayed 

on the interface. This secondary name, known as the display name, can be helpful in 

simplifying information presented to the user. For more information, see “Using Display 

Names” on page 126. 

Any changes you make within the Fields dialog box are implemented in the database 

immediately; you cannot cancel them. If you create a field with an incorrect type, you cannot 

change its type. You can remedy the problem by renaming the field, making it invisible for all 

types, or deleting it if there are no references (see “Deleting Fields” on page 142). 

NOTE There are special considerations if you rename a default field that is 

referenced in an item type property. Item type properties are used to define 

solution-specific behavior. For more information, see the ALM section of the MKS 

Customer Community Knowledge Base found at http://www.mks.com/ 

community. 

Several of the default fields are used specifically in the document model structure. To learn 

more about the architecture of the document model, see the ALM section of the MKS 


Standard MKS Integrity fields that you can include in your workflow are as follows: 

Field Name Editable? Description 

Assigned User Yes User responsible for item. 

Assigned Group Yes Group responsible for item. 

Attachment Yes Attachment(s) included with the item. For more 

information about creating attachments in items, see your 


121


122 


Backward Relationships Yes Related parent items. For more information on item 

relationships, see the MKS Integrity 2009 User Guide. 

Category Yes FVA field that displays the value from the Shared 

Category field in a node item. 

For more information about item types in the document 

model, “Types” on page 82. 

Contained By No Describes the linkage from child to parent and defines the 

contents and structure of a document. 



Contains No Describes the linkage from parent to child and defines 

the contents and structure of a document. 



Created By No User who created item. 

Created Date No Date item was created. 

Subdocument Name No Name of the document item name that references the 

segment. The subdocument name is derived from the 

Summary field on the referencing node. You can edit 

Summary directly on a node or a segment. 



Document ID No ID of the document item in which content is contained. 



Forward Relationships Yes Related child items. For more information on item 

relationships, see the MKS Integrity 2009 User Guide. 

ID No Unique ID assigned to each item upon creation. 

Input Revision Date Yes Date of the last significant modification to this document 

item or, if a node, to the shared item that backs it. 

Modified By No User who last modified item. 

Modified Date No Date item was last changed. 

Notes Yes Special notes about the item. 

Parameters Yes Lists the valid parameters for an item. For more information, 

see “Using Parameters and Parameter Values Fields” on 

page 138. 

Parameter Values Yes Specifies the values for the parameters. For more 

information, see “Using Parameters and Parameter Values 

Fields” on page 138.


Project No Project item belongs to. Projects are groupings of related 

items. 

Referenced By No Describes the linkage from shared item to node, or document 

root to node. 



Referenced Item Type Yes Shared item type as exposed through the node 

reference. 



Reference Mode No Controls how document items are versioned, branched, and 

reused. 

References No Describes the linkage from node to shared item, or node to 

document root. 

Root ID No ID of the original ancestor of a document item. Same as 

the item ID if an original artifact. 

Shared By No Establishes an explicit sharing linkage between two node 

items. 

Node items participating in a Shares/Shared By 

relationship always point to the same shared item. 

Edits to shared node fields also appear on the items 

listed. 

For more information on nodes and shared items, see 

“Setting Up Documents” on page 97. 

Shared Category Yes Defines the type of document or shared item. Values are 

constrained by field relationships. 



Note: Shared Category fields are always mandatory. 

Shared Test Steps Yes Related test steps for a test case. Test steps are items with a 

test management role of Test Step. For more information, 

see “Setting the Test Management Role for Types” on 

page 112. 

A test step shared with another test case cannot be edited, 

but it can be copied and replaced with the new version. 

Shares No Establishes an explicit sharing linkage between two node 

items. 

Node items participating in a Shares/Shared By 

relationship always point to the same shared item. 

Shared node fields can only be edited on the item listed. 

For more information on nodes and shared items, see 

“Setting Up Documents” on page 97. 

Fields 

123


124 


Signature Comment No Any comments entered as part of electronic signature. 

For more information, see “Setting Up Electronic 

Signatures” on page 241. 

Signed By No User who provided electronic signature when item was 

changed. For more information, see “Setting Up 

Electronic Signatures” on page 241. 

State Yes Step or stage of workflow process. 

Summary Yes Brief summary of item, up to 250 alphanumeric 

characters. 

Tests As Of Date Yes Date on test session that determines which test cases 

display for test documents in the test result editor. Test 

cases added to test documents after this date are not 

displayed. 

Test Cases Yes Related test cases that shared test steps belong to. 

Tests Yes Related test documents or test cases. When you add a 

related item to this field, a dialog box displays, allowing 

you to select a test document, or select individual test 

cases from a test document. 

Note: You cannot create new items to add as related 

items. 

Test documents can be test suite or test group 

documents. Test suites have a document model of 

Segment and a test management role of Test Suite. 

Test group documents have a document model of 

Segment and a segment setting of Group Document. 

Test cases have a document node of Node and a test 

management role of Test Case. 

For more information on the document model, see 

“Setting Up Documents” on page 97. For more 

information about test management roles, see “Setting 

the Test Management Role for Types” on page 112. 

Tests For Yes Related item that the test document or test case belongs to. 

Test Steps No FVA field that displays information from the Shared Test 

Steps field in a related test case. 

Type No Item type that pertains to particular workflow. 


MKS Integrity comes with a set of standard fields that are visible to all item types and all 

users. 

Field visibility rules based on item type are defined when creating a type. For more 

information, see “Setting Field Visibility for Types” on page 120.

When naming a field, MKS Integrity allows you to use a secondary name (the display 

name) that appears on the GUI. 

Working in Fields View 

Using the MKS Integrity Administration Client, you can manage fields from one convenient 

location. Managing fields is carried out through the Fields view. 

CLI EQUIVALENT im fields 

To open the Fields view from the MKS Integrity Administration Client, expand the 

Workflows and Documents node, and select Fields. The Fields view displays. 

By default, the data filter in the Fields view displays all existing fields. You can search for a 

specific field by typing in the text filter and/or using the following filters: 

Filter Description 

visible in item type Displays fields visible in the specified item type. 

visible in all item types Displays fields common to all types. 

of field type Displays specific field types. 

For more information on using the data filter, see “Filtering Data” on page 18. 

Fields 

MKS Integrity has a standard set of default fields that are visible to all users for all item types. 

Fields are categories of data that can be associated with items. You can also create custom 

fields in MKS Integrity. 

NOTE Field visibility rules based on item type are defined when creating a type. For 

more information, see “Setting Field Visibility for Types” on page 120. 

Any changes you make in the Fields view have an immediate effect on your MKS Integrity 

database. For general information on the MKS Integrity Administration Client, see 

“Introduction” on page 10. 

Through the Fields view, you can: 

edit the details for an existing field 

view the details for an existing field 

create a new field 

reposition, or change the order of presentation for a field 

delete an existing field 

125


126 

Any changes you make within the Fields dialog box are implemented in the database 

immediately; you cannot cancel them. If you create a field with an incorrect type, you cannot 

delete it or change its type or definition. You can either rename it or make it invisible for all 

types. 

Using Display Names 

NOTE Certain standard fields are always visible and cannot be edited. For these 

standard fields, only the Description and Position panels appear. The standard 

fields are: ID, Modified By, Created By, Modified Date, and Created Date. You can 

provide a description for each standard field. 

When naming a field, MKS Integrity also allows you to use a secondary name that can be 

displayed to the user on the interface. This secondary name, known as the display name, is the 

field title that users see when working with MKS Integrity. Therefore, the field name is the 

name used by MKS Integrity to identify the field, and the display name is the text displayed 

to the user. 

When naming a field, MKS Integrity automatically enters the same selected name in the 

Display Name field; however, you can choose a different name to use as the display name. 

Display names are useful for clarifying the terminology presented to users on the interface. 

For example, you may want to use acronyms or short forms when naming your fields, but 

then provide the full text name as the field title that is presented to users, such as a field name 

Mgr with a display name Manager. You could also use display names to simplify titles, such 

as a field name Created Date with a display name Created On. 

NOTE Display names are not intended as a method for translating or localizing 

information presented on the interface. 

To avoid confusion for users, display names must be unique for fields referenced within a 

single type. Fields referenced across multiple types do not need to have unique display 

names. For non-unique display names referenced across multiple types, MKS Integrity 

appends detailed information or displays tooltips to help the user identify the field. 

In the presentation template designer, display names are also used by default for the titles of 

fields that you insert into your custom template. For more information on working with 

custom presentation templates, see “Customizing Item Presentation” on page 188. 

TIP To view the column for display names from the GUI, right click the column 

header, and select Display Names from the shortcut menu.

Creating Fields 

Fields 

MKS Integrity is installed with a set of default fields, and you can also create custom fields to 

suit your work process. Default fields cannot be deleted. 

IMPORTANT When creating custom fields used in item types, custom indexes may 

need to be created for your database. Contact your Database Administrator (DBA) 

for assistance. 

You can create the following types of fields. 

Field Type Description 

Attachment For including attachments, such as design documents. 

Note: You can create relevance and editability rules on 

attachment fields; however, you cannot include attachment 

fields in the definition of a rule. 

Integer For simple, countable items, such as call tracking numbers. 

Item Backed Picklist (IBPL) For displaying values from one or more items in a picklist. For 

more information, see “Item Backed Picklist Fields” on 

page 129 

Field Value Attribute (FVA) For sharing field information from a linked item. For more 

information, see “Field Value Attribute Fields” on page 129 

Picklist Specifies items that should display in a drop-down list, such as 

predefined product codes. You can also choose an option that 

allows users to select multiple picklist values. 

Note: Once you use a picklist value, that value cannot be used 

again, even if you delete the pick field that is associated with it. 

Similarly, you cannot change the picklist value once you have 

set it. 

Floating Point For numbers with decimals, such as performance data. 

Logical For Boolean items (ones that are either true or false), such as 

whether an item has been tested. 

Date For dates, such as when a defect was fixed. Optionally, you 

can include the time. 

Short Text For miscellaneous information, such as a comment field. You 

can define suggestions to appear in this field. 

Long Text For miscellaneous information. You can display information in 

this field in rows. 

User For users that display in a drop-down list, such as users in a 

specific group. 

Group Fields For groups that display in a drop-down list, such as groups 

assigned to a specific project. 

127


128 

Field Type Description 

Relationship Fields Relationship fields enable you to link one item to another. 

For more information, see “Relationship Fields” on page 128. 

Trace Relationship Fields Trace relationship fields enable you to create trace 

relationships between two items in the document model. 

Phase For categorizing groups of states in a workflow. For more 

information, see “If an FVA field is backed by a text field with 

parameter substitution, when you view the item through a view 

or report that supports parameter substitution, the substituted 

values from the item containing the backing field are displayed 

in the FVA field on the current item. For more information, see 

“Using Parameters and Parameter Values Fields” on 

page 138.” on page 130. 

Query Backed Relationship For displaying a large number of related items in a read-only 

relationships field, based on a query. For example, the 

Features field in a Project item could display all the Feature 

items that are returned by the Release_5_Features query. 

Range For categorizing numeric value ranges in an associated 

numeric field (integer or floating point). For more information, 

see “Range Fields” on page 130. 

Relationship Fields 

You can create relationship fields to link items for reference purposes, such as linking 

duplicate items, or linking features and their defects. You can also create relationship fields to 

link items for the purposes of tracking and monitoring. For example, you can create a Sub 

Features relationship field on a Feature item type to link a master feature to a group of 

secondary features, which in turn can have relationship fields that link to defect and 

documentation items. Users can then track the overall development progress for a master 

feature by reviewing its hierarchy of related items using the Relationships view. For more 

information on the Relationships view, see the MKS Integrity 2009 User Guide. 

Every relationship consists of a pair of relationship fields: one for the forward relationship 

and one for the backward relationship. Forward relationships are relationships where the 

related item is a child of the original item. Backward relationships are relationships where the 

related item is a parent of the original item. For example, you could create a forward 

relationship field named Sub Features to link master features to their sub features, and a 

backward relationship field named Master Feature to link sub features to their master feature. 

Users can create a relationship from either the child or the parent, and the corresponding 

field in the related item is updated automatically. 

To learn how to define a relationships field as a trace for use in document types, see the last 

section of “Creating Document Types” on page 104.

Item Backed Picklist Fields 

Fields 

An item backed picklist (IBPL) field displays the values of one or more fields from another 

item type as picklist values. The item type that the values are based on is known as the 

backing item type. Whenever a value in one of the fields is updated in a backing item, all items 

with IBPL fields that reference that value are updated to reflect the new value. 

For example, if you create an IBPL field named Documentation on the Defect item type, 

backed by the ID field on the Documentation item type, ID field values in all Documentation 

items appear as pick text in the Documentation IBPL field in Defect items. If you wanted to 

show more information in the pick text, the Documentation field could be backed by the 

Project and Summary field as well as the ID field. The values from these fields would be 

combined to form more descriptive picklist values. 

Only values from active backing items are displayed in IBPL fields. You determine the 

criteria for active items by specifying the active states, and by defining a filter for any 

additional criteria that you require. The item type, active states, and additional filter criteria 

are used together to filter the values that appear in the IBPL field. 

If a selected picklist value becomes inactive, it still displays in the IBPL field, unless you edit 

that field. 

Note the following: 

The name of the IBPL field cannot be the same as the referenced field in the backing item 

type. 

If a new or existing IBPL field is multi-valued, it cannot be used as a relationship for a 

Field Value Attribute (FVA) field. When creating an FVA field, the IBPL field does not 

appear in the relationship field. 

Field Value Attribute Fields 

If an item is related to another item through a single-valued relationship field or IBPL field, 

you can share information from the related item in an FVA field. For example, if Department 

items have a Manager field and a Phone Extension field, and Department items can be related 

to Defect items through a Manager IBPL field on the Defect, you can also create an FVA field 

on the Defect named Extension to Call that displays the phone number for the selected 

department manager. If you change the Phone Extension in the Department item, that change 

is reflected in the Defect item. 


You cannot create an FVA field backed by a range field that is based on a numerical field 

value attribute field. 

Users cannot edit an FVA field if it has no backing relationship. 

If you create an FVA rich content field, it can only access attachments from an FVA 

attachment field over the same relationship as the FVA rich content field. This keeps the 

text and image data together. If the rich content field is not an FVA field, it should use 

129


130 

non-FVA attachment fields. If you create a type with visible FVA and non-FVA rich 

content and attachment fields, MKS Integrity only displays attachment fields visible to 

the user in the GUI or Web interface. From the CLI, the user must know which 

attachment fields to use with rich content fields. 

If an FVA field is backed by a text field with parameter substitution, when you view the 

item through a view or report that supports parameter substitution, the substituted 

values from the item containing the backing field are displayed in the FVA field on the 

current item. For more information, see “Using Parameters and Parameter Values 

Fields” on page 138. 

Phase Fields 

Phases are useful for organizing an item type’s workflow if it contains a large number of 

states and provide users with a broad overview of an item’s status independent of the 

workflow. For example, a Feature type could have the following phases (states are in 

parentheses): 

Requirements (Draft 1, First Draft Signoff, ...) 

Design (Update Data Model, ...) 

Development (In Development, Unit Testing, ...) 

Testing (White Box Testing, Black Box Testing, Regression Testing, ...) 

Implementation (Planning, Implementation, ...) 

Post-Implementation Maintenance (Patch 1 In Progress, ...) 

You can create any number of phases for a phase field. States not grouped into a phase are 

referred to as out of phase states. When an item is in an out of phase state, the phase field 

displays Out of Phase. 

Range Fields 

A range field is a computed picklist field associated with a numeric field: range limits and the 

associated field are stored in the computation expression and the range category name and 

icon are stored in the database as picklist items. When a value is entered in the associated 

numeric field, the appropriate range category displays in the range field. Range fields are 

useful for defining thresholds for numeric data and providing a broad overview of that data. 

For example, if a Project type has an integer field called Critical Defects that displays the 

number of Defect items marked Critical, you could add a range field called Defect Status 

that displays one of the following range categories based on the number of items in the 

Critical Defects field: 

Golden ("Critical Defects" = 0) 

Acceptable (1

Fields 

You can also add visual indicators to a range field by using customized images for each range 

category or by using the item presentation template designer to render range fields 

differently for each range category. For example, in the Defect Status field you could render 

Golden as black text on a white background, Acceptable as blue text on a white 

background, Watch as black text on a yellow background, and Trouble as red text on a 

yellow background. 

NOTE 

You cannot specify different range category names and icons for types; however, 

you can specify different range limits for types. 

Range field values are automatically determined based on an associated numeric 

field. You cannot edit range fields in an Item Details view. 

Range fields cannot contain an associated field that includes a computed 

expression with an external information function. 

Range value limits can be overridden on a per type basis; however, you cannot 

override range category names and icons. 

SI Project Fields 

SI project fields allow users to specify a related configuration management project, optionally 

including a checkpoint revision or development path. By creating a configuration 

management project field and a computed field that uses the SIMetric() external 

information function, you can retrieve metrics about the specified project, for example, how 

many lines of code are in the project. For more information on creating configuration 

management project metrics, see “Using Configuration Management Project Metrics” on 

page 280. For more information on external information functions and computed fields, see 

“Computed Expressions” on page 291. 

IMPORTANT 

Metrics are only maintained against project checkpoints; therefore, to generate 

metrics users must specify a checkpoint when they specify the configuration 

management project. 

Configuration management project fields cannot be specified in any type of rule. 

To allow users to specify a related configuration management project when 

creating or editing an item, you must enable and properly configure the 

workflow and document, and configuration management integration. For more 

information, refer to the MKS Integrity Server 2009 Installation and Configuration 

Guide. You must restart the server for this change to take effect. 

To create a field in the GUI 

CLI EQUIVALENT im createfield 

1 From the Fields view (see “Fields” on page 121), select Field > Create. The Create Field 


131


132 

2 In the Name field, type a new name for the field. This is the name you use to refer to the 

field in MKS Integrity. The Name field allows 100 alphanumeric characters. 

In the Display Name field, MKS Integrity automatically enters the same selected name. 

Display names are the field titles that users see when working with MKS Integrity. 

You can choose a different name to use as the display name. Display names are useful 

for clarifying the terminology presented to users on the interface. For more information, 

see “Using Display Names” on page 126. 

3 On the Values panel, from the Data Type list select a data type for the field. When you 

select a data type, the values the field can accept display below. For more information, 

see the following. 

“Attachment Fields: Values Tab” on page 443 

“Integer Fields: Values Tab” on page 443 

“Item Backed Picklist Fields: Values Tab” on page 444 

“Field Value Attribute Fields: Values Tab” on page 444 

“Pick Fields: Values Tab” on page 445 

“Floating Point Fields: Values Tab” on page 445 

“Logical Data Fields: Values Tab” on page 446 

“Date Fields: Values Tab” on page 446 

“Short Text Fields: Values Tab” on page 447 

“Long Text Fields: Values Tab” on page 448 

“User Fields: Values Tab” on page 449 

“Group Fields: Values Tab” on page 450 

“Relationship Fields: Values Tab” on page 450 

“Phase Fields: Values Tab” on page 452 

“Query Backed Relationship Fields: Values Tab” on page 452 

“Range Fields: Values Tab” on page 453 

NOTE The Values panel is unavailable for standard fields, such as Type, ID, Created 

Date, Created By, Modified Date, and Modified By. 

4 Edit the field information as needed: 

To type a more detailed textual description of the field, such as the field’s purpose 

or what distinguishes this field from others, click the Description tab.

Fields 

To customize the order the fields display in, click the Position tab to display the 

Position panel, and use the Move Up and Move Down buttons to change the order in 

the list. This order is used throughout MKS Integrity. 

To specify default columns for relationship fields, click the Default Columns tab to 

display the Default Columns panel. For more information, see “Specifying Default 

Columns” on page 133. 

To set field relevance, click the Relevance tab. For more information, see “Setting 

Field Relevance” on page 133. 

To set field editability, click the Editability tab. For more information, see “Setting 

Field Editability” on page 135. 

To set field rules, click the Rules tab. For more information, see “Setting Field Rules” 

on page 137. 

5 When you are finished setting the field’s properties, click OK. 

Specifying Default Columns 

You can specify default columns for fields types Relationship and Query Backed 

Relationship. 

Use the Forward tab to specify the columns displayed on the forward relationship field and 

the Backward tab for the columns displayed on the backward relationship field. The 

customization of the two fields are independent of each other, but both can be specified from 

just one of the fields (you are not required to edit both fields). 

For information on filtering data to specify fields and the common interactors on the panel, 

see the MKS Integrity Client 2009 Getting Started Guide. 

Setting Field Relevance 

Relevance is a set of field conditions that determine which fields are relevant to selected 

groups of users or to specified field values. Fields that do not meet the relevance rules are not 

visible to users. 

You can define specific conditions that make a field relevant to selected groups of users or 

items with field values. Fields that do not meet relevance rules are not visible to users. 

Relevance allows you to create subsets of information that make it easier for users to create 

and edit items. 

Relevance uses logical conditions based on user groups and field values to make up a rule. 

These rules apply item by item and not by type definition. 

If you create a dynamic group related to a specific project, you can also choose to make a field 

relevant only to members of that group. 

Relevance is not a security mechanism for controlling access to information in MKS Integrity. 

For purposes of security, MKS Integrity includes project, type, and field visibility rules to 

133


134 

control user access to information. For more information on visibility rules, see “Setting 

Workflow and Document Project Visibility” on page 250, “Setting Type Visibility” on 

page 114, and “Setting Field Visibility for Types” on page 120. 

NOTE Relevance rules are evaluated on the MKS Integrity Client’s time zone. 

To define field relevance in the GUI 

CLI EQUIVALENT im createfield or im editfield 

NOTE Relevance does not apply for fields ID, Created Date, Created By, Modified 

Date, Modified By, and Type. 

1 From the Create Field or Edit Field dialog box, click the Relevance tab. For more 

information on the dialog box, see “Creating Fields” on page 127 or “Editing Fields” on 

page 140. The Relevance panel displays. 

2 To prevent the field from being displayed, enable Never Relevant. This option is useful if 

you want to hide read-only custom fields (that is, phase, range, computed) in Item Detail 

and Items views, but still be able to query on them. Enabling this option replaces any 

existing rules with false, removing all remaining options in the panel. If you enable this 

option, proceed directly to the final step of this procedure. 

3 Under Condition, define the conditions that make the selected field relevant to the 

selected user, groups, or field values. For more information, see “Defining Rules” on 

page 43.

4 Under Copy, copy relevance rules from another field. Do one of the following: 

Fields 

Click Add to copy relevance rules from another field. The copied rules are appended 

to any existing rules. 

NOTE If the field you are copying has a false relevance rule (never relevant), the 

rule does not appear. This means that a false relevance rule cannot be copied. 

Click Replace to copy relevance rules from another field to replace any existing 

rules. The Rule Selection dialog box displays. 

In the Objects with Rules list, select the field that you want to copy a rule from. If the 

field has a rule, that field displays in the Preview area. 

Click OK. The rule displays in the Relevance panel. 

5 Click OK to save the relevance rule(s). 

Setting Field Editability 

You can define the conditions that give users permission to edit a field. If you create a 

dynamic group related to a specific project, you can also choose to make a field editable only 

by members of that group. 


Editability rules are evaluated on the MKS Integrity Client’s time zone. 

Editability does not apply for fields ID, Created Date, Created By, Modified Date, Modified By, 

and Type. It also does not apply for phase, range, item backed picklist, query backed 

relationship, and computed fields. 

Editability rules cannot include a computed expression that requires an external 

information function. For more information on computed expressions, see “Computed 

Expressions” on page 291. 

To define field editability in the GUI 


1 From the Create Field or Edit Field dialog box, click the Editability tab. For more 


page 140. The Editability panel displays. 

135


136 

To prevent the field from being edited, enable Never Editable. This option is useful for 

fields that are updated by event triggers and are not meant to be edited by users. For 

example, you could create a date field where the date is automatically specified when the 

item enters a certain state. If you enable this option, proceed directly to the final step of 

this procedure. 

NOTE By default, this option is enabled for read-only custom fields (that is, phase, 

range, field value attribute (FVA), computed) and cannot be disabled. 

2 Under Condition, define the conditions this field should be editable under. For more 

information, see “Defining Rules” on page 43. 

3 Under Copy, do one of the following: 

Click Add to copy editability rules from another field. The copied rules are 

appended to any existing rules. 

If the field you are copying has a false editability rule (never editable), the rule 

does not appear. This means that a false editability rule cannot be copied. 

Click Replace to copy editability rules from another field to replace any existing 

rules. The Rule Selection dialog box displays. 

In the Objects with Rules list, select the field that you want to copy a rule from. If the 

field has a rule, that field displays in the Preview area.

Click OK. The rule displays in the Editability panel. 

NOTE If the field type is a phase, range, item backed picklist, query backed 

relationship, or computed field, a false rule automatically displays in the 

Editability panel. These field types display read-only values and cannot be edited. 

4 Click OK to save the editability rule(s). 

Setting Field Rules 

You can select and configure rules that control how a field works. You can select multiple 

rules for one field. Currently, rules are only available for relationship fields. 

To define a field rule in the GUI 


Fields 

1 From the Create Field or Edit Field dialog box, click the Rules tab. For more information 

on the dialog box, see “Creating Fields” on page 127 or “Editing Fields” on page 140. The 

Rules panel displays. 

2 Click New. The Rules Wizard dialog box displays. 

3 Type a name for the rule. 

4 Select a template to use for the rule. The rule description displays in the field below. 

5 Click a rule parameter (with links shown in blue) in the rule description. A dialog box 

displays, allowing you to set the value(s) for the parameter. 

Repeat this step until there are values set for all the required parameters in the rule. 

6 Click OK. The rule displays in the Rules tab. 

Setting Field Description 

You can specify a text description of a field. This description displays as a tooltip when users 

point to the field name in the GUI or Web interface. 

To specify a field description in the GUI 


1 From the Create Field or Edit Field dialog box, click the Description tab. For more 


page 140. The Description panel displays. 

2 Type a text description of the specified field. 


137


138 

Using Parameters and Parameter Values Fields 

Parameters are a special type of long text field. You can make the default fields visible on 

item types, but you cannot create new Parameters or Parameter Values fields. 

You use these fields to specify valid parameters and parameter values for an item type. Users 

can then specify the appropriate parameters for individual items. For more information on 

how users work with Parameters and Parameter Values fields, see the MKS Integrity 2009 

User Guide. 

Parameters allow you to reuse an item in different contexts by being able to specify unique 

item values for each context. Parameters are typically used in the requirements management 

and test management domains. For example, you could have a test case item with parameters 

that display different values for different test sessions. 

Example 

The ABC watch company produces a number of waterproof watch models. Each watch is 

tested underwater, but the depth requirement is different for each model. If the waterproof 

depth is a parameter value, then the same test can be used for each model, but the value of 

the depth parameter will change based on the model being tested. If there are multiple tests 

for the different amounts of time the watch should work underwater, making the depth a 

parameter also ensures that if the depth requirement for a model changes, all the tests for that 

model would use the new value. 

MKS Integrity determines what parameters can be specified and what parameter values are 

substituted in text fields based on items that are related to the item being edited or viewed. 

How MKS Integrity Determines Parameters and Parameter Values for an Item 

MKS Integrity uses the following process to determine the parameters and parameter values 

that display in a Parameter Values field when viewing an item, and that are substituted for 

parameter names in short and long text fields when viewing an item. 

MKS Integrity searches a hierarchy of items that are related to the current item. It searches for 

parameters and parameter values that are defined in the related item, or that are shared with 

the related item through a Field Value Attribute (FVA) field backed by a parameters or 

parameter values field. 

The following hierarchy of related items is considered when determining parameters and 

parameter values for an item: 

1 Shared parameters from a related project item. For example, the related project item has 

an FVA field that displays a parameter value from the application item. 

2 Parameters defined in the related project item. 

3 Shared parameters from a related test session item. 

4 Parameters defined in the related test session item.

5 Shared parameters from a related document content item linked through a Shares 

relationship. 

6 Parameters defined in a related document content item linked through a Shares 

relationship. 

Fields 

7 Shared parameters from the closest related document root item, for example, a test suite. 

8 Parameters defined in the closest related document root item. 

The next two steps only apply when substituting parameters in FVA fields backed by a 

text field with parameter substitution, or when substituting parameters in text fields for 

items in a relationship table field. 

9 Shared parameters from the item containing the backing field or from the item 

represented by the table row. 

10 Parameters defined in the item containing the backing field for an FVA field or in the 

item represented by the table row. 

11 Shared parameters on the current item. 

12 Parameters defined in the current item. 

Parameter values higher in the hierarchy are overridden by parameter values lower in the 

hierarchy, unless the parameter value is locked, in which case the value locked at the highest 

point in the hierarchy is used. If the relationship does not exist, MKS Integrity skips that step 

and continues down the hierarchy. 

Example 

NOTE If you change a parameter value in an item, and you have an item that is 

lower in the hierarchy open, you must refresh the view of the lower level item in 

order to see the updates. 

The ABC watch company produces a number of waterproof watch models. Each watch is 

tested underwater, but the depth requirement is different for each model. The waterproof 

depth is a parameter. 

If the following parameters and parameter values are defined: 

The project item for the new waterproof watches has a Depth parameter with a value of 

25 metres. 

The test suite for watch model A has a Depth parameter value with a value of 25 

metres. 

The test suite for watch model B had a value of of 10 metres. 

The test cases, which are shared across the test suites for watch models A and B, specify 

the depth parameter in a text field: {{Depth}}. 

139


Editing Fields 

140 

When viewing the test cases for the model A test suite, a value of 25 metres displays in the 

text field. 

When viewing the test cases for the model B test suite, a value of 10 metres displays in the 

text field. 

You can edit field details, including editability, relevance, description, and position. 

To edit a field in the GUI 

CLI EQUIVALENT im editfield 

1 From the Fields view (see “Fields” on page 121), select the field you want to edit. 

2 Select Field > Edit. The Edit Field dialog box displays. 

3 Edit the field information as needed. 

For more information about the fields and tabbed panels in this dialog box, see “To 

create a field in the GUI” on page 131. 

NOTE 

When editing the maximum length of a short text or long text field, decreasing 

the value does not truncate existing data or affect how data is displayed in the 

Items view. 

If you specify an inactive value for a user, group, or project field with a default 

value, the existing value is cleared when you relaunch the Edit Field dialog box. 

For multi-valued user and group fields, the entire field value is cleared even if 

you specify one inactive value. 

To view a history of administrative changes for the selected field, click the History 

tab. The record of changes displays. 

To determine which fields are referenced by any given type, click the Usage tab. The 

Usage panel shows what types refer to the field and what attributes have been 

overridden for that type. For types used in document model, the Usage panel shows 

which fields are significant and which ones are copied when a document is 

branched. To learn about document branching and significant fields, see “Setting 

Up Documents” on page 97. 

To determine all objects that reference the field, click the References tab. For 

information on the contents of the tab, see “To manage admin provided objects in 

the MKS Integrity Administration Client” on page 244. 

4 Click OK to save your changes.

Viewing Fields 

You can view detailed information for existing fields. You can only view the details for one 

field at a time. 

To view a field in the GUI 

CLI EQUIVALENT im viewfield 

1 From the Fields view (see “Fields” on page 121), select the field you want to view. 

2 Select Field > View. The View Field dialog box displays. For more information about the 

fields and tabbed panels in this dialog box, see “To create a field in the GUI” on 

page 131, and “To edit a field in the GUI” on page 140. 

NOTE You cannot change information that displays in a view mode. 


Deactivating Picklist Values 

Setting a picklist value to inactive means that in the GUI it is not displayed in any filtered 

picklists, such as Severity; however, an inactive picklist value can still be selected using the 

Select button in the Web interface and is denoted with the [Inactive] tag. 

Fields 

By deactivating picklist values, the picklist is filtered to display only those picklist values that 

are currently active in MKS Integrity. 


Inactive picklist values continue to display in fields, history, query filters, relevance and 

editability rules, field relationship filters, charts, and reports. 

Inactive picklist values can be selected in query filters, relevance and editability rules, 

field relationships, charts, and reports. 

Inactive picklist values cannot be selected in fields; however, fields retain inactive 

picklist values. If a user edits a multi-valued picklist, inactive picklist values are no 

longer valid selections, even if only one of the values was previously inactive. 

If one or more active picklist values are referenced in a trigger field assignment and you 

attempt to make one of those values inactive, an error message displays the picklist 

values and the trigger(s) where the assignment occurs. The references in the event 

trigger(s) must be removed before making a picklist value inactive. 

141


Deleting Fields 

142 

To deactivate a picklist value in the GUI 


1 From the Fields view (see “Working in Fields View” on page 125), select the pick field 

you want to edit. 

2 Select Fields > Edit. The Edit Field dialog box displays. 

3 Select the picklist value you want to deactivate, and click Edit. The Edit Pick dialog box 

displays. 

4 To deactivate the picklist value, clear the Active check box. 

5 To save the changes, click OK. The changes take effect immediately in the MKS Integrity 

database. Inactive picklist values are denoted by the [Inactive] tag. 

6 To save the pick field, click OK. 

You can delete fields, even if items have already been created that use that field. However, to 

delete a field, all objects must be edited so that they no longer contain references to that field. 

You can view references from the References tab when viewing a field (see “Viewing Fields” 

on page 141). For a list of objects that can reference a field, see “To manage admin provided 

objects in the MKS Integrity Administration Client” on page 244. 

You cannot delete a field that has historical references to that field in the history of one or 

more items. You must first delete the items that have entries for the field in their histories. 

CAUTION Deleting a field is permanent. That data cannot be restored after command 

completion. Ensure that you back up your database before deleting a field. 

IMPORTANT Deleting a field of the Relationship data type also deletes its partner 

field. By default, you are asked to confirm that the server delete the partner field. For 

more information on such fields, see “Managing Field Relationships” on page 143. 

To delete a field in the GUI 

CLI EQUIVALENT im deletefield 

1 From the Fields view (see “Working in Fields View” on page 125), select the field you 


2 View the field (see “Viewing Fields” on page 141), and examine the References tab to 

ensure that there are no references to the field.

Moving Fields 

3 Return to the Fields view, and with the field you are deleting selected, select Field > 

Delete. The Confirm Delete Field dialog box displays. 

4 To confirm field deletion, click Yes. 

You can customize the order fields display in. The order in the Fields dialog box is the order 

in MKS Integrity. 

To change the order of the fields in the GUI 


1 From the Fields view (see “Working in Fields View” on page 125), select Field > 

Reposition. The Reposition Fields dialog box displays. 

2 Select the field you want to move, and click Move Up or Move Down. 

3 Click OK. 

Managing Field Relationships 

Fields 

Once you have types and corresponding fields for your types, you can use field relationships 

to customize the display of data in an item further. Field relationships allow for a finer level 

of control by making the available selections in a given field dependent on the values selected 

in another field. Field relationships can be used to subset data for specific groups in your 

organization and minimize long lists of selections. 

NOTE You cannot create a relationship to a field value attribute data type. 

When creating a field relationship, you select a Source Field that controls what displays in the 

Target Field. The source field and target field are also assigned a corresponding value. Before 

reading about how field relationships work, you should note the following rules apply: 

Field relationships are subject to visibility rules. Visibility rules restrict access to specific 

information based on project or item type. For more information, see “Setting Field 

Visibility for Types” on page 120 and “Setting Workflow and Document Project 

Visibility” on page 250. 

Field relationships are based on Type, which means that you can only create 

relationships between fields that exist within a single Type in your workflow. 

143


144 

You can only use Type, State, Project, Assigned User, Assigned Group, custom User, 

custom Group, Boolean, or Picklist fields as source or target fields in a field relationship. 

NOTE If you are copying a type, Type is not available as a source or target field in a 

field relationship because the copied type has not been created yet. 

Field relationships can only be created on a one-to-one basis; one field is related to 

another field. However, you can select multiple values for a source or target field. You 

may also create many field relationships for the same source field to different target 

fields. 

When the target field is an item backed picklist (IBPL) field, the value selected in the 

source field controls which picklist values are displayed from the backing items. For 

these types of relationships, the source value is defined as a rule that compares the 

values between the value in the source field and the value for the same field in the items 

backing the IBPL target field. 

The following examples show how field relationships can be used in an organization: 

Source Field Target Field Function 

Project Assigned User or 

custom User 

State Assigned User or 

custom User 

Selection in Project field determines subset of user names in 

Assigned User or custom User field. Only users that work on 

selected project are available for selection. 

Selection in State field determines subset of user names in 

Assigned User, or custom User field. For example, a State - 

Assigned User field relationship ensures only users who are 

developers can be assigned item in state In Development. 

Assigned Group State Selection in Assigned Group field determines subset of states in 

State field. For example, if Assigned Group value is QA, only states 

that QA group members use are available for selection, such as In 

QA, Verified, and Failed QA. 

Assigned Group Assigned User or 

custom User 

Selection in Assigned Group field determines subset of user 

names in Assigned User or custom User field. Only users that are 

members of selected group are available for selection. If changes 

are made to membership of group, changes are dynamically 

updated throughout MKS Integrity.

Source Field Target Field Function 

Assigned Group Assigned User and 

State 

Access to field relationship functionality occurs in the Field Relationships view, which is 

contained in the Edit Type and Create Type dialog boxes. 

NOTE Because field relationships are based on Type, data must be sent to the server 

before any changes take effect. This means that once you have created, edited, or 

deleted field relationships, you must click OK on the Edit Type dialog box to send 

this information to the server. If you cancel the Edit Type dialog box, changes made 

to field relationships are lost. 

Fields 

In this view, you can customize the columns and sort order to organize the field relationships 

to suit your needs. For more information on customizing columns, see the MKS Integrity 

Client 2009 Getting Started Guide. 

To open the Field Relationships view in the GUI 


In this example, same source field (Assigned Group) has field 

relationship to two different targets. Selection in Assigned Group 

field determines subset of user names in Assigned User or custom 

User field, and also determines subset of states in State field. For 

example, if Assigned group is QA, then Assigned User must be 

member of group QA, and State can only be one that users in that 

group can use, such as In QA. 

Product Component In this example, the Component field is an item backed picklist field 

backed by the Component item type. You want the picklist values 

that come from the backing Component items to be filtered based 

on the value selected in the Product field. When you select a value 

in the Product field, only components items that have the same 

value in the product field are displayed. For example, if Product is 

Financial Toolkit then you could have Component picklist 

values such as Savings Manager and Amortization 

Calculator. 

1 From the Types view, select a type. The type you select here is the type the field 

relationship is based on. For more information on the Types view, see “Types” on 

page 82. 

2 Edit the selected type. The Edit Type dialog box displays. For information on editing 

types, see “Editing Types” on page 91. 

3 In the tree pane, select Field Relationships. The Field Relationships view displays. 

4 Use the Create, Edit, and Delete buttons to perform related tasks. 

145


146 

Creating Field Relationships 

To create a field relationship, you must have a type with fields already defined. You can only 

create one field relationship at a time. 

NOTE You cannot create or edit fields while creating a field relationship. 

To create a field relationship in the GUI 


1 From the Edit Type dialog box, in the tree pane select Field Relationships. For more 

information on the Edit Type dialog box, see “Editing Types” on page 91. 

2 Click Create. The Create a Field Relationship dialog box displays. 

3 From the Source Field list, select the field you want to control the other field. 

NOTE If you select Type as your source field, the only type available in the Source 

Values list is the one you selected when entering into the Edit Type dialog box. For 

more information, see “Editing Types” on page 91. 

4 From the Source Values list, select the corresponding value(s) for the Source Field. For 

example, if your source field is State, you can select one or more different state values, 

such as Unspecified, and Submit. If you select multiple values, then at least one of the 

values must be selected in the item field for the relationship to apply. 

If you select a user field from the Source Field list, a selection panel displays. For 

information on selecting users, see “Filtering Data” on page 18. 

5 From the Target Field list, select the field you want to specify values in. 

NOTE You cannot create a field relationship to a field value attribute (FVA).

6 Depending on your target field, do one of the following: 

Fields 

If you select Assigned User or any custom user field as the target field, proceed to 

step 7. 

If you select a field other than Assigned User or any custom user field as the target 

field, proceed directly to step 9. 

7 When you select Assigned User or any custom user field as the target field, a selection 

panel displays in the Static Values panel. For information on selecting users, see 

“Filtering Data” on page 18. You have the option to assign the value of this field to be 

populated based on a group (within the same realm), or select static values. 

To select a non-user value, see step 8. 

8 To assign the value based on a group, in the Dynamic Values panel do one of the 

following and proceed directly to step 9: 

Select Value Of, and the pane is populated with all visible group fields for the 

specified type. Select the Assigned Group or a custom group field from the active 

list. This selection populates the Assigned User or custom user field in the type 

definition with all users. However, when creating or editing an item, the values in a 

user field based on a group field are determined based on the users in the specified 

group. 

Select Member Of, and the pane is populated with all the valid groups. Select one or 

more groups from the active list. This selection populates the Assigned User or 

custom user field with all members in the specified group(s). 

NOTE If you select a dynamic group, it populates the Assigned User or custom 

user field in the type definition with all users. However, when creating or editing an 

item, the values in a user field based on a dynamic group are determined based on 

the current project for that item. 

147


148 

9 In the Static Values list, select the corresponding value(s) for the target field. For 

example, if your target field is Project, you can select one or more different project 

values. 

10 Click OK. The field relationship displays in the Field Relationships view. 

11 To save the field relationship, click OK on the Edit Type dialog box. 

To create a rule-based field relationship in the GUI 

You can only create a rule-based field relationship for item backed picklist (IBPL) fields. This 

rule determines which values appear in the picklist. 

NOTE For general information on rule nodes and conditions, see “Rule Format” on 

page 43. 

1 From the Edit Type dialog box, in the tree pane select Field Relationships. For more 

information on the Edit Type dialog box, see “Editing Types” on page 91. 

2 Click Create (Rule Based). The Create Rule Based Field Relationship dialog box displays.

NOTE The only IBPL fields that display in the Target Field are those that are made 

visible in the type. If none are made visible in visible fields, then none display in the 

Target Field. 

Fields 

3 In the Target Field section, select a field from the list of IBPL fields for the type. The rule 

you define controls the items that appear as picklist values in this field. 

4 Select And or Or, depending on the type of logical connector you want to use between 

conditions. 

NOTE If you are creating a rule with only one condition, you do not need to select 

And or Or. 

Swap replaces the selected node with the opposite node. For example, swapping an Or 

node replaces it with an And node. 


5 Under Condition, select the type of comparison used for the condition: 

Compare the value of a field with a constant 

This option filters IBPL values based on a comparison between a field in the backing 

items and a specific value. 

Compare the value of a field with the value of another field 

This option filters IBPL values based on a comparison between a field in the item 

being edited and a field in the backing items. 

Check a pre-condition associated with a document 

This option filters IBPL values based on conditions associated with components in 

the document model. 

149


150 

For more information, see the ALM section of the MKS Customer Community 


6 Define the condition by specifying fields, operators and values. 

The following types of fields cannot be used in conditions: attachment fields, text fields, 

relationship fields, or dynamic computation fields. 

If you select a date field, you must compare it to another date field. Refer to step 7 if you 

are comparing a date field to a constant. 

When defining a condition, you specify whether the field or value applies to the item 

containing the item backed picklist field (Editing Item Value) or to the items backing the 

item backed picklist field (Target Field). 

For example, if you are comparing the value of a field with a constant, and you want the 

IBPL field values filtered based on a specific value in the Project field of the backing 

items, you would do the following: 

Select Project as the first part of the rule and specify it as the Target Field 

Select = as the operator 

Select Financial Toolkit 2.0 from the list of product values 

Only backing items with a Project field containing Financial Toolkit 2.0 display as 

values in the IBPL field. 

For example, if you are comparing the value of a field with the value of another field, 

and you want the IBPL field values filtered based on matching the value in the Project 

field of the item containing the IBPL and the items backing the IBPL, you would do the 

following: 

Select Project as the first part of the rule and specify it as an Editing Item Value 

Select = as the operator 

Select Project as the second part of the rule and specify it as the Target Field 

Only backing items with a Project field containing the same value as the Project field on 

the item being edited display as values in the IBPL field. 

NOTE 

For more information on using the data filter to select fields, see “Filtering Data” 

on page 18. 

For more information on operators, see “When working with conditions, the 

meaning of the operator depends on whether the field you are using in the rule is 

single or multi valued.” on page 44. 

7 If you are comparing the value of a date field with a constant, click Change. The Specify 

Date or Time dialog box displays. Do one of the following:

Fields 

Select a date from the calendar. If the date field is configured to display the time and 

you want to include it, select the Show time option (if not already enabled) and 

include a time from the calendar. The Show time option is enabled by default. 

Select now to specify the current date and time. This option displays only if the date 

field is configured to display the date and time. 

Select today to specify the current date and a time of 00:00:00 (midnight). This 

option can be specified for a date field or a date field configured to display the date 

and time. 

Select none to specify an empty value for the date field. 

To save the specified value, click OK. 



9 When you have defined all your rules, click OK. The field relationship displays in the 

Field Relationships view. 


Editing Field Relationships 

To change the source and target fields or their values, you can edit a field relationship. You 

can only edit one field relationship at a time. 

NOTE You cannot create or edit fields while editing a field relationship. 

To edit a field relationship in the GUI 


1 From the Field Relationships view, select the field relationship you want to edit. For 

more information on the Field Relationships view, see “Managing Field Relationships” 

on page 143. 

2 Click Edit. The Edit a Field Relationship dialog box displays. The current field 

relationship settings display highlighted. 

3 Edit the field relationship as required. For more information on the lists in this dialog 

box, see “Creating Field Relationships” on page 146. 

4 Click OK. The field relationship displays in the Field Relationships view. 


151


Workflows 

152 

Deleting Field Relationships 

If a field relationship is no longer necessary, you can delete it. 

To delete a field relationship in the GUI 


1 From the Field Relationships view, select the field relationship you want to delete. For 

more information on the Field Relationships view, see “Managing Field Relationships” 

on page 143. 

2 Click Delete. The Delete Field Relationship dialog box confirms the operation. 

3 Click Yes to continue. The field relationship no longer displays in the Field Relationship 

view. 

4 To delete the field relationship, click OK on the Edit Type dialog box. 

Each item follows a workflow, the process established by your administrator to capture and 

track information during your software development cycle. Each item type can have its own 

set of states to advance through the development cycle. For example, a change request may 

go through states such as submitted, work started, tested, reviewed, and closed. Items and 

their current states provide change management information necessary to support business 

decisions. 

The Workflow view is a graphical depiction. You also use it to create a workflow for an item 

type. The Workflow view cannot be used to import users and groups or to create projects, 

types, and fields. Only one workflow for one type can be opened in the Workflow view. 

Access to workflow functionality occurs in the Workflow view, which is contained in both 

the Create Type and Edit Type dialog boxes. 

NOTE Because workflows are based on Type, data must be sent to the server before 

any changes take effect. This means that once you have created or edited workflows, 

you must click OK on the Edit Type (or Create Type) dialog box to send this 

information to the server. If you cancel the Edit Type (or Create Type) dialog box, 

you will lose your changes to the workflow. 

To open the Workflow view in the GUI 

1 From the Types view, select a type. The type you select here is the type that uses the new 

workflow. For more information on the Types view, see “Types” on page 82.

Workflow View 

Title Bar 

Menu Bar 

Tree Pane 

Workflows 

2 Edit the selected type. For information on editing types, see “Editing Types” on page 91. 

The Edit Type dialog box displays with the Workflow view in focus. 

The Workflow view allows you to edit the selected workflow in graphical mode using drag 

and drop gestures, and menu options. 

Title Bar 

The title bar displays the name of the type whose workflow is opened, and the server and 

port number for the MKS Integrity Server it resides on. 

Menu Bar 

The menu bar is located directly below the title bar and contains the menus: View, Edit, State, 

and Transition. 

Workflow 

Workflow Pane Groups/Mandatory Fields Box 

Available States Box 

The workflow is a graphical representation of the type’s workflow. The following items may 

be included in the workflow: 

153


154 

A filled box denotes the Unspecified state. The Unspecified state always displays in 

the workflow and cannot be deleted. 

A clear box denotes a named state in the workflow. The name of the state is centered 

within the box. You cannot manually control the position of states in the workflow. The 

position of states is determined by the direction of the layout and the state transitions to 

and from the state. 

Underneath the name of a state, a name in brackets denotes a named phase in the 

workflow. Phases are optional read-only fields that specify categorized groups of states 

in a workflow, essentially creating states (represented by phases) and sub-states 

(represented by states) for an item type. Phases are useful for organizing an item type’s 

workflow if it contains a large number of states and provide users with a broad overview 

of an item’s status independent of the workflow. 

An arrow denotes a state transition moving in a direction of the layout (see “Viewing 

Workflow” on page 157). 

A blue outline denotes the currently selected state(s) or state transition(s). You can only 

multi select states together or state transitions together. 

Available States Box 

In the Available states box, the State column lists all states that are not currently in the type’s 

workflow, but that can be dragged or inserted into the workflow. The Phase column lists all 

phases that correspond to states, if any. 

Groups/Mandatory Fields Box 

The contents of this box change based on what is selected in the workflow. Selecting at least 

one state transition displays the Groups box, which contains a list of the groups of users who 

are permitted to make state transitions for the item type. The checkmarked boxes denote 

groups of users who are able to make the transition(s) selected in the workflow. When 

multiple state transitions are selected, gray checkmarks denote that the group is allowed in at 

least one selected state transition, not all. 

Selecting at least one state displays the Mandatory Fields dialog box, which contains a list of 

the fields for the item type. The checkmarked boxes denote fields that must contain values 

before the user is permitted to advance to that state in the workflow. When multiple states 

are selected, gray checkmarks denote that the field is mandatory for at least one selected state 

but not all. 

User Preferences 

User preferences that are automatically saved for each user when closing the Workflow view 

include: 

zoom factor 

layout direction

window size and location 

Creating Workflow 

Workflows 

Before using the Workflow view to create a workflow, you must first set up the following 

items: 

users (see the MKS Integrity Server 2009 Installation and Configuration Guide) 

groups (see the MKS Integrity Server 2009 Installation and Configuration Guide) 

projects (see “Creating Workflow and Document Projects” on page 252) 

states (see “Creating States” on page 78) 

types (see “Creating Types” on page 84) 

fields (see “Creating Fields” on page 127) 

To create a workflow in the GUI 

CLI EQUIVALENT im createtype 

1 Open the Workflow view (see “To open the Workflow view in the GUI” on page 152). If 

this is a workflow for a type that has no states inserted, only the default state 

Unspecified displays in the workflow. 

2 Insert a state into the workflow by doing one of the following: 

From the Available states box, drag a state onto the workflow. 

From the Available states box, right click the state you want to add, and select Insert. 

Select State > Insert > State Name, where State Name is the state you want to insert. 

The state displays in the workflow. By default, everyone can edit an item without 

advancing the state in the workflow. To change from the default, see “Configuring Self 

Transitions” on page 156). 

NOTE You cannot define a field or group in the Workflow view. If another 

administrator creates a new group or field while you have a Workflow view open, 

they are not available from the view until it is re-initiated. 

155


156 

3 In the Workflow pane, select the state that you just added to the workflow. Then from 

the Mandatory fields dialog box, select the fields that the user is required to fill out before 

advancing to that state in the workflow. 

IMPORTANT If you set field visibility for groups or define a relevance rule for a 

mandatory field, you must ensure that it is both visible to users and relevant for all 

states for which it is mandatory (see “Creating Fields” on page 127). 

4 Create a state transition from a state in the workflow to the newly added state by doing 

one of the following: 

Drag the existing state in the workflow to the state added. 

Select the existing state in the workflow, and select State > Create Transition to > 

State Name, for example, submit. 

Right click the existing state in the workflow, and select Create Transition to > State 

Name. 

An arrow displays in the workflow from the existing state to the state added. The 

color of the arrow is determined by the layout direction of the workflow (see 

“Workflow View” on page 153 and “Viewing Workflow” on page 157). 

NOTE A state must have at least one state transition to be saved in the workflow. 

Every state transition must have at least one group assigned to it. 

5 Specify groups of users who are permitted to make the state transition. First select the 

state transition(s), then from Groups box select the groups. You must assign at least one 

group to each state transition in the workflow or you cannot save the workflow. 

6 Repeat this procedure to add additional states and state transitions to the workflow. 

When you complete the workflow, do one of the following: 

To save the workflow, click OK. 

To print the workflow, click Print (see “Printing Workflow” on page 161). 

To save the workflow as an image file, click Save Diagram, then follow the prompts 

(see “Saving Workflow as Image” on page 161). 

Configuring Self Transitions 

Self transitions allow users to edit the item without being required to advance it to another 

state in the workflow. By default, each state has a state transition to itself shared to the

everyone group. The self transition does not display in the workflow, but it can be 

configured as follows: 

1 In the Workflow pane (see “Workflow View” on page 153), do one of the following: 

Select the state you want to configure the self transition for, and select State > 

Configure Self Transition. The Configure Self Transition dialog box displays. 

Right click the state, then select Configure Self Transition. 

Workflows 

2 Select the groups that can edit the item in that state. Groups that are not selected can only 

edit the item by advancing the state in the workflow. 

3 Click OK. 

Viewing Workflow 

You can customize the appearance of the workflow. 

To view a workflow in the GUI 

CLI EQUIVALENT im viewtype 

1 From the Workflow view (see “To open the Workflow view in the GUI” on page 152), 

you can modify the appearance of the workflow in the following ways: 

To change the size of the workflow, select a zoom level from the View menu. The 

options are Zoom 100%, Zoom 75%, Zoom 50%, and Zoom to Fit. The zoom size 

determines the size of the workflow when it is printed or saved as an image. 

To change the layout of the workflow, select View > Layout and a layout option as 

follows: 

Up, the green arrows point from down to up 

Down, the green arrows point from up to down 

Right, the green arrows point from right to left 

Left, the green arrows point from left to right 

For example, if you perceive the workflow as climbing through the states to 

completion, use the Up layout option. 

157


Managing Workflow 

158 

2 The following information is available using tooltips: 

Point to a state transition arrow in the workflow to view a tooltip of the groups 

permitted to make that transition. 

Point to a state box in the workflow to view a tooltip of the mandatory fields 

assigned to that state and the groups permitted to edit the type without being 

required to advance it in the workflow. 

You can edit the information in a workflow as part of its management. 

To manage a workflow in the GUI 


1 Open the Workflow view (see “To open the Workflow view in the GUI” on page 152). 

2 To add additional states and state transitions, see “Creating Workflow” on page 155. 

3 To remove state transitions from the workflow, do one of the following: 

Select the transition(s) then Transition > Remove Delete. 

Right click the transition, and select Remove. 

NOTE You cannot save the workflow unless at least one group is assigned to each 

state transition in the workflow. 

4 To remove states from the workflow, do one of the following: 

Select the state(s) then State > Remove. 

Right click the state, and select Remove. 

In addition to the state, the state transitions to and from that state are removed. The 

Unspecified state cannot be deleted and must always exist in the workflow.

5 From the Edit menu, you can perform the following: 

To undo the last operation, select Edit > Undo. 

To redo the operation that undo was last performed on, select Edit > Redo. 

You can undo or redo up to 10 operations when performing the following: 

adding states 

removing states 

adding state transitions 

removing state transitions 

adding groups to selected state transitions 

removing groups from selected state transitions 

adding mandatory fields to selected states 

removing mandatory fields from selected states 

To create multiple state transitions to a single state in the GUI 


Workflows 

1 Select the states from the workflow. For more information, see “Workflow View” on 

page 153. 

2 Select State > Create Transition to, and select a state name from the list. Arrows appear 

from the states you multi selected to the state you created selected from the State menu. 

To multi-edit state transitions in the GUI 


1 Select the transitions you want to edit. For more information, see “Workflow View” on 

page 153. 

2 In the Groups box, groups that are assigned to all of the selected state transitions display 

a black checkmark. Groups that are assigned to some but not all of the selected state 

transitions display a gray checkmark. Clicking a check box either displays a black 

checkmark or clears an existing checkmark. 

3 Right click the group name you want to edit states transitions for. A context menu 

displays listing the state transitions you multi selected. State transitions for that group 

are checkmarked in the list. 

159


160 

4 Select a state transition from the list to either assign it for the group or clear it from the 

assigned group. Repeat as necessary until the group is assigned to the desired state 

transitions. 

5 Repeat steps 3 and 4 for all groups you want to assign to state transitions. 

To multi-edit states in the GUI 


1 Select the states you want to edit. For more information, see “Workflow View” on 

page 153. 

2 In the Mandatory fields box, fields that are mandatory for some but not for all of the 

selected states display a gray checkmark. 

3 Right click the field name you want to edit states for. A context menu displays listing the 

states you have multi selected. If the field is mandatory for that state, it is checkmarked 

in the list. 

4 Select a state from the list to assign it a mandatory field. Repeat as necessary until the 

field is mandatory for the desired states. 

5 Repeat steps 3 and 4 for all mandatory fields you want to assign to the states.

Printing Workflow 

Workflows 

You can print out the workflow in a variety of sizes, depending on the zoom factor (for more 

information, see “Viewing Workflow” on page 157). 

To fit the workflow on a single printed page, select View > Zoom to Fit before printing. 

To print a workflow in the GUI 


click Print. A print dialog box displays. 

2 Select the print options you want. 

3 Click OK. 

Saving Workflow as Image 

You can save a copy of the workflow in an image format for use in documents or on Web 

pages. The zoom factor determines the size of the workflow in the saved image. For more 

information, see “Viewing Workflow” on page 157. 

To save a workflow as an image in the GUI 


click Save Diagram. The Save Diagram dialog box displays. 

2 Enter the location where you want to save the image. 

3 Click Save. 

Testing Workflow With Admin Migration Wizard 

As part of the procedure for setting up workflows and documents, you can use the 

MKS Integrity Admin Migration Wizard (migration wizard) to test your workflows and 

documents configuration on a separate server before ultimately migrating a final 

configuration to your production MKS Integrity Server. 

For the purpose of migrating workflow and document admin provided objects, the separate 

server for testing your configuration is called the staging server and the MKS Integrity Server 

that users connect to is known as the production server. By default the MKS Integrity Server is 

always installed as a production server. The production server manages all aspects of 

MKS Integrity: workflows and documents, requirements, configuration management, 

testing, and deployment. The migration wizard allows you to test proposed changes 

thoroughly on the staging server before migrating those changes to the production server, 

avoiding the situation where live changes must be made in your production environment. 

161


162 

The process helps you to work with the required admin provided objects to create a 

workflow that functions for your environment. 

Staging 

Server 

Holds Lock on 

Production 

Admin Migration Server Configuration 

1 

Copy Database 

Migrate Objects 

2 

Production 


Locked by Staging 

IMPORTANT Production and staging servers must be installed on separate machines. 

Both servers must be from the current release. 

To create a staging server, you must install a second MKS Integrity Server on a separate 

machine and then configure specified properties on that server. 

The staging server starts by using a copy of the MKS Integrity database from the production 

server. The two servers must have identical copies of the database or you cannot begin the 

initial migration configuration setup (later, changes to imported users and converted admin 

provided objects are automatically detected and can be imported from the production 

server). The database copy is created manually, based on the recommended procedures for 

the type of database you are using for your system. If assistance is required for managing the 

database, you should contact your database administrator. 

In starting up, the staging server automatically obtains a binding administrative lock on the 

production server. The administrative lock means that no changes can be made to workflow 

and document admin provided objects on the production server. The binding establishes an 

association between the two servers: the staging server is the server you want to test your 

workflow changes on, and the production server is the server you want to ultimately migrate 

the changes to. At any time, you may also lock the staging server to prevent changes from 

being made in your test environment. 

When you have made your desired changes on the staging server, the migration wizard 

allows you to transfer those changes to the production server. After a successful migration, 

the production server then has the same administrative configuration in MKS Integrity that 

existed on the staging server. You can also elect to transfer only specific changes to the 

production server. States, fields, workflows, and other admin provided objects migrated

Workflows 

from the staging server function in the same way on the production server. You can migrate 

admin provided objects repeatedly until all the desired changes are migrated. 

IMPORTANT Releasing the lock on the production server means that the binding link 

between the staging server and production server is lost and the two servers are no 

longer synchronized. Further staging work therefore requires a new copy of the 

database from the production server, including items outside of the database such as 

trigger scripts and workflow and document report templates. 

Admin provided objects and components that are migrated include the following: 

administrative charts 

administrative dashboards 

administrative queries 

administrative report resources 

administrative reports 

change package attributes 

change package entry attributes 

change package types 

dynamic groups 

fields 

files under the data/public_html directory 

groups 

item presentation templates (including image files in the public_html directory) 

projects 

states 

document items 

time entries 

trigger scripts 

triggers 

types 

users 

ViewSets 

test verdicts 

163


164 

The basic steps for completing a workflow migration include: 

1 Install and start the MKS Integrity Server you intend to use for production purposes (the 

production server). For more information, see “Installing and Starting Production 

Server” on page 166. 

2 On a separate machine (the staging server), install the MKS Integrity Server you intend 

to use for testing and migrating your workflow and document admin provided objects. 

For more information, see “Installing and Configuring Staging Server” on page 166. 

3 Place an administrative lock on the production server before copying the database. For 

more information, see “Managing Administrative Locks” on page 169. 

4 Copy the database (and other necessary objects) from the production server to the 

staging server. For more information, see “Copying MKS Integrity Database” on 

page 168. 

5 Start the staging server, which automatically creates a lock binding between the staging 

server and the target production server. For more information, see “Starting Staging 


6 Configure workflow and document admin provided objects on the staging server and 

test your configuration. For more information, see “Testing Workflow and Document 

Configuration” on page 169. 

7 As required, manage administrative locks on the staging and production servers to keep 

the two databases synchronized. For more information, see “Managing Administrative 

Locks” on page 169. 

8 Migrate your configuration from the staging server to the production server. For more 

information, see “Using Admin Migration Wizard” on page 171. 

Two Stage Server Configuration 

MKS Integrity supports a two-stage migration whereby two staging servers are used with a 

single production server. For example, the two staging servers in the following diagram are 

named Development and Test. In this configuration, all changes are made on the 

Development server and migrated to the Test server for testing. Only if the changes test 

successfully are they migrated to the Production server. 

Development 

Test 



Holds Lock on 

Holds Lock 

on Test Server Migrate Objects 

Production 

Locked by 

Development 

Migrate Objects 

3 4 

Two Stage Server Configuration 

2 

Copy Database 

1 

Copy Database 

Production 


Locked by Test

The basic steps for completing two stage workflow migration include: 

Workflows 

1 Install and start the MKS Integrity Server you intend to use for production purposes (the 

production server). For more information, see “Installing and Starting Production 


2 On a separate machine (a staging server), install the MKS Integrity Server you intend to 

use for development of your workflow and document admin provided objects. For more 

information, see “Installing and Configuring Staging Server” on page 166. 

3 On a separate machine (a staging server), install the MKS Integrity Server you intend to 

use for testing of your workflow and document admin provided objects. For more 

information, see “Installing and Configuring Staging Server” on page 166. 

4 Create administrative locks, and then copy databases as follows: 

a) Copy the database from the production server to the staging server you want to use 

for testing. For more information, see “Copying MKS Integrity Database” on 

page 168. 

b) Copy the database from the production server to the staging server you want to use 

for development. For more information, see “Copying MKS Integrity Database” on 

page 168. 

NOTE Ensure that the production server (in step 1) has been started before starting 

the servers in steps c) and d) next. 

c) Start the test staging server, which automatically creates a lock binding between that 

staging server and the target production server. For more information, see “Starting 

Staging Server” on page 168. 

d) Start the development staging server, which automatically creates a lock binding 

between that staging server and the test staging server. For more information, see 

“Starting Staging Server” on page 168. 

IMPORTANT Place an administrative lock on the production server before copying 

the database. To place an administrative lock manually, see “Managing 

Administrative Locks” on page 169. 

5 Configure workflow and document admin provided objects on the development staging 

server, then test the configuration of those objects on the test server until you have a final 

configuration. For more information, see “Testing Workflow and Document 

Configuration” on page 169. 

6 As required, manage administrative locks on the staging and production servers to keep 

the databases synchronized. For more information, see “Managing Administrative 

Locks” on page 169. 

165


166 

Installing and Starting Production Server 

The production server is the MKS Integrity Server that users connect to when using 

MKS Integrity. By default, all MKS Integrity Servers are installed as production servers. For 

detailed procedures on installing and starting the MKS Integrity Server, see the MKS Integrity 

Server 2009 Installation and Configuration Guide. 

Installing and Configuring Staging Server 

By default, all MKS Integrity Servers are installed as production servers. To create a staging 

server, you install another MKS Integrity Server on a separate machine. For more 

information on installing an MKS Integrity Server, see the MKS Integrity Server 2009 


After installing the second MKS Integrity Server, configure additional properties to have it 

operate as a staging server. Configure the following properties in the installdir/config/ 

properties/is.properties file: 

Properties To Be Modified Defined Values 

mksis.adminStagingServer= If MKS Integrity Server is to function as production server or 

staging server. Valid options are true or false. If false, 

MKS Integrity Server functions as standard production server. If 

true, MKS Integrity Server functions as staging server that can 

be used to test workflow configuration and migrate it to 

production server. 

By default, mksis.stagingServer=false (that is, 

MKS Integrity Server operates as standard production server). 

mksis.adminStagingServerDisplayName= Display name of staging server. For example, if you are using 

two stage staging server configuration, two staging servers can 

be named Development Server and Test Server. If no 

value specified, display name is Staging Server. 

In the title bar of the MKS Integrity Administration Client, the 

name of the staging server displays. For example, if you specify 

the staging server name as My Server, the following displays: 

Administration jriley@abcFinancial:7001 (My 

Server - Locked) 

If you do not specify a name, the following displays: 

Administration jriley@abcFinancial:7001 

(Staging Server - Locked) 

Note: On a production server, Locked appears only if the 

staging server is manually locked. 

NOTE The names of the staging server properties are case sensitive. For example, 

you must use mksis.im.prodServer rather than mksis.im.prodserver. 

To configure the staging server, configure the following properties in the installdir/config/ 

properties/im.properties file:

Properties To Be Modified Defined Values 

mksis.im.prodServer= Host name of production MKS Integrity Server. 

mksis.im.prodPort= Port number to connect to on production server. 

E-mail Notification Upon Lock Break 

Workflows 

mksis.im.prodUser= Login ID of administrator used when the staging server 

performs verifications and comparisons between the staging 

and production servers. 

Note: The Admin Migration Wizard allows you to specify a login 

ID and password for the administrator migrating workflow and 

document admin provided objects. 

mksis.im.prodPassword= Password of administrator used when the staging server 

performs verifications and comparisons between the staging 

and production servers. 

Note: Password encryption is enabled for this password if you 

have encryption enabled on MKS Integrity Server. 

mksis.im.allowPartialAdminMigration= If true, permits ability to migrate individually specified objects 

from staging server to production server. 

Note: This property is modified under Workflows and 

Documents > Configuration > Properties in the 


mksis.im.allowAdminDeletionWithAdmin 

Migration 

As administrator, you can ensure that you are notified whenever an administrative lock is 

broken by editing the following property under Workflows and Documents > 

Configuration > Properties in the MKS Integrity Administration Client: 

mksis.im.notificationsOnAdminLockBreak==value 

where value is a comma separated list of e-mail addresses for the administrators to be notified 

whenever an administrative lock is released 

Configuring SMTP Server 

To configure an SMTP server for handling e-mail notifications, edit the following property 

under Configuration > Properties in the MKS Integrity Administration Client: 

mksis.mailserver=hostname 

If true, permits you to delete admin objects on a staging 

server, even if that object has been migrated to the production 

server. By default, you may only delete admin objects if they 

have not been migrated to the production server. This prevents 

deadlock situations from occurring during an admin migration. 

Note: This property is modified under Workflows and 

Documents > Configuration > Properties in the 


where hostname is the host name or TCP/IP address of the SMTP server to send e-mail 

notifications through. 

167


168 

Copying MKS Integrity Database 

Before creating a copy of your database, you should back up the existing production database 

and then restore a copy for use by the staging server. Follow the copying procedures 

recommended for the specific database you are using. 

CAUTION To ensure that you do not lose any data, follow the manufacturer’s 

recommended back up procedures for the specific database you are using. 

Starting Staging Server 

You start the staging server using the standard procedure for starting any MKS Integrity 

Server. For more information on starting the server, see “Running MKS Integrity Server” on 

page 283MKS Integrity Server 2009 Installation and Configuration Guide. 

Starting the staging server automatically creates a lock binding between the staging server 

and the production server. You can confirm the status of the lock binding by connecting to 

the production server, right clicking the Workflows and Documents directory node, and 

then selecting View Admin Lock from the shortcut menu. The View Admin Lock dialog box 

displays information on the production server (hostname:port number) that is locked, 

when the lock was obtained, and the staging server (hostname:port number) it is bound to. 

For more information on lock binding, see “Managing Administrative Locks” on page 169. 

IMPORTANT When starting the staging server for the first time, it will not start if 

differences are detected between it and the production server. 

When the staging server starts, it first tests to see if its database contains the same workflow 

and document admin provided objects as the production server's database. If they are 

identical, the production server creates a binding lock to that staging server. The server also 

tests to see if the Integrity Presentation Templates (IPTs), trigger scripts, reports, ViewSets, 

and the public_html directory are identical. If differences are detected, the staging server 

does not start. 

NOTE Exceptions to the database content include auto imported users/groups. 

If the production server is not running when the staging server attempts to initialize, the 

staging server does not start. If the production server is running, the staging server creates a 

lock binding. 

If the production server already has a lock as a result of a super administrator manually 

obtaining the lock, then the staging server still creates a lock binding between the two 

servers. A check is then carried out to ensure that the admin provided objects on the staging 

server match exactly with those on the production server. If they are not the same, the staging 

server does not start and the lock binding is dropped. An error message is posted to the 

installdir/log/server.log file on the staging server.

Workflows 

A lock binding cannot be directly created by an administrator. It is created automatically 

when the staging server has initialized and successfully verified that it is synchronized with 

the production server. Once the staging server is started and the binding lock is set, you can 

then modify the required workflow and document admin provided objects on the staging 

server. 

Testing Workflow and Document Configuration 

Once the staging server is started and creates a lock binding to the production server, you can 

work with the required admin provided objects to create a workflow that functions for your 

environment. Admin provided objects cannot be modified when the production server is 

locked. 

For detailed information on working with the various admin provided objects in 

MKS Integrity, see the following sections: 

For Managing Users, Groups, and Dynamic Groups, see the MKS Integrity Server 2009 






“Managing Field Relationships” on page 143 


“ViewSets” on page 49 

Managing Administrative Locks 

Locking a server means that the server is no longer editable directly through the standard 

command set. The migration wizard requires that the production server be locked before it 

can start any migration operation. Locking ensures that no changes can be made during the 

migration or at any time while the staging server is bound to the production server. 

IMPORTANT As administrator, you can also manually lock either the staging or 

production servers, or both, to prevent administrative changes from taking place. 

Locking both servers means that no one can make any administrative changes to the 

workflow and document system unless they are using the Admin Migration 

Wizard. 

It is important to understand that an administrative lock cannot be used to prevent 

other administrators from making changes so that you (the owner of the lock) can 

make changes. 

169


170 

Creating a lock binding is the act of linking one server to a lock on another server. When a 

lock binding is created, the production server records the host name and port of the staging 

server. 

IMPORTANT 

You cannot bind two different staging servers to the same production server. 

Do not break a lock when a migration operation is in progress. 

A lock binding cannot be directly created by an administrator. It is created automatically 

when the staging server has initialized and successfully verified that it is synchronized with 

the production server. 

If the connection between the staging and production servers is lost for any reason, such as a 

hardware or network failure, the lock remains on the production server and the staging 

server continues to act as if the lock binding relationship is in place. If the migration wizard is 

started while the communication between the two servers is still broken, then the system 

posts an error. You cannot then run the migration wizard until the problem has been 

resolved. 

To avoid the possibility of any administrative changes occurring while the staging server is 

being brought on line, you can also manually lock the production server before setting up the 

staging server. If the production server is locked when the staging server initializes, a lock 

binding is still created. 

IMPORTANT When the production server is locked, users and groups can be 

automatically imported. 

In the GUI, locking and unlocking are available through the shortcut menu. For more 

information, see “To work with administrative locks in MKS Integrity” on page 171. 

If a super administrator attempts to break a lock on the production server, a warning 

message indicates that breaking the lock invalidates any work that is currently being done on 

the staging server and that the staging server must be re-initialized. E-mail notifications are 

also sent, provided the appropriate properties have been configured. For more information, 

see “E-mail Notification Upon Lock Break” on page 167. 

CAUTION Releasing the lock on the production server means that the lock binding 

between the staging server and production server is lost and the two servers are no 

longer synchronized. Further staging work, therefore, requires a new copy of the 

database from the production server. 

You can also control server locks through the CLI using the commands for 

im obtainadminlock, im releaseadminlock, and im viewadminlock. For more 

information on using these commands, see the MKS Integrity Server 2009 Administration CLI 

Reference Guide.

To work with administrative locks in MKS Integrity 

1 Open the MKS Integrity Administration Client and connect to the selected 

MKS Integrity Server, whether a staging server or production server. 

Workflows 

2 Right click the Workflows and Documents node on the tree pane. From the shortcut 

menu, select one of the following commands: 

Obtain Admin Lock to place an administrative lock on the server. If you have the 

required permissions, the lock is placed immediately. If you do not have the 

required permissions, an error message displays. 

Release Admin Lock to release an administrative lock on the selected server. If you 

are releasing the lock on a production server, a message cautions you that releasing 

the lock means an inability to migrate any existing changes from the staging server 

to the production server. The message includes the user ID of the person who set the 

lock, the lock timestamp, and the host name and port of the server the lock is bound 

to. If the lock is not bound to any staging server, the message indicates that. 

View Admin Lock to view the status of an existing lock on the production server. 

Anyone using the MKS Integrity Administration Client can view the status of an 

administrative lock. The View Admin Lock dialog box displays the user ID of the 

person who set the lock and the lock timestamp. After reviewing the status of the 

target lock, click Close to exit. 

3 In the title bar of the MKS Integrity Administration Client, an administrative lock is 

indicated by Locked, for example: 

On a locked production server: 

Administration jriley@abcFinancial:7001 (Locked) 

On a locked staging server: 

Administration jriley@abcFinancial:7001 (Staging Server - Locked) 

On a locked staging server with stagingsServerDisplayName=My Server 

specified in is.properties: 

Administration jriley@abcFinancial:7001 (My Server - Locked) 

If there is no administrative lock, lock status is not appended to the title bar. For 

example, an unlocked staging server displays: 

Administration jriley@abcFinancial:7001 (Staging Server) 

Using Admin Migration Wizard 

Once you are ready to migrate your final changes to the production server, you can launch 

the migration wizard. You can also run the wizard to view the existing state of 

synchronization between the production and staging servers. Only an MKS Integrity super 

administrator can perform the final operation to migrate changes. Type administrators are 

only permitted to view migration details using the wizard. 

171


172 

You launch the migration wizard from the MKS Integrity Administration Client by right 

clicking the Workflows and Documents node and selecting Launch Admin Migration Wizard 

from the shortcut menu. The Launch Admin Migration Wizard menu item appears only when 

the server is configured as a staging server and for users who are assigned as super 

administrators or type administrators. 

Only the super administrator can actually perform a migration. Type administrators may 

access the migration wizard only to view the information but cannot complete the migration 

operation. Type administrators can view all admin provided objects but can only edit the 

ones that they have permissions for. 

Changes made by the migration wizard are shown as being carried out by the super 

administrator user who ran the migration operation. All changes are viewable in the history 

for the object and in the audit log. 

If the staging server or the production server is disconnected, or if the whole system is put 

into a state where the migration cannot be completed, then the operation is rolled back to put 

the production server (or staging server) into a usable state. You can also cancel a migration 

that is in progress. The operation is then rolled back to put the production server into a 

usable state. 

Migrating admin provided objects from the staging server to the production server involves 

updating the configuration for the entire object being modified. When you perform the 

migration, all overrides are transferred to production. Therefore, you should only start a 

migration when all changes are finalized on the staging server. Since this may affect the work 

of multiple type administrators, you may want to consult with all type administrator before 

starting a migration. Once the migration is complete, a migration report displays. 


The super administrator who performs the migration must also be a super administrator 

on the target production server (that is, he or she must have the Admin ACL permission 

under mks:im). 

MKS recommends that all locks be maintained while the migration is running. If the lock 

on the production server is broken during a migration, an error message displays and 

the migration stops. 

To prevent deadlock situations from occurring during an admin migration, you cannot 

delete admin objects on a staging server if they have been migrated to a production 

server. Admin objects that have not been migrated to a production server may be 

deleted. 

To migrate a shared field or state that has an override, without migrating the overrides 

of the new types that refer to it, see “Migrating a Shared Field or State Override” on 

page 177.

Workflows 

To migrate workflow and document admin provided objects to the production server 

NOTE Settings chosen from a previous migration session are not retained. 

1 On the staging server, open the MKS Integrity Administration Client. 

2 Right click the Workflows and Documents node on the tree pane and select Admin 

Migration Wizard. The wizard displays, confirming the server you are migrating data 

from and the server you are migrating data to. The wizard also confirms the type of 

migration your server is configured to perform, for example, a partial admin migration. 

In addition to migrating user objects, you can also choose to migrate user notification 

rules by enabling Include user notification rules. By default this option is disabled. 

Enabling this option overwrites individual user notification rules configured by users. 

IMPORTANT Enabling Include user notification rules may significantly increase the 

time required to migrate your data. 

To continue, click Next. 

3 If the wizard detects admin provided objects or users/groups with identical names on 

both the test and production servers, the objects or users/groups are listed in the 

Identical Objects panel of the wizard. 

If this occurs, the migration wizard asks you to confirm that the two admin provided 

objects are to be mapped together. Do one of the following: 

If the object names can be mapped together, click Next to continue the migration. 

The migration wizard then links the two counterparts and any differences between 

the objects display as edits. 

If the two object names are not to be mapped together, click Cancel to stop the 

migration. Then either rename or delete the object on the staging server to avoid an 

error. 

If there are no duplicate named admin provided objects, the Identical Objects panel does 

not display. Instead, advance to the next step. 

4 If the wizard detects changes to the staging server (or test server depending on your 

configuration), the import panel displays the new admin provided objects (or users and 

groups) that must be imported into the production server database. To import the admin 

provided objects, click Next. You cannot advance through the wizard without first 

importing the admin provided objects. 

NOTE Differences between servers for LDAP realm users appear on this panel. 

If there are no new admin provided objects on the production server, the import panel 

does not display. Instead, advance to the next step. 

173


174 

5 The migration wizard displays the options for migrating unused objects. To continue, 

click Next. The summary panel displays the available changes to be migrated from the 

staging server to the production server. 

By default, the Show objects containing data filter displays all objects on the staging 

server. Use the data filter to display objects you want to migrate to the production 

server. For more information on using the data filter, see “Filtering Data” on page 18. 

When you select an object in the Show objects containing data filter, its metadata 

displays in the bottom pane. 

IMPORTANT You can only select individual candidates for migration if the 

mksis.im.allowPartialAdminMigration property is set to true in file 

im.properties. For more information, see the MKS Integrity Server 2009 


If there are mandatory objects for the selected object, they are highlighted in light blue. 

Mandatory objects always move with the selected object. Objects are only highlighted 

when selecting another object that either is an object with a reference to or from it or if 

there is some relationship that requires the actions to be performed in the same

Workflows 

migration. If there are objects referenced by the selected object, those referenced objects 

display an icon in the Ref Info column, indicating the relationship. 

The following details are provided for admin provided objects in each list: 

Position indicates the order objects are migrated in. 

Type indicates the type of admin provided object affected by the change, for 

example, State. 

Name indicates the name of specific admin provided object, for example, state 

Published. 

Action lists the type of change that occurred, for example, Create. 

Modified Date indicates the date the object was modified (not always available). 

Modified User indicates the user name of the user who modified the object (not 

always available). 

Ref Info indicates the relationship to and from the selected object. 

indicates that the object refers to at least one of the selected objects. 

indicates that the object is referenced by at least one of the selected objects. 

indicates that the object refers to at least one of the selected objects and that 

at least one of the selected objects refers to this object. 

Selected indicates the object is currently selected (explicitly or implicitly). This 

allows you to sort by the selected objects if they are spread out among a large list of 

objects. Once you make a new selection, the column must be resorted if the new 

selection is sorted by selection. 

Grouping indicates a number given to selections of objects added to the Objects to 

be migrated list. A grouping number allows you to move objects between the lists as 

groups. 

Explicit indicates that the selected object was explicitly added to the list. This 

column is hidden by default. 

Referred By indicates the number of objects that this object is referenced by. This 


Refers To indicates the number of objects that this object directly references. This 


To include one or more objects for migration, select the object(s) in the Show objects 

containing data filter and then click + to move the object(s) to the Objects to be migrated 

list. Similarly, to remove one or more objects from the Objects to be migrated list, select 

the object(s) and click x to return them to the Show objects containing data filter. 

175


176 

To print migration candidates, click Print. The Print summary of admin migration to be 

performed dialog box displays. Select one of the following, and then click Print: 

Print filtered changes not to be migrated prints the contents of the top data filter. 

Print all changes being migrated prints the contents of the Objects to be migrated 

list. 

NOTE Availability of this option requires that the property mksis.im. 

allowPartialAdminMigration be true in file im.properties. For more 

information, see the MKS Integrity Server 2009 Installation and Configuration Guide. 

To select the migration policies you want applied for this migration, click Options. The 

available options include: 

Include References 

Select this option to automatically select all objects that the explicitly selected objects 

reference. If any of these additional objects force more objects to be implicitly 

selected, they are also selected.

Include References Recursively 

Select this option to recursively include the objects that the referenced objects 

reference. 

Include Referrers 

Workflows 

Select this option to automatically select all objects that have references to the 

explicitly selected objects. If any of these additional objects force more objects to be 

implicitly selected, they are also selected. 

Include Referrers Recursively 

Select this option to recursively include the objects that reference the objects 

referencing the selected objects. 

NOTE If you are a type administrator, you do not have permission to run the 

migration and the next panels are not available for viewing. 

6 To continue the migration, click Next. The migration wizard displays the description 

field. Enter a description for this migration request. 

7 To continue the migration, click Next. The migration wizard displays the credentials 

panel. 

To finish the migration, enter your credentials (user name and password) for logging 

into the production server, and click Finish. 

NOTE 

To cancel a migration after it has started, right click the status bar at the bottom of 

the MKS Integrity Administration Client window, and select Cancel from the 

shortcut menu. Once the migration operation is completed, it cannot be undone. 

Settings chosen from a previous migration session are not retained. 

After the migration is completed, the migration report displays the results of the 

migration, including the options and policies you selected. 

Click OK. 

You can also view a record of the staging server operations for the migration in the file 

installdir/log/server.log. 

Migrating a Shared Field or State Override 

If you override a shared field or state for an item type on the staging server, when you 

migrate the field with the override you must also migrate any new item types that refer to the 

override. This can make migration difficult to manage, especially if there are multiple 

administrators or groups developing workflows. 

The admin migration wizard contains a CLI command that allows you to migrate a shared 

field or state that has an override, without migrating the overrides of the new types that refer 

177


178 

to it. This also removes the requirement of the new types to be migrated. To enable this 

feature, set the following property to true under Workflows and Documents > 

Configuration > Properties in the MKS Integrity Administration Client: 

mksis.im.allowOverrideSuppression 

NOTE You must have the AdminServer permission. 

If this feature is enabled and if you have created at least one new type on the staging server 

that has at least one field or state override, a new type overrides panel displays after the 

welcome panel of the Admin Migration Wizard. The new panel lists each item type that has 

not been migrated. You can select the type(s) that you want to temporarily remove overrides 

for during the migration. 

In the summary panel of the Admin Migration Wizard, item types that referenced a field or 

state override that has been removed are no longer highlighted as mandatory. If you select an 

item type, the metadata displayed at the bottom of the screen indicates if its overrides have 

been removed. 

Field or state overrides remain on the staging server and can be migrated separately when 

required. 

Considerations When Modifying Visibility, 

Editability, and Types 

Workflow and document, and configuration management users may experience errors when 

trying to create change packages if visibility rules, editability rules, or type specifications are 

not properly set. The following modifications may result in user error: 

visibility of the Assigned User, Project, or Summary fields 

visibility of the SI Change Package project (used for configuration management 

standalone change packages), excluding the creator of the change package 

editability of the Assigned User, Project, or Summary fields 

specifications of the SI Change Package type (used for configuration management 

standalone change packages) 

For more information, see the following: 

“Setting Workflow and Document Project Visibility” on page 250 

“Setting Field Visibility for Types” on page 120 

“Editing Types” on page 91

Deleting Admin Provided Objects and Items 

Deleting Admin Provided Objects and Items 

As administrator, you may want to delete some of the building blocks that are used by 

MKS Integrity. A building block is any one of the fundamental pieces that your MKS Integrity 

database is built on, such as users, groups, projects, and items. 

Deleting Admin Provided Objects 

Deleting Items 

You can delete a user, group, dynamic group, type, state, field, or project, if you have not 

used them to make a change to the database. You cannot delete any building block that has 

been recorded in the history. For example, if you create a user or group and want to delete it 

immediately, you can. However, if a user or a group member logs in as that user and creates 

an item, or if someone else assigns an item to that user or group, you can no longer delete that 

user or group. 

You can only delete a project if an item does not reference that project or any of its children. 

To delete an idle project that has children, you must first delete all of its children and then 

delete the project. 

You can delete admin provided objects that have references to other admin provided objects 

as long as the admin provided object you are deleting does not violate the restrictions 

mentioned earlier in this section. When deleting the admin provided object, a prompt 

displays stating if there are object references. You then have the opportunity to cancel and 

manually remove the references. Object references can be viewed on the References tab when 

editing or viewing an admin provided object. For information on identifying object 

references, see “To manage admin provided objects in the MKS Integrity Administration 

Client” on page 244. 

IMPORTANT Contrary to other admin provided objects, you cannot delete a field if it 

has references to other admin provided objects, even if that field has not made a 

change to the database. You must remove the references before deleting the field. 

Deleting an item removes it from the database. Only a user with the DeleteItem permission 

can delete an item of any type; however, your administrator can assign the 

ModifyDeleteItemRule permission, allowing a type administrator to set a type rule that 

specifies which users can delete items of that type. Deleting an item removes the item history 

and any links to attachments, change packages (change package members associated with the 

item are not deleted from the database), relationships (including both forward and backward 

relationships), and some history records from related items. If you delete an item containing 

relationships, the history of each related items denotes the ID of the deleted items, the user 

that deleted the items, and the date of the deletion. 

179


180 


Deleting an item is irreversible. 

The ID of a deleted item is never reused. 

MKS recommends that you do not delete requirements management items. With the 

release of the Requirements Management 2007 solution template and the associated 

node-item data model, these items are linked to configuration management baselines 

which means that these items, if deleted, change the recorded baseline as if the items 

never existed. 

If you are using both workflows and documents, and configuration management, do not 

confuse an item’s change package members with project or Sandbox members. 

To delete an Item in the GUI 

CLI EQUIVALENT im deleteissue 

You can delete an item by choosing the delete option from the Item menu in the GUI. 

Although this option is outside the MKS Integrity Administration Client, the Delete Item 

command is not visible to users without administrative privileges. If the delete option is 

unavailable even though you have selected an item to delete and the item displays in the Item 

Details panel, this item cannot be deleted temporarily because it is being edited by another 

user. 

1 In the Query Results pane, select an item to delete, making sure it displays in the Item 

Details panel. 

2 Select Item > Delete. The Delete Item message warns you that deleting this item cannot be 

undone and that if you delete it all the history information for this item is lost. 

3 Click Yes to confirm the deletion of an item. After successful deletion, the item is 

removed from the Item Details pane. 

4 Run the query to remove the item from the Query Results view. 

Setting Up E-mail Notification 

Any MKS Integrity user can be notified through an e-mail message whenever a new item is 

submitted or item information changes. This is useful for users who need to review and 

approve state changes on new submissions or existing items and for users who need to work 

on items assigned to them. Notifications also keep users informed of project progress.

NOTE 


E-mail notification is subject to project, type, and field visibility rules. Only users 

that have visibility for a given project and type receive e-mail notification for 

items related to that project and type. In addition, e-mail notifications include 

only the fields they have permission to view. For more information, see “Setting 

Workflow and Document Project Visibility” on page 250, “Setting Type 

Visibility” on page 114, and “Setting Field Visibility for Types” on page 120. 

E-mail notifications are evaluated on the MKS Integrity Server’s time zone. 

You configure MKS Integrity to send you e-mail notification by creating rules. Rules are made 

up of conditions, which are logical expressions of specific item field changes that you want to 

be notified about. For example, you could create a simple rule containing one condition that 

sends you e-mail every time a new problem assigned to you is submitted. Similarly, you 

could create a complex rule containing two conditions that sends you e-mail every time a 

new problem assigned to you is submitted and when existing problems become assigned to 

you. Rules can contain as many conditions as you want. 

The e-mail message displays information on the item, for example, the item type, ID, 

summary, who edited the item and when, a hyperlink to the item, and the modified fields. 

Optionally, you can select additional notification fields for each type. These additional 

notification fields are included in the notification e-mail sent to users. Additional notification 

fields appear as a separate Notification Fields section between the default header 

section and the Modified Fields section. 

You can also select the character set that the MKS Integrity Server uses when sending e-mail. 

The property controlling the character set is contained in file: 

installdir/config/properties/is.properties 

By default, the character set for internationalization support is: 

java.system.property.smtpencoding=UTF-8 

Permissions for E-mail Notification 

Depending on how MKS Integrity is configured, the administrator may be the only one who 

can create and edit e-mail notification rules for users and groups. If you want users to have 

access to the notification feature, you assign the following permissions to them: 

allow ViewMyNotification allows users to view e-mail notification settings, but not 

make any changes to them. If users do not have this permission, they see the options but 

cannot perform any edits in the GUI. In the Web interface, users who do not have 

ViewMyNotification may select Session > Notifications, but the notification settings 

do not display. 

allow ModifyMyNotification allows users to create and edit notification rules. If 

users do not have this permission, they cannot create or edit e-mail notification rules. 

181


182 

For more information on setting permissions, see the MKS Integrity Server 2009 Installation and 


To set e-mail notification in the GUI 

CLI EQUIVALENT im setnotification 

1 In the MKS Integrity Client, select Item > Set Notification. The Notifications dialog box 

displays. 

2 The e-mail address specified for you by your administrator is automatically entered in 

the Email Address field. 

3 If certain conditions are met, nodes specify if e-mail notification is sent. Select a node 

option by clicking a button: 

And specifies that all of the conditions specified must be true for an e-mail 

notification to be sent. For example, if an item’s assigned group = 

documentation and project = editor, then an e-mail notification is sent. 

Or specifies that one or more of the conditions must be true for an e-mail notification 

to be sent. For example, if an item’s state = submitted or the priority is not 

equal to high, an e-mail notification is sent. 

Swap replaces the selected node with the opposite node. For example, swapping an 

Or node replaces it with an And node. 


NOTE You do not need to use the And and Or nodes if your rule contains only one 

condition. If your rule contains more than one condition, you must begin by 

entering and And or Or node. 

The following image shows a sample notification rule.


4 Under Condition, define the conditions that specify when an e-mail notification is sent. 

For more information, see “Defining Rules” on page 43. 

For example, you can configure MKS Integrity to send an e-mail notification every time 

the assigned user of an item is changed to the specified user, such as in the following 

example: 

Assigned UserAssigned User 

Assigned User=mchang 

You could also configure MKS Integrity to send an e-mail notification for all items that 

are currently assigned to the specified user (such as, Assigned User=mchang). 

5 To add the condition to the rule, click Add. To replace an existing rule with a new rule, 

select the rule in the rules list, and then click Replace. 

6 To accept the changes, click OK. 

183


184 

To set e-mail notification in the Web interface 

The Web interface allows you to set simple e-mail notification rules, for example, receiving 

e-mail notification when new submitted items are assigned to you. 

NOTE To create advanced e-mail notification rules, you must create them in the GUI. 

1 Click My Profile on the right side of the title pane. 

NOTE When the view is maximized, click in the title pane and select My Profile. 

The My Profile dialog box displays. Your e-mail address displays on the Item 

Notifications tab. 

NOTE If you create a notification rule in the GUI that is too complex to view or edit 

in the Web interface, you are asked whether you want to delete the existing rule and 

create a new one in the Web interface. 

2 Click the button and select a pre-defined notification rule. The pre-defined rule 

displays in the list with a . 

3 Click specific type(s) in the rule and use the data filter to select one or more item types to 

be notified about when the condition described in the rule is satisfied. For example, if 

you set the notification rule Items of type(s) Defect are submitted you would be notified 

when a new Defect item type is submitted. 

If you select a rule that has an item state condition, click specific state(s) and use the data 

filter to select one or more states that the specified item type must be in for a notification 

to be sent. For example, if you set the notification rule Items of type(s) Docs are assigned


to state(s) Rejected you would be notified when a documentation item is rejected. The 

list of states you can select depends on the workflow implemented by your 


If you add more than one rule at a time without defining any values for them, all rules 

display with a . After defining the values for one of the rules, the changes to a . 

4 Repeat steps 2 and 3 for any additional notification rules. All rules are connected using 

the logical or, which indicates that one or more of the specified conditions must be true. 

To remove a notification rule, select it and click . 

5 When all the notification rules are set, click OK. 

Troubleshooting E-mail Notification 

In the event of problems with e-mail notification, you can also configure specific properties to 

increase the level of detail included in the error messages that are logged to the 

MKS Integrity Server. The relevant properties are included in the following file on the 

MKS Integrity Server: 

installdir/config/properties/logger.properties 

where installdir is the path to the directory where you installed the MKS Integrity Server. 

Logging levels are set to a value between 0 and 10, with 10 providing the greatest level of 

detail. Increasing the logging level increases the level of detail returned in the error message. 

185


186 

Logging for SMTP Operations 

The following property provides a category to log the SMTP conversation between the 

MKS Integrity Server and the SMTP server: 

mksis.logger.message.includeCategory.SMTP=10 

Logging for MKS Integrity E-mail Notification 

The following properties provide categories to log rule evaluations, project visibility checks, 

error handling, and other information for the MKS Integrity notification dispatcher: 

message logging property 

mksis.logger.message.includeCategory.IM-NOTIFICATION=10 

exception logging property 

mksis.logger.exception.includeCategory.IM-NOTIFICATION=5

C HAPTER FIVE 

Customizing Workflow 

Item Presentation and Configuration 

5 

This chapter contains information on customizing the presentation of items to users, as 

well as configuring how they appear in reports. Information on customizing admin 

provided objects for workflows and documents is also provided. 



“Customizing Rich Content Fields” on page 216 

“Customizing Report Presentation Templates” on page 219 

“Customizing Test Verdicts” on page 234 

“Configuring Attachment Size Limits” on page 237 

“Configuring Limits for Queries” on page 238 

“Configuring Context Based Text Searching” on page 240 

“Setting Up Electronic Signatures” on page 241 

“Admin Provided Objects” on page 242 

“Using Type Properties” on page 245 

“Using Type Properties” on page 245 

187

Chapter 5: Customizing Workflow 


188 

The following table summarizes the available content for customizing items: 


Use an item presentation template to customize 

how items appear to users. 

Customize how reports are rendered through the 

use of report presentation templates. 

Customizing Item Presentation 

MKS Integrity’s presentation template designer allows you to customize the layout and 

display of items in your MKS Integrity database. The template designer incorporates drag 

and drop functionality to help you create a custom layout for a selected item type. Using the 

template designer, you can: 

create unique templates for viewing, editing, and printing items 

control the field order and position for each item type 

apply labels, field labels, field values, and images to the contents of a cell 

create borders and colors to group similar information 

apply background color, logos, and field visibility conditions to the presentation 

template 

create and delete grids, changing the number of the rows or columns in any grid 

apply custom cell properties for individual cells and allow cells to span adjacent 

columns 

minimize the requirement for scrolling by placing short fields on the same line 

preview a graphical representation of the template’s layout 


“Customizing Report Presentation Templates” on 

page 219 

Configure how users use attachments for items. “Configuring Attachment Size Limits” on 

page 237 

Configure limits for how items appear in queries. “Configuring Limits for Queries” on page 238 

Configure how users search for items in 


Ensure confidentiality of electronic records by 

using electronic signatures. 

Learn about and manage admin provided 

objects for workflows and documents. 

“Configuring Context Based Text Searching” on 

page 240 

“Setting Up Electronic Signatures” on page 241 

“Admin Provided Objects” on page 242


MKS Integrity saves your presentation template files in XML format in the database. 

MKS recommends creating and editing IPTs in the GUI; however, you can retrieve IPTs from 

the database for manual editing. Once you are finished editing these files, you can store them 

in the database. 

As an alternative to using the Admin Migration Wizard, you could also retrieve an IPT from 

a server, modify it, and place it in another server’s database for use. 

To retrieve IPTs from the database, use the integrity/im getdbfile command. 

To put IPTs in the database, use the integrity/im putdbfile command. 

NOTE The integrity putdbfile and getdbfile commands require the 

mks:AdminServer permission. The im putdbfile and getdbfile commands 

require the mks:im:AdminServer permission. 

For more information on using these commands, see the MKS Integrity Server 2009 


Understanding Template Designer 

Presentation templates are customizable layouts for displaying items in MKS Integrity. 



and drop functionality to help you create a custom layout for a selected item type. 

Certain tools also work in a modal fashion, that is, by clicking the tool on the toolbar you can 

operate in the selected mode on the design pane. Template properties and the preview 

function are also available on the toolbar. For more information on the available tools, see 

“Available Tools” on page 190. 

NOTE You can only work with presentation templates from the MKS Integrity 


The following shows the main features of the template designer interface. 

189


190 

Name Field 

Fields Filter 

Fields View Pane 

Property Pane 

Available Tools 

Toolbar 

Design Pane 

The presentation template designer includes tools to help you create a customized 

presentation for your items. Certain tools can work in two modes: 

clicking the tool to operate in the selected mode, for example, clicking the text tool to 

insert a text label into a cell 

dragging the tool onto the design pane to add the selected component, for example, drag 

the image tool to insert an image into a cell 

The following table summarizes the available tools: 

Tool Function 

Preview custom template. Displays Set Item Number dialog box for previewing 

template. 

Modify template properties. Displays Layout Properties dialog box where you 

can modify general properties, and default styles for text, cells, and grids. 

Delete selected item from design pane. 

Note: To completely delete field and return it to fields view pane, you must 

delete both Field Label and Field Value. 

Select components of template, including grids, cells, and labels. 

Create a new tab in the layout.

Tool Function 

Modifying Template Properties 


Clone the selected tab and insert it into the layout at the last position. 

Add new grid to template. Works in modal fashion by selecting tool or by 

dragging it. 

Insert text label into cell. Works in a modal fashion by selecting tool or by 

clicking/dragging it. 

Insert image into cell. Works in modal fashion by selecting tool or by clicking/ 

dragging it. 

Insert row above selected cell. To delete row, select cell in that row and then 

click . 

Insert row below selected row. To delete row, select cell in that row and then 

click . 

Delete row containing selected cell. 

Insert column to left of insertion point. To delete inserted column, first select cell 

in that column and then click . 

Insert column to right of insertion point. To delete inserted column, first select 

cell in that column and then click . 

Delete column containing selected cell. 

Join cell to right of selected cell. To join multiple cells across row, continue 

clicking until all target cells joined. 

Split cell. Only available if selected cell previously joined. 

Copy the selected grid. 

Paste the copied grid. 

Note: You cannot paste a grid that would result in a field appearing twice on the 

same tab. 

The Layout Properties dialog box allows you to configure styles and settings that can be 

applied globally to components of your template. 

191


192 

By using the styles and settings in Layout Properties, you can avoid having to configure 

detailed settings for each individual element of your template, and instead have a consistent 

style that is applied to all instances of a text, cell, or grid element. 

Using the properties pane, you can also override a global style setting by modifying 

individual values for a selected item. 

General Properties 

General properties include settings for background color, logo URL and alignment, and the 

layout for any fields that are not referenced by the template. 

To access general properties, click on the toolbar to open the Layout Properties dialog box, 

and click the General tab. The available settings for general properties display in the dialog 

box. 

Once you have modified the necessary general properties, you can click the next tab to 

configure additional properties. If you have completed your changes, click OK to save them 

and close the dialog box. 

The following table summarizes the available general properties: 

General Properties Description 

Background Color Specifies preferred background color of entire template. Select 

preferred background color by selecting: 

available named HTML color 

option for Custom… and then a color from the selectors for 

Swatches, HSB (Hue, Saturation, Brightness), or RGB (Red, 

Green, Blue) 

By default, background color is default as determined by 

operating system. 

Logo URL Displays image, such as corporate logo, as part of customized 

template. By default, no logo displays. 

Note: Logo file stored in public HTML directory of server and 

referenced using an URL. 

For more information, see “To add a logo” on page 212.

General Properties Description 

Text Styles 


Logo Alignment Specifies alignment of logo, if one selected, at top of template. 

Options are Left or Right. Option not available if no logo 

selected. By default, logo alignment set to Right. 

Unreferenced Fields Layout Specifies default layout for any fields not referenced by template. 

Available fields from field view pane not inserted into cell. Options 

are: 

Single field per row allowing only one field on row of 

template 

Multiple fields per row allowing more than one field on 

row of template 

By default, unreferenced fields layout set to Single field per 

row. 

Default setting for defaultprint template is Multiple 

fields per row. 

You can configure text styles for field labels, field values, and labels. To access text styles, 

click on the toolbar to open the Layout Properties dialog box, and click the Text Styles tab. 

The available settings for defined text styles display in the Layout Properties dialog box. 

Once you have completed your changes, click Apply to save your settings. To cancel the 

changes, click Revert. 

To create a new text style, click New. A new text style has a name, default font, size (weight), 

and color. You can then apply the new text style as you would for any of the defined text 

styles. 

NOTE When creating a style for a mandatory field, consider using a unique font 

color so users can quickly identify mandatory fields when editing items. The color is 

also used as an indicator for the tab name of a tab that contains the mandatory field 

(see “Working With Tabs” on page 209). 

To delete a text style that is no longer required, click Delete. 

NOTE You do not need to assign text styles. If no text styles are assigned, the default 

styles are applied. 

193


194 

The following table summarizes the available properties for text styles: 

Text Styles Properties Description 

Defined Text Styles By default, styles are defined for Heading, FieldLabel, and 

FieldValue. 

Heading style available to apply to any text you define as heading. 

FieldLabel and FieldValue styles available to apply to field 

labels and values. 

Name Display name of defined text style you select. By default, first one 

selected. 

Font Font for selected text style. Default font determined by operating 

system. 

Size Available font sizes from 8–72 points. Also font weight, such as Bold, 

or Italic, or both. Default font size determined by operating system. 

Color Font color from available system font colors. By default, color 

determined by operating system. 

Sample Sample of text, including font size, weight, and color. 

Default Text Styles Properties 

The default text styles provide the underlying style for labels, field labels, field values, and 

mandatory field labels. 

To access default text styles, click on the toolbar to open the Layout Properties dialog box, 

and click the Default Text Styles tab. The available settings for default text styles display. 

Use the default text styles to define how different text elements display by default in your 

template. 

Once you have modified the necessary default text style properties, click the next tab to 

configure additional properties. If you have completed your changes, click OK to save them 

and close the dialog box. 

The following table summarizes the available properties for default text styles: 

Default Text Styles Properties Description 

Default Label By default, label text style is system. 

Default Field Label By default, field label text style is system. 

Default Field Value By default, field value text style is system. 

Default Mandatory Field Label By default, mandatory field label text style is system.

Default Grid Properties 


Modifying the default grid properties affects the characteristics of all grids in the selected 

template. The available properties are background color, border, cell spacing, cell padding, 

pack, and fill. 

To access the default grid properties, click on the toolbar to open the Layout Properties 

dialog box, and click the Default Grid tab. The available settings for default grid properties 

display. 

Once you have modified the necessary default grid properties, click the next tab to configure 

additional properties. If you have completed your changes, click OK to save them and close 

the dialog box. 

The following table summarizes the available default grid properties: 

Default Grid Properties Description 

Background Color Background color of grid. Choose color by clicking list and 

selecting: 

available color 

custom option and then choosing a color from the selectors for 


Green, Blue). 



Border Thickness of border around grid from 0 to 99 pixels. By default, 

border is 0. 

Cell Spacing Distance between individual cells from 0 to 99 pixels. By default, 

cell spacing is 0. 

Cell Padding Distance between cell’s contents and cell margin from 0 to 99 

pixels. By default, cell padding is 0. 

Pack Specifies whether any extra horizontal space in grid is filled by last 

column (at far right). If pack is False, then extra horizontal space 

distributed across all columns. Extra horizontal space only occurs 

when Fill option set to True. By default, pack is True. 

Fill Specifies whether grid expands to fill available width in item 

display. If fill False, grid uses only space required to display its 

contents. By default, fill is True. 

Default Cell Properties 

Modifying the default cell properties affects the characteristics of all cells within the template. 

The available properties are background color, horizontal alignment, vertical alignment, and 

wrap. 

To access default cell properties, click on the toolbar to open the Layout Properties dialog 

box, and then click the Default Cell tab. The available settings for default cell properties 

display. 

195


196 

Once you have modified the necessary default cell properties, click the next tab to configure 

additional properties. If you have completed your changes, click OK to save them and close 

the dialog box. 

The following table summarizes the available default cell properties: 

Default Cell Properties Description 

Background Color Preferred background color of cell. Select preferred background 

color by clicking list and selecting: 

available named HTML color 

custom option and then choosing a color from the selectors for 


Green, Blue). 



Horizontal Alignment Horizontal alignment of cell contents (Left, Center, or Right). By 

default, horizontal alignment is Left. 

Vertical Alignment Vertical alignment of cell contents (Top, Middle, or Bottom). By 

default, vertical alignment is Middle. 

Wrap Wrapping of text within cell. By default, Wrap enabled. 

Tips for Working With Template Designer 

Consider the following when using the presentation template designer to create and edit 

templates: 

To have a standard corporate presentation for your items, you can create a generic 

presentation template and use that template as the basis for all other templates. You can 

then copy the generic template and make modifications that are specific to an individual 

item type saving each modified template and applying it to the appropriate type. 

You can select any naming convention for saving your templates, but associating the 

template name with the item type can simplify the task of assigning templates. 

You can create and set individual templates for viewing, submitting/editing, and 

printing items. For more information, see “Templates for Viewing, Submitting, and 

Printing Items” on page 197. 

While designing your template you can save your work without closing the template 

designer. The template designer does not include an undo function. Once you are 

satisfied with your work, you can save it to avoid losing your design. 

If you have made changes and cannot correct them, immediately close the template 

designer without saving to discard those changes. You can then reopen the earlier version 

of the template with all your desired changes intact and continue editing. 

Instead of modifying individual cell, text, and grid elements in the template, you can 

define and use styles through the Layout Properties dialog box. Styles allow you to make


a change in one place that applies to every instance where the style is applied in the 

template. 

When formatting a mandatory field, choose a unique font color so users can quickly 

identify mandatory fields when editing items. The color is also used as an indicator for 

the tab name of a tab that contains the mandatory field (see “Working With Tabs” on 

page 209). 

When choosing background color, remember the color of an individual cell overrides the 

color of the grid, and the color of the grid overrides the background color of the 

template. 

You can preview all your changes before saving them by clicking on the toolbar. Once 

you are satisfied with the changes you have made, click Save to retain those changes. 

You can only preview the template for the type of item you are working on. For example, 

if you are working from the Edit Type window on the Feature Request type, you cannot 

preview the template for the Bug type. 

When previewing a template, you must also enter an item ID number for an item that is 

of the same type as the template you are working on. For example, if you are working on 

the Feature Request type and want to preview the template, you must enter an item 

number for an item that is also a Feature Request. If you enter a number for an item that 

is of the wrong type or does not exist, an error message displays. 

When working in the template designer, you can preview the template only in the GUI. 

When working from the Edit Type window, you can preview the template in either the 

GUI or Web interface. 

Templates for Viewing, Submitting, and Printing Items 

You can create unique templates for viewing, submitting/editing, and printing items. 

Templates for viewing and submitting/editing items are intended for on-screen displays, 

and they can be designed with features such as a controlled field width to minimize scrolling 

and larger font sizes to improve readability. 

Templates for printing items are intended for paper output, and they can be designed with 

smaller font sizes, or without color or backgrounds, to make printing more efficient. 

Previewing Presentation Template 

When working in the presentation template designer, you can preview all your changes 

before saving them by clicking on the toolbar. You can only preview the template for the 

type of item you are working on. For example, if you are working on the Feature Request 

type, you cannot preview a template for the Bug type. 

When working in the template designer under Select User Interface, you can preview 

templates only in the GUI. From the template designer under Select Command, you can 

select the command the template is previewed with, for example, whether the template is for 

viewing an item, or for submitting and editing items. 

197


198 

When working from the Edit Type window, you can preview your presentation template by 

clicking Preview. You can choose to preview the template in either the GUI or Web interface. 

Whenever you want to preview a template, you must first set an item number ID through the 

Set Item ID dialog box. 

The item ID number must be for an item that is of the same type as the template you are 

working on. For example, if you are working on the Feature Request type and want to 

preview the template, you must enter an item number for an item that is also a Feature 

Request. If you enter a number for an item that is of the wrong type or does not exist, an error 

message displays. 

To preview a presentation template 

1 From the Set Item ID dialog box in the Item ID field, type an item ID number that 

corresponds with the type you are working on. 

IMPORTANT When previewing a template, you must enter an item ID number for an 

item that is of the same type as the template you want to preview. For example, if 

you are working on the Feature Request type and want to preview the template, you 

must enter an item number for an item that is also a Feature Request. If you enter a 

number for an item that is of the wrong type or does not exist, an error message 

displays. 

2 Under Select User Interface, select the interface for viewing (either the GUI or Web 

interface). 

3 Under Select Command, select the command you will use the template with, for 

example, will you use it for viewing an item, or for submitting and editing items. The 

available options are: 

View 

Submit/Edit 

Print 

NOTE Select Command options are only enabled when working from the 

presentation template designer. 

4 To preview the item in the selected template and user interface, click OK. 

Creating New Presentation Template 

You can create a new presentation template to provide a custom look for displaying, 

submitting, and printing items. Presentation templates are set according to the item type. 

You create a new presentation template through the Edit Type window using the New 

function.

To create a new presentation template 


1 From the MKS Integrity Administration Client, expand the Workflows and Documents 

node, and select Types. The display pane shows the available item types. 

2 Highlight the item type you want to create the new presentation template for, and select 

Type > Edit. The Edit Type window displays. 

3 From the Edit Type directory tree, select Presentations. The display pane shows the 

presentation template options and available templates. 

4 To open the template designer and begin designing your template, click New under 

Available Presentation Templates. The Create Presentation Template window displays. 

5 In the Name field, type the name for the new presentation template. By default, the name 

is template. The name you choose should help you to associate the template with the 

item type it is intended for. 

To save an initial version of the new presentation template, click Save. 

6 There is a default two-by-two grid available on the tab. To add or modify a grid, see 

“Working With Grids” on page 204. 

7 Add fields to the template (see “Adding Fields” on page 211). 

199


200 

8 Continue editing the template as required for your design. Depending on the design you 

create, you may need to carry out the following tasks: 

“Working With Cells” on page 205 

“Working With Labels” on page 206 

“Working With Images” on page 212 

“Working With Tabs” on page 209 

CAUTION The presentation template designer does not include an undo function. 

You can preview all your design changes before saving them. Once you are satisfied 

with the changes you have made, click Save to retain those changes. 

If you have made changes and cannot correct them, close the template immediately 

without saving it to discard those changes. You can then reopen the earlier version 


To preview your changes, click on the toolbar. You can only preview the template for 

the type of item you are working on. 

When previewing a template, you must also enter an item ID number for an item that is 

of the same type as the template you are working on. For example, if you are working on 

the Feature Request type and want to preview the template, you must enter an item 

number for an item that is also a Feature Request. If you enter a number for an item that 

is of the wrong type or does not exist, an error message displays. 

From the template designer under Select User Interface, you can preview templates only 

in the GUI. Under Select Command, you can select the command the template is 

previewed with. For example, whether the template is for viewing an item, or for 

submitting and editing items. For more information on previewing a template, see 

“Previewing Presentation Template” on page 197. 

To save your new template design, click Save.

A completed presentation template might look like the following: 


9 Once you have completed and saved all your changes, click Close. The template 

designer closes and the new template is added to the list of available presentation 

templates in the Edit Type window. You can open this template for further editing at any 

time. 

Keep the Edit Type window open for the next step. The next step sets the template for the 

item type you are editing. 

To set the new presentation template for the target type 

1 From the Edit Type window under Set Presentation Template, view the available 

templates: 

View Item is the presentation template that is used to display items on screen in 

MKS Integrity. By default, this is the default template. 

Submit/Edit Item is the presentation template that is used for submitting and editing 

items in MKS Integrity. By default, this is the default template. 

Print Item is the presentation template that is used for printing items. By default this 

is the defaultprint template. 

201


202 

For more information on templates for viewing, submitting and printing items, see 

“Templates for Viewing, Submitting, and Printing Items” on page 197. 

2 To preview the layout of an item in the assigned template, click Preview. The Set Item ID 


3 From the Set Item ID dialog box in the Item ID field, type an item ID number for the type 

you want to preview. 

IMPORTANT When previewing a template, you must enter an item ID number for an 

item that is of the same type as the template you want to preview. For example, if 

you are working on the Feature Request type and want to preview the template, you 

must enter an item number for an item that is also a Feature Request. If you enter a 

number for an item that is of the wrong type or does not exist, an error message 

displays. 

4 Under Select User Interface, select the interface for viewing (either the GUI or Web 

interface). 

5 To preview the item in the selected template and user interface, click OK. The target item 

displays in the template you selected. 

6 Once you have set and previewed the presentation template, click OK to save the settings 

and exit the Edit Type window.

Editing Presentation Template 


After you have created a presentation template, you can edit that template as required. You 

edit an existing presentation template through the Edit Type window using the Edit function. 

CAUTION The presentation template designer does not include an undo function. 

You can preview all your changes before saving them by clicking Preview. Once you 

are satisfied with the changes you have made, click Save to retain those changes. Try 

to save at frequent intervals to avoid losing your work. 

If you have made changes and cannot correct them, close the template immediately 

without saving it to discard those changes. You can then reopen the earlier version 


You can also edit the default template, though it is recommended that you edit a copy of the 

default template instead (see “Copying Presentation Template” on page 214). When editing 

the default template, you can modify or delete the Relationships and Attachments tabs (see 

“Working With Tabs” on page 209). However, other tabs, such as Change Packages and 

History, are not editable and are not viewable in the presentation template designer. 

To edit a presentation template 


node. 

2 Highlight the item type you want to edit and do one of the following: 

Select Type > Edit. 

Right click, and select Edit from the shortcut menu. 

The Edit Type window displays. 

3 From the Edit Type directory tree, select Presentations. Presentation template options 

and available templates displays in the display pane. 

4 From the list, select the template you want to edit, and click Edit. The Edit Presentation 

Template window displays with the selected template in the editing pane. 

5 Perform your editing tasks as required: 

“Working With Grids” on page 204 

“Working With Cells” on page 205 

“Working With Labels” on page 206 

“Working With Tabs” on page 209 

“Filtering Fields” on page 210 

“Adding Fields” on page 211 

“Working With Images” on page 212 

203


204 

6 Save your changes at frequent intervals. When you have completed your editing, click 

Save and then Close to close the template designer. 

Working With Grids 

You can set up new grids or modify the properties for an existing grid. The available 

properties are background, border, cell padding, cell spacing, fill, pack, and visibility. 

To set up a grid 

NOTE To modify an existing grid, highlight the target grid and go directly to step 4. 

1 From the presentation template designer, drag the grid tool onto the design pane to 

add a new grid to your template. The New Grid dialog box displays. By default, the 

template starts with a grid containing two rows and two columns. 

2 Set the size of the grid: 

In the Number of Rows field, select the number of rows required for the grid. 

In the Number of Columns field, select the number of columns required for the grid. 

3 Click OK to insert the new grid on the design pane. 

NOTE These procedures only describe how to modify selected grid components of 

the template. Through the Layout Properties dialog box, you can make global 

changes that apply by default to all grid components. For more information, see 

“Default Grid Properties” on page 195.

4 Modify the properties of the grid as required: 


For Background, specify the default background color of the grid. You can select a 

named color from the list, or click Custom and select from the Swatches, HSB, or 

RGB color selectors. Your systems determines the Default color. 

For Border, specify the width of the border around the outside edge of the grid. 

Values range from 0 to 99. By default, Border has the value 0. 

For Cell Padding, specify the distance between individual cells on the grid. 

Values range from 0 to 99. By default, Cell Padding has the value 0. 

For Cell Spacing, specify the distance between the cell contents and the cell 

margin. Values range from 0 to 99. By default, Cell Spacing has the value 0. 

For Fill, specify whether the grid expands to fill the available display space. If fill 

is set to True, the grid expands to fill the available width in the item display. If fill is 

set to False, the grid uses only the space required to display its contents. By 

default, Fill is enabled. 

NOTE Because it can result in an uneven border, it is preferable to use the 

Fill=False option only for grids at the bottom of the item display. 

For Pack, specify the horizontal space occupied by columns. If pack is set to True, 

then all columns are sized to fit their contents and the last column (at the far right) 

then occupies the remaining horizontal space in the grid. By default, Pack is 

enabled. 

For Visible When, specify a value to control the visibility of the selected grid. For 

example, if the grid is only visible when the assigned group is visible, select 

Assigned Group. The visibility of the grid takes priority over the visibility of an 

individual cell. 

The selected grid is immediately formatted according to your selections. 

5 To save your changes, click Save. 

Working With Cells 

You can modify the property for individual cells as required to customize your template 

design. The available properties include horizontal alignment, background, vertical 

alignment, visibility, and wrap. 

NOTE If you decide to leave empty cells in the template, empty space displays in the 

item presentation for both the GUI and Web interface. 

205


206 

To format template cells 

1 From the presentation template designer, select the cell you want to modify. The 

available properties display. 

NOTE These procedures only describe how to modify selected cell components of 

the template. Through the Layout Properties dialog box, you can make global 

changes that apply by default to all cell components. For more information on 

default cell properties, see “Default Cell Properties” on page 195. 

2 In the Properties pane, configure the following properties as required: 

For Background, specify the preferred background color of the cell by choosing an 

available named color, or by selecting the Custom option and choosing a color from 

the selectors for Swatches, HSB, RGB, or Default. 

For Horz. Alignment, specify the horizontal alignment of the cell contents, 

whether Left, Center, Right, or Default. 

For Vert. Alignment, specify the vertical alignment of the cell contents, whether 

Top, Middle, Bottom, or Default. 

For Visible When, specify a value to control the visibility of the cell. For example, 

if the cell is only visible when the assigned group is visible, select Assigned Group. 

For Wrap, specify how text wraps within the selected cell. By default, wrapping is 

enabled (true). To disable wrapping, select false. 

NOTE The visibility of the grid takes priority over the visibility of an individual cell. 


Working With Labels 

You can modify individual text labels, field labels, and field values to create the emphasis, 

readability, and layout you want for your template. Text labels are simple text strings defined 

by you.


Field labels are assigned by MKS Integrity according to your field definitions. You can 

override the text presented as a field label for purposes of the item display. 

IMPORTANT For purposes of item display, a field label also overrides the display 

name for a field. For more information on display names, see “Using Display 


The field value is directly associated with the field label. The content for field values is 

supplied by MKS Integrity according to the information submitted by users over the item’s 

life. You can format the style of presentation for field values, but you cannot change their 

content. 

To modify text labels 

1 From the presentation template designer, select the label you want to modify. 

TIP These procedures only describe how to modify selected text labels of the 

template. You can make global changes that apply by default to all text labels using 

the Layout Properties dialog box. For more information, see “Modifying Template 

Properties” on page 191. 

207


208 

2 In the Property pane, configure the following properties as required: 

For Text, type the text string you want to display as the label. For example, you 

could type Development Items to create a heading for your custom display. To 

restore the default text, delete the text string that you entered as an override and 

press ENTER; the default text string is restored on the label. 

For Text Style, specify the style you want applied to the label. By default, styles 

are pre-defined for Default, FieldLabel, FieldValue, and Heading. You can 

edit the pre-defined styles and create additional custom styles as needed. For 

example, you could apply the Heading style to set a label as a heading. For more 

information on text styles, see “Text Styles” on page 193. 

NOTE You can modify or delete the default styles or create new ones to suit your 

design. 

For Visible When, specify a value to control the visibility of the cell. For example, 

if the cell is only visible when the assigned group is visible, select Assigned Group. 


To modify field labels 

1 From the presentation template designer, select the field label you want to edit. 

TIP These procedures only describe how to modify selected field labels of the 

template. You can make global changes that apply by default to all field labels using 

the Layout Properties dialog box. For more information, see “Modifying Template 

Properties” on page 191.

2 In the Property pane, configure the properties as required: 


For Text Override, type the text string you want to display as the field label. For 

purposes of the presentation template, this text overrides the field label, that is the 

display name, as defined in MKS Integrity. 

For Text Style, specify the style you want to apply. By default, styles are predefined 

for Default, FieldLabel, FieldValue, and Heading. You can edit the 

pre-defined styles and create additional custom styles as needed. For more 

information on text styles, see “Text Styles” on page 193. 


To modify field values 

1 From the presentation template designer, select the field value you want to edit. 

TIP These procedures only describe how to modify selected field values of the 

template. You can make global changes that apply by default to all field values 

using the Layout Properties dialog box. For more information, see “Modifying 

Template Properties” on page 191. 

2 In the Property pane, modify the Text Style property as required. Select a style to 

apply to the field value. By default, styles are pre-defined for Default, FieldLabel, 

FieldValue, and Heading. You can edit the pre-defined styles and create additional 

custom styles as needed. For more information on text styles, see “Text Styles” on 

page 193. 


Working With Tabs 

In a presentation template, a tab provides a way for you to separate design elements onto 

different panels. 


You cannot add the same field more than once to the same tab. 

209


210 

You can add the same field to different tabs in the same template. 

You can view a comma-separated list of the tabs a field has been added to by removing 

the not in any tab filter (see “Filtering Fields” on page 210). The tab name appears in 

parentheses after the field name in the Fields View pane, for example, Attachments 

[Fields]. 

When there are mandatory fields on different tabs, the same visual indicator you have 

specified for mandatory fields is automatically used for the tab name to indicate to the 

user that the tab contains a mandatory field on a tab not currently displayed. 

Tab Operations 

The following table is a quick reference for performing tasks with tabs in presentation 

templates from the Presentation Template Designer (see “Creating New Presentation 

Template” on page 198 or “Editing Presentation Template” on page 203). 

Task Operation 

Create tab Click . The default name is new tab. 

Clone tab Select a tab, then click . The cloned tab is inserted into the 

last position in the layout (last tab). The source tab name is 

used for the default name, appended with clone. 

Rename tab Select the tab (click its name). Its properties display in the 

Property Pane. Change the value for the Name property. 

Reorder a tab Select the tab (click its name). Its properties display in the 

Property Pane. Change the value for the Position property. 

Use the same field on different tabs Ensure that not on any tab is not a restriction on the Fields 

Filter. That way the same field is available to drag to a cell on 

any tab. 

Enable tab check mark Indicators Select the tab (click its name). Its properties display in the 

Property Pane. Change the value for the Has Checkmark 

Icon property to True. 

Enabling this property causes users to see a check mark 

icon on the tab name if any field on a tab requires user input. 

Delete tab Select the tab (click its name). Click . The Delete Tab 

dialog displays to confirm before the delete operation is 

performed. 

Caution: You cannot undo deleting a tab. 

Filtering Fields 

The fields filter determines which fields are displayed in the Fields View pane of the 

presentation template designer. For more information on using the fields filter, see “Filtering 

Data” on page 18.

The following table describes the available field filters: 

Filter... Displays... 

not in any tab Fields not yet added to any tab. 

Adding Fields 


The Fields view pane displays the fields associated with the selection. The fields are available 

to be dragged onto the grid. 

To add a field to the template grid 

1 In the Fields view pane of the presentation template designer, select a field to add to the 

template, for example, Assigned Group. The available fields are determined by the 

selection you make in the fields filter list (see “Filtering Fields” on page 210). 

2 Drag the selected field into the target cell of the grid. The field displays as a Field 

Name{Field Value}. For example, if you select the Assigned Group field, the display 

appears as follows: 

By default, the field name shown by the template designer is the display name entered 

when the field was created. For more information on display names, see “Using Display 


3 Drag the field value to the adjacent cell. 

Note: Filter is on by default for each new template created. 

in tab Fields added to specified tab. 

visible in item type Fields visible in specified item type. 

mandatory in item type Fields mandatory in specified item type. 

visible in all types Fields visible in all types. 

of field type Specific field. 

4 Repeat this procedure until all desired fields are added to the grid. 

211


212 

NOTE Fields that remain in the Fields view pane are not referenced by the template. 

MKS Integrity assigns these fields a layout according to the default setting for 

Unreferenced Fields under General template properties. For more information, 

see “General Properties” on page 192. 

To delete a field completely and return it to the Fields view pane, you must delete 

the Field Label and Field Value pair for the target field. 

If you decide to leave empty cells in the template, empty space displays in the item 

presentation for both the GUI and Web interface. 

Working With Images 

The presentation template designer allows you to add logos and images to customize your 

presentation template. Images are added by entering a URL or Web address. You can 

reference image files that are in GIF, JPEG, or PNG format. 

You add a logo by modifying the general properties for the template. Logos are always 

added at the top of the template and can be aligned to the right or left edge. 

Images can be added to any cell in the grid by dragging the image tool to the target cell. 

You then type the URL or Web address for the target image, and it displays in the 

presentation template. 

Storing Image Files 

If you use the MKS Integrity Server to store the required images, the image files are made 

available to your template from the following directory: 

installdir/data/public_html/images 


Using an URL address, you can also access images on any public HTML server. 

To add a logo 

IMPORTANT Image files copied to the web directory are not backed up and must be 

restored manually. Therefore, it is important to retain copies of your required image 

files. 

1 Copy the image to the following directory on the MKS Integrity Server: 

installdir/data/public_html/images/logo 


The image is now available for use in your template. 

NOTE Using an URL address, you can also access images on any public HTML 

server.


2 To open the Layout Properties dialog box, click on the toolbar. The Layout Properties 


3 Under the General tab in the Logo URL field, enter the case-sensitive URL for the image 

location using the following syntax: 

http:///images/logos/ 

For example, an image file named corporate_logo.gif on the xyz-server would 

have the following URL: 

http://xyz-server:7001/images/logos/corporate_logo.gif 

4 In the Logo Alignment field, choose whether you want the logo to be aligned to the right 

or left edge of the template. Logos are always placed at the top edge of the template. The 

logo is placed at the top of the template. 


To add a new image 

1 Copy the image to the following directory on the MKS Integrity Server: 

installdir/data/public_html/images 

where installdir is the path to the directory where you installed the MKS Integrity Server, 

and images is a subdirectory to contain the images. The image is now available for use 

in your template. 

2 Click the image tool on the toolbar and insert the image placeholder in the target cell. 

3 In the Property pane, click the value field for Image URL, and enter the URL for the 

image location using the following syntax: 

http://images/ 

For example, the image file named corporate_logo.gif on the xyz-server would 

have the following URL: 

http://xyz-server:7001/images/corporate_logo.gif 

213


214 

4 If required for the Visible When property, specify a value to control the visibility of the 

image. To set a value, click the associated value field. For example, if the image should 

only be visible when the assigned group is visible, select Assigned Group. The image is 

placed into the target cell on the template. 


Copying Presentation Template 

You can copy a presentation template to use it as the basis for a new template. For example, 

you can create a generic presentation template to reflect your corporate standards, and use 

that template as the basis for all other templates. You can then copy the generic template and 

make modifications that are specific to an individual item type saving each modified 

template and applying it to the appropriate type. Copying a template is carried out from the 

Edit Type window using the Copy function. 

To copy a presentation template 



2 Highlight the item type for the presentation template you want to copy, and select Type 

> Edit. The Edit Type window displays. 



4 From the list, select the template you want to copy, and click Copy. The Create 

Presentation Template window displays the file name with the prefix Copy of. 

5 In the Name field, rename the template file as desired. The name you choose should help 

you to associate the template with the item type it is intended for. 

6 Make any design changes to the new presentation template as required. For more 

information, see “Editing Presentation Template” on page 203. 

7 When you have completed your changes, click Save and then Close. The new template is 

added to the list of available templates. You can now set the new template for the item 

type, or retain it for future use. 

Viewing Presentation Templates 

At any time, you can also view the presentation template settings for a given type. Viewing is 

carried out from the View Type window.

To view the presentation template settings for a type 




2 Select the item type you want to create the new presentation template for, and select 

Type > View. The View Type window displays. 

3 From the View Type directory tree, select Presentations. The display pane shows the 

selected template options under Set Presentation Template. 

NOTE You cannot modify any presentation template options while in view mode. 

4 Once you have finished viewing the information, click Close to close the View Type 

window. 

Deleting Presentation Template 

If you no longer want to use a template for a given item type, you can delete that template. 

You cannot delete a presentation template that is still set for an item type. You must first set a 

new template for the type and then delete the presentation template. For more information 

on setting the presentation template for an item type, see “To set the new presentation 

template for the target type” on page 201. 

Deleting a template is carried out from the Edit Type window using the Delete function. Once 

a template is deleted for a given type, you must set a new template—either a default template 

or one created by you. If you do not set a new template, MKS Integrity notifies you with an 

error message and automatically applies the default templates. 

NOTE You cannot delete the default templates (default and defaultprint) 

stored with MKS Integrity. 

To delete a presentation template 



2 Highlight the item type you want to delete the new presentation template for, and select 

Type > Edit. The Edit Type window displays. 



4 Under Set Presentation Template, set a new template (either a default or one created by 

you) for the item type you are editing. 

215


216 

5 From the list, select the presentation template you want to delete, and click Delete. The 

Confirm Delete Presentation Template dialog box displays and you are asked to confirm 

the deletion. 

IMPORTANT You cannot delete a presentation template that is still set for an item 

type. You must first set a new template for the type and then delete the presentation 

template. For more information on setting the presentation template for an item 

type, see “To set the new presentation template for the target type” on page 201. 

6 To delete the selected template, click Yes. The template is deleted and the name is 

removed from the list of available presentation templates. 

If no custom presentation template is assigned for a type, items display and are printed 

using MKS Integrity’s default and defaultprint templates. 

Customizing Rich Content Fields 

Rich content allows users to enhance the display of text in long text fields by adding 

formatted text, tables, background colors, images, and hyperlinks. To ensure a consistent 

look when viewing and printing rich content field data in different Web browsers, you can 

define screen and printer Cascading Style Sheets (CSS). 

HTML Elements and Attributes 

Rich content is expressed using a limited set of HTML elements and attributes. In the GUI 

and Web interface, rich content is applied using commands and toolbar buttons; however, 

HTML source can be copied and pasted into rich content fields. In the CLI and CSS files, rich 

content is applied and styles are defined using the HTML elements and attributes. Detailed 

information about CSS and HTML is beyond the scope of this guide. For more information, 

browse to: 

http://java.sun.com/j2se/1.5.0/docs/api/javax/swing/text/html/ 

CSS.html

http://www.w3.org/TR/CSS1 

Element Attributes 

Customizing Rich Content Fields 

Mandatory element that prefaces all elements in a rich content 

field. Other comments are removed. 

to align 

style, align 

 

size, width 

, , style 


218 

Element Attributes 

 

style 

style, rowspace, align, height, width, bgcolor, valign, 

background 

 

CSS Definitions 

NOTE For any elements that deal with size units, the attributes can only be specified 

as values in pixels or points. Values in inches cannot be specified. 

Each CSS file consists of a single HTML style element, which is a subset of the CSS 1.0 

specification. The element defines base styles to be applied to the rich content field; 

however, styles for supported HTML elements may also be defined. Regular or class styles 

cannot be defined, specifically: 

no generic (.foo { color: green; }) or regular classes (h1.foo {color: 

green;}) 

no ID based selectors (#1234 { color: green; }) 

no pseudo-classes (A:link { color: red}) or pseudo-elements (P:first-line { 

font-variant: small-caps}) 

Location of CSS Files 

Screen and printer CSS files (default.css) are stored on the MKS Integrity Server in the 

following directories: 

installdir/data/im/richcontent/styles/screen 

installdir/data/im/richcontent/styles/printer 

Removing and Transforming Style Definitions and Elements 

If any CSS selector or rich content field references an unsupported selector or element, the 

invalid style definition or element is silently discarded. 

In the Web interface and instances where rich content field data is displayed as a complete 

HTML page, such as the Items view, the definitions in the CSS file are transformed before the 

file is applied to the rich content field data. 


The screen and print CSS file are not applied to field data in reports. 

The printer CSS file is applied by the print item command.

Customizing Report Presentation Templates 

You cannot override a rich content field’s CSS using the type field override or report 

definition. 


Workflow and document reports are summaries of the data in your project. Reports are based 

on the standard and custom fields of types. Reports can be customized to include images, 

fonts, and hyperlinks, and can be saved as HTML files for viewing on the Web. Configuration 

management reports provide an analysis of projects, members, or individual archives. 

Reports and graphs can be printed or viewed on screen. 

Report presentation templates control the organization of report data based on groupings 

and sortings. The report tags you specify in a report presentation template represent the 

panels that a user sees after they select a presentation template in the Report Wizard. For more 

information on creating a workflow and document report, see the MKS Integrity 2009 User 


MKS Integrity provides sample templates you can use as a base to create custom templates 

that include only the data you require. Templates are saved in HTML or XML format for 

rendering in a Web browser. 


Creating a custom template or modifying an existing template requires knowledge of 

HTML/XML. This guide does not offer assistance with HTML/XML coding. If you are 

not familiar with HTML/XML, you should not attempt to create or modify a 

presentation template. 

If you create a custom template that is not based on an existing workflow and document 

report template, and if you want that report to display UTF-8 characters, specify UTF-8 

as the character set (HTML), or encoding (XML) in the report header. 

Creating report styles requires knowledge of CSS. This guide does not offer assistance 

with CSS coding. If you are not familiar with HTML/XML, you should not attempt to 

create or modify a CSS file. 

Workflow and document report elements are not removed when the MKS Integrity 

Server is uninstalled. 

You should not directly alter an existing presentation template or an example 

presentation template. Instead, you should create a copy of it and modify the copy to suit 

your needs. 

Report tags used in report presentation templates are case sensitive. 

If you create a custom template that is not based on an existing report template, review 

your HTML and report tags, and ensure that hyperlinks open in a new window. 

219


220 

To create a custom report presentation template 

The following procedure details how to create a report presentation template by beginning 

with a copy of an existing template. You can, however, create a template simply using the 

available tags. For it to appear in the Report Wizard, the template, along with screen and 

printer CSS files, logo image, and report template preview image must be placed in the 

correct directories. 

NOTE Once you move the modified files to the correct locations, the changes are 

automatically detected when you run the Report Wizard. You do not need to restart 

the MKS Integrity Server. 

1 Browse to the following directory: 

installdir/data/reports/recipes 


2 Select an example template to use, and make a copy of the file. 

3 Rename the copied example template to the name you want to appear in the Report 

Wizard. 

4 Open the template file in a text editor, and make the necessary modifications using the 

tags described in “Report Tags” on page 222. 

5 When you complete the necessary modifications to the template file, move it to: 

installdir/data/reports/recipes 

6 Create individual CSS files for the printer and screen styles. The sample names must 

match the report template name. 

a) Place the printer style in: 

installdir/data/reports/styles/printer 

b) Place the screen style in: 

installdir/data/reports/styles/screen 

c) Place the screen style sample in: 

installdir/data/reports/styles/screen/samples 

d) Place the printer style sample in: 

installdir/data/reports/styles/printer/samples 

7 Optionally, create an image in JPEG, GIF, or PNG format for a company logo to be used 

in the report. Place the image in: 

installdir/data/public_html/images/logos

Report Elements 


8 Optionally, create an image in JPEG, GIF, or PNG format for the new template. The 

image name must match the report template name. Place the image in: 

installdir/data/reports/recipes/images 

The following customizable elements make up a report: 

Element Description Location 

template file Template file determines layout and format 

of report and includes parameters that 

determine what data is contained in report. 

Template file must be coded in either 

HTML or XML and saved without an 

extension. 

If you are creating or working with an XML 

report template, encoding must be 

adjusted if you are using a special 

character set of any kind. 

cascading style sheet CSS determines how reports appear when 

viewed in a browser window or when 

printed. A CSS file is required for both 

screen style and printer style. 

Important: Creating a CSS file or 

modifying an existing CSS file requires 

knowledge of CSS. This guide does not 

offer assistance with CSS coding. If you 

are not familiar with CSS, you should not 

attempt to create or modify a CSS file. 

images A small image of report template so that 

users have a graphic representation of 

report and how it displays data. This is 

optional, but is helpful to users when 

deciding on a template to use. 

Note: Image must have same name as 

corresponding template file. 

Template files are located in: 

/ 

data/reports/recipes 

Screen style HTML samples are located in: 

/ 

data/reports/styles/screen/ 

samples 

Printer style HTML samples are located in: 

/ 

data/reports/styles/printer/ 

samples 

Style sheet samples are HTML files with 

same name as CSS and a .css.html 

extension. 

Screen style CSS files are located in: 

installdir/data/reports/ 

styles/screen 

Printer style CSS files are located in: 


styles/printer 

CSS files must be in CSS format with a .css 

extension. 


recipes/images 

Note: Supported image types are GIF, JPEG, 

and PNG. 

logos A logo image to display in report. installdir/data/public_html/ 

images/logos 

Note: Supported image types are GIF, JPEG, 

and PNG. 

221


Report Tags 

222 

The following tables show the available report tags and what they do. 

Report Tag Description 

Basic Tags 

Presentation template version. Allows future releases of report wizard to 

interpret and process older templates. Information is on first line in template 

and does not display in Report Wizard or generated report. 

Templates created in MKS Integrity 2006 use , templates 

created in MKS Integrity 2007 (or later) use , and so on. 

Presentation template description. Typically second line in presentation 

template. Displays with report name and image in Type panel of Report 

Wizard. 

You can include HTML tags in description. For example, to add bolding, 

specify: 

Project Description 

If you do not include tags, literal string displays in report, for 

example, Project Description. 

/ 

 

/ 

 

/ 

 

Everything between tags repeated for each item returned by specified query. 

Tag required for all templates. 

Everything between tags repeated by number of fields selected in Item Fields 

panel of Report Wizard. 

Use to prevent grouping fields 

from being reported (if using grouping tag). 

&fielddisplayname displays field name. 

&fieldname displays field value. 

&#fields displays number of fields iterated. 

Everything between tags is used to filter report contents. You can specify 

multiple filter criteria. For example: 

((field[Type] = "Defect") and (field[Project] 

= "Release 2.1")) 

filters for items with a type of Defect that are assigned to project Release 2.1.


Parameter Tags 


Displays user entered values, such as name and description of report in 

Parameters panel of Report Wizard. Instances of &name tag are replaced with 

value, for example: 

 

Use ampersand and parameter name (that is &reporttitle) to display 

value in template. 

type can be String for single line or MultiString for multiple lines. 

Special values: 

{fieldname} displays value of field in template 

{fieldname.name} displays field name in template 

Specifies keyword user can substitute with parameter value when running 

report (im runreport --param=value). Keywords and parameter values 

allow user to configure report content at runtime. 

For example, if report template includes: 

 

:%> 

 

and user specifies: 

im runreport --param=segmentname=SegmentA BugReport 

replaced with , which is then 

substituted during normal pre-item substitution. 

Displays name of MKS Integrity Server that items in report reside on. 

Displays port number of MKS Integrity Server that items in report reside on. 

Displays name and port number of MKS Integrity Server that items in report 

reside on. Tag builds http://hostname:hostport/ as part of 

MKS Integrity Server URL. 

Tag useful in HTML tags for displaying images or linking to other reports. 

 

 

 

 

Displays an item ID number as hyperlink. 

Displays header and footer on each report page. 

Achieved through use of and HTML table tags and CSS. 

Required CSS: 

thead {display: table-header-group} 

tfoot {display: table-footer-group} 

and tags must be placed before tag. 

A pre-processing tag that replaces itself with the current name of the builtin 

fields used in solutions, where FILENAME is the one of the English field names 

for the builtin field. Because it is a pre-processing tag, it must be enclosed 

within a tag itself 

223



224 

Attribute Tags 

Displays Date Format field in Attributes panel of Report Wizard, for example: 

 

MM/dd/yy expands to 01/30/09. 

MMM dd yyyy expands to Jan 30 2009. 

MMMM dd, yyyy expands to January 30, 2009. 

Displays Date Time Format field in Attributes panel of Report Wizard, for 

example: 

MM/dd/yy expands to 01/30/09. 

MMM dd yyyy expands to Jan 30 2009. 

MMMM dd, yyyy expands to January 30, 2009. 

hh:mm:ss expands to hour, minute, and second using 2


/ 

 

Segment Tags 


Displays Segment panel in Report wizard, for example: 

 

 

Can add any other tag between segment tags (i.e. , 

, etc.) and you can nest segment tags. 

Setting type=regular to type=relationship enables Relationship Field 

panel in Report Wizard, for example: 



226 

 

/ 

 

 

/ 

/ 

 

/ 

 


 

/ 

 

/ 

/ 

 

/ 

 

Attachment Tags 

Required to report on attachment information, with attachment tags placed 

between tags. 

Adding &attachmentFilter to attachment tag enables Attachment Filter 

section in Report Wizard to filter by file extension. 

Displays Attachment Fields panel in Report Wizard, allowing selection of 

attachment information. 

Adding &attachmentfielddisplayname displays name of attachment 

fields in report. 

Adding &attachmentfieldname displays value of attachment fields in 

report. 

Everything between tags displays when no attachments exist. 

Required to report on relationship attachment information, with attachment 

tags placed between tags. 

Time Entry Tags 

Required to report on time entry information, with time entry tags placed 

between tags. 

Displays Time Entry Fields panel in report wizard, allowing selection of time 

entry information. 

Everything between tags displays when no time entries exist. 

Adding &timeentryfielddisplayname displays name of time entry fields 

in report. 

Adding &timeentryfieldname displays value of time entry fields in report. 

Required to report on relationship time entry information, with time entry tags 

placed between tags.

Report Tags Description 

 

 

 

&verdictfilter 

&verdictfiltertype 

/ 

 

/ 

 

 

 

 

/ 

 

/ 

 

 

 

 

/ 

 

/ 

 

Test Result Tags 


Reports on test result information, with test result field tags placed between 

tags. 

The field tag can be one of the following: Session ID, Test ID, Annotation, 

Verdict, Modified By, Modified Date. 

Allows test results to be filtered by verdict or verdict type. 

Everything between tags displays above test results when test results exist. 

Everything between the tags displays when no test results exist. 

Reports on test step information for a test result, with test step field tags 

placed between tags. 

The field tag can be one of the following: Step ID, Annotation, Result, Modified 

By, Modified Date. 

Everything between tags displays above test steps when test steps exist. 

Everything between the tags displays when no test steps exist. 

Reports on attachment information for a test result, with attachment field tags 


The field tag can be one of the following: Name, Size, HTML Link, Created By, 

Date Added, Summary. 

Everything between tags displays above attachments when attachments exist. 

Everything between the tags displays when no attachments exist. 

227


Report Tags Description 

228 

 

 

 

/ 

 

/ 

 


 

/ 

 

 

/ 

 

 

Reports on item information for a test result, with item field tags between tags. 

The field tag can be any regular item field. 

Everything between tags displays above items when items exist. 

Everything between the tags displays when no items exist. 

Relationship Tags 

Displays Relationship Fields panel in Report Wizard. 

Tag functions same as but for 

relationships. Required for each relationship segment. 

Must specify L# for each relationship level, except for first level, for example: 

First level would be: . 

Second level would be: . 

Displays Item Fields panel in Report Wizard for relationship section. 

Tag functions same as , but 

for relationships. 

Adding &relationshipfielddisplayname displays related field name. 

Adding &relationshipfieldname displays related field value. 

Displays Sort By panel in Report Wizard for relationship section, allowing 

sorting of related items. 

Displays Relationship Filter panel in Report Wizard, allowing filtering of related 

items. 

Is same type of filtering available for field editablility and relevance rules. 

 

/ 

 

Test Result Tags 

Displays relationship flag in report. Replace flagname with name of flag. 

MKS recommends setting up flag name as parameter rather than be hardcoded 

in template. 

Everything between tags displays above related items when relationships 

exist.


/ 

 

/ 

 

/ 

 

/ 

 

/ 

 

 

 

 

 

 

header_and_or_footer_bl 

ocks 

 



Everything between tags displays below related items when relationships 

exist. 

Everything between tags displays when no relationships exist. 

Displays Group By in Report Wizard, allowing grouping of related items. 

For more than one level, include L# tag. 

Everything between tags displays above related items. 

Everything between tags displays below related items. 

To display specific relationship fields. 

Filter relationships within specified relationship field by flags, for example: 

 

Specify headers and footers for relationship details. Possible values for param 

are: 

header 

footer 

none 

Group items returned by specified relationship fields of specified item, where: 

Relationship level groupby tag prefixed with relationship to 

differentiate it from top-level groupby tag. 

L# tag specifies relationship level. L# tag not specified for level 1 

relationship. 

groupby_fieldname tag specifies field name in list of items. items are 

grouped by field values. Only one field can be specified per tag; allows 

header and footer per grouping. 

+ or - specify sort order of groups based on value of groupby field. + 

(default) indicates ascending, and - indicates descending. 

Multiple sets of relationshipgroupby tags can be specified within 

relationshipsdetail tag for multi-level grouping. For example, second 

set nested within first set and third set nested within second set. 

229



230 

 

 

 

 

group_computation_strin 

g 

 

 

computation_string 

 

 

/ 

 

 

/ 

 


Specify headers and footers for relationship level groups. Valid values for 

param are: 

header 

footer 

Following grouping related tags used at top-level may also be used as part of 

header and footer at relationship level: 

specifies name of groupby field. Valid in header and 

footer. 

specifies value of groupby field. Valid in header and 

footer. 

specifies total number of items in group. Valid in footer 

only. 

Specify calculation against relationships fields in group of items, where 

group_computation_string specifies group computed expression. 

These tags are within context of specific relationship level. Do not specify L# 

relationship level tag. 

Specify calculation against relationship fields within item, where: 

computedValueDisplayPattern specifies display pattern for computed 

value. 

computation_string specifies computed expression. 

L# tag specifies relationship level. L# tag not specified for level 1 

relationship. 

Required to report on relationship time entry information, with time entry tags 


Required to report on label information for related items, with label tags placed 

between tags. 

For more than one relationship level, include L# tag. For example, for label 

information on a second level relationship use: 


/ 

 

 

/ 

 

 

/ 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Change Package Tags 


Displays Change Package Type panel in Report Wizard, allowing selection of 

change package type to report on. 

Displays Change Package Attributes panel in Report Wizard to allow selection 

of CP attribute information in report. 

Attributes available depend on CP type chosen. 

Adding &genericcpfielddisplayname displays cp attribute name in 

report. 

Adding &genericcpfieldname displays cp attribute value in report. 

No tags to get relationship CP information. 

Displays Change Package Entry Attributes panel in Report Wizard. 

Used between / 

tags. 

Entry attributes available depend on CP type chosen. 

Adding &genericcpentryfielddisplayname displays cp entry attribute 

name in report. 

Adding &genericcpentryfieldname displays cp entry value in report. 

Display change package details for items included in report. 

These tags provide details for workflow and document management, and 

configuration management change packages. 

Display change package entry details for items included in report. 

These tags provide details for workflow and document management, and 


Display change package details for items included in report. These tags 

provide details for Implementer change packages. 

Display change package entry details for items included in report. These tags 

provide details for Implementer change packages. 

231



232 

Computed Expression Tags 

Performs calculation between fields in single item. For information on creating 

computed expressions, see “Computed Expression Types” on page 292. 

 

computation 

 

computation 

 


/ 

 

Performs calculation between fields in group of items. For information on 

creating computed expressions, see “Computed Expression Types” on 

page 292. 

Note: Group calculation must be aggregate expression. 

Specifies display pattern with computation against fields in single item, for 

example: 

22.0/7.0 

For more information on display patterns, see “Display Patterns” on page 28. 

Specifies display pattern with computation against fields in group of items. 

Grouping and Sorting Tags 

Displays Group By panel, allowing item grouping. Everything between tags 

grouped. You can nest grouping tags for any number of groupings. 

You can further detail grouping by specifying group names, values, and counts. 

groupby tag allows user to choose field to group by. 

To group data for multiple fields, include multiple groupby tags, for example: 

 

... 

 

... 

 

... 

 

... 

 

... 

 

Displays name of grouping field in report. 

Displays value of grouping field in report.


Displays count of grouped items in report. 


Displays Sort By panel in Report Wizard, allowing users to sort by selected 

item fields. 

Sort data for specific field, for example, report organizes data by sorting on ID 

field, starting from lowest ID to highest ID. sortby tag allows user to choose 

field to sort by. 

You may sort by multiple fields, separated by comma (,). Default sort order 

ascending (+); however, if necessary you can specify descending (-), for 

example: 

 


/ 

 

/ 

 

/ 

/ 

 

 


/ 

 

/ 

 

Grouping and Sorting Tags 

Label Tags 

Required to report on label information, with label tags placed between tags. 

The following label tags may be used: 

specifies the name of label. 

specifies the time the label was applied. 

Everything between the tags displays when no labels exist. 

Everything between the tags displays above labels when labels exist. 

Everything between the tags displays below labels when labels exist. 

Specify headers and footers for label details. Possible values for param are: 

header 

footer 

none 

Label Tags 

Required to report on label information, with label tags placed between tags. 

The following label tags may be used: 

specifies the name of label. 

specifies the time the label was applied. 

Everything between the tags displays when no labels exist. 

233



Customizing Test Verdicts 

234 

/ 

/ 

 

 


 

or 

% 

Test verdicts are used to indicate the outcome of a test, for example, passed or failed. 

You can add new test verdicts or change the standard verdicts that are shipped with 

MKS Integrity. The default verdicts are: passed, failed, and skipped. 

You must have the Admin permission to work with test verdicts. 

Working in the Test Verdicts View 

Everything between the tags displays above labels when labels exist. 

Everything between the tags displays below labels when labels exist. 

Specify headers and footers for label details. Possible values for param are: 

header 

footer 

none 

You customize test verdicts in the Test Verdicts view. To open the Test Verdicts view from 

the MKS Integrity Administration Client, expand the Workflows and Documents node, and 

select Test Verdicts. 

CLI EQUIVALENT tm verdicts 

Label Tags 

Solution Tags 

Required to report on item type properties. Possible values for 

solutionproperty are: 

CategoryFieldName

Through the Test Verdicts view, you can perform the following actions. 

Operation Procedure 

Create a test verdict See “To create a test verdict in the GUI” on page 235 

Edit a test verdict See “To edit a test verdict in the GUI” on page 236 

Creating a Test Verdict 

Customizing Test Verdicts 

View test verdict details Select the test verdict in the Test Verdict view and select Test 

Verdict > View Definition 

Reposition a test verdict Select the test verdict in the Test Verdict view and select Test 

Verdict > Reposition. The Reposition Fields dialog box displays. 

Select the field you want to move, and click Move Up or Move 

Down. 

Deactivate a test verdict See “Deactivating Test Verdicts” on page 237. 

Delete a test verdict Select the test verdict in the Test Verdict view and selected Test 

Verdict > Reposition. 

Note: You cannot delete the default test verdicts shipped with 


You can create your own test verdicts to use in addition to the default verdicts shipped with 


CLI EQUIVALENT tm createverdict 

To create a test verdict in the GUI 

1 From the Test Verdicts view, select Test Verdict > Create. The Create Test Verdict dialog 

box displays. 

2 In the Name field, type a new name for the test verdict. This is the name you use to refer 

to the field in MKS Integrity. The Name field allows 100 alphanumeric characters. 

In the Display Name field, MKS Integrity automatically enters the same selected name. 

Display names display in the pick list field for test verdicts. 

You can choose a different name to use as the display name. Display names are useful 

for clarifying the terminology presented to users on the interface. For more information, 

see “Using Display Names” on page 126. 

3 In the Description field, type a more detailed textual description of the test verdict, such 

as when it should be used. 

4 To customize the order the test verdicts display in a picklist field, click the Position tab to 

display the Position panel, and use the Move Up and Move Down buttons to change the 

order in the list. This order is used throughout MKS Integrity. 

235


236 

5 On the Image tab, associate an image with a test verdict. To associate an image with the 

test verdict, you have three options: 

To use your own icon image, select Use Custom Image, and click Select to browse 

for the image file. 

To use the predefined icon image, select Default Image. 

To associate no icon image with the user, select No Image. 


format and no larger than 16 x 24 pixels. 

6 On the Verdict Type tab, select the appropriate type for the test verdict. You can have 

multiple verdicts for each type. For example, you could create different verdicts for 

different types of failures. 

Editing a Test Verdict 

You can edit the details of the default verdicts shipped with MKS Integrity or of any custom 

verdicts you have added. 

CLI EQUIVALENT tm editverdict 

To edit a test verdict in the GUI 

1 From the Test Verdicts view, select the test verdict you want to edit. 

2 Select Test Verdict > Edit. The Edit Test Verdict dialog box displays. 

3 Edit the information as required. For details about the fields in this dialog box, see “To 

create a test verdict in the GUI” on page 235. 

NOTE To deactivate a test verdict, disable the Active check box. Deactivated verdicts 

do not display in picklist fields. You cannot deactivate the default test verdicts 

shipped with MKS Integrity. For more information, see “Deactivating Test Verdicts” 

on page 237 

4 To view a history of administrative changes for the test verdict, click the History tab. The 

record of changes displays. 

NOTE You cannot edit the verdict type for the default test verdicts shipped with 


5 To save your changes, click OK.

Deactivating Test Verdicts 

Configuring Attachment Size Limits 

Setting a test verdict to inactive means that in the GUI it is not displayed in any filtered 

picklists. By deactivating test verdicts, the picklist is filtered to display only those test verdict 

values that are currently active in MKS Integrity. 


Inactive test verdicts continue to display in fields, history, query filters, relevance and 

editability rules, field relationship filters, charts, and reports. 

Inactive test verdicts can be selected in query filters, relevance and editability rules, field 

relationships, charts, and reports. 

Inactive test verdicts cannot be selected in fields; however, fields retain inactive picklist 

values. 

If one or more active test verdicts are referenced in a trigger field assignment and you 

attempt to make one of those test verdicts inactive, an error message displays the test 

verdicts and the trigger(s) where the assignment occurs. The references in the event 

trigger(s) must be removed before making a test verdict inactive. 

Configuring Attachment Size Limits 

As administrator, you can control the maximum size of file that users can attach to any item 

in MKS Integrity. You can set a higher or lower limit by modifying the value for 

mksis.im.maxAttachmentSizeMB in the following file: 

installdir/config/properties/im.properties 

For example, the following setting limits the maximum size of an attached file to 4 MB: 

mksis.im.maxAttachmentSizeMB=4 

The minimum value for the attachment size is a limit of 1 MB, while the maximum value is a 

limit of 250 MB. By default, the limit for attachment file size is 4 MB. 

NOTE For Microsoft SQL Server, the attachment size should not exceed 25 MB. 

For more information on configuring the property for mksis.im.maxAttachmentSizeMB, 

see the MKS Integrity Server 2009 Installation and Configuration Guide. 

237


Configuring Limits for Queries 

238 

A query is a request to select and list the items that meet specific selection criteria. The 

selection criteria are a logical expression of specific values, or ranges of values, of the 

standard and custom fields of the item type. 

Charts are graphs that present trends over time or distributions of the data in your project. 

Charts are based on the standard and custom fields of item types. You can display trend 

charts as line or bar graphs, and distribution charts as pie or bar graphs. You can also display 

data in tabular form. 

MKS Integrity users have the ability to create complex queries that can demand significant 

system resources when run against a large database of items. Queries, reports, or charts that 

return a large result count can also demand significant memory resources from both the 

MKS Integrity Server and client. 

To address the item of complex queries, MKS Integrity also includes two further options: 

query timeout setting for groups configured through the Groups view in the 

MKS Integrity Administration Client 

maximum query item count setting configured through Workflows and Document > 

Configuration > Properties in the MKS Integrity Administration Client 

If you have specified query limits and a user runs a query exceeding those limits, 

MKS Integrity displays an error message to the user advising that the set limit has been 

exceeded. If the specified limits are relatively low and many of your users have large, 

complex queries, it may become necessary to modify the settings. 

As administrator, you can also stop a query that is actively running on the MKS Integrity 

Server. For more information on viewing and stopping query processes, contact 

MKS Customer Care. 

System Query Timeout 

By default, the system query timeout value is 15 seconds. This means that if no other options 

are set for group query timeouts or maximum query item count, individual queries are 

allowed to run for 15 seconds before the system stops them. 

Values assigned for query timeout represent the total time the query is allowed to run—the 

higher the value, the longer the query is allowed to run. For example, a system query timeout 

value of 20 seconds allows the query to run for 20 seconds, which is higher than the default 

value of 15 seconds. 

IMPORTANT A system timeout value of 0 means there is no limit on the time allowed 

for the query and queries are allowed to run until all results are returned.

Configuring Limits for Queries 

The system query timeout is modified using the im diag command. For more information 

on the im diag command and modifying the system query timeout value, contact 


Query Timeouts for Groups 

In addition to the system timeout value, you can limit the total time allowed for queries 

performed by members of any group. You can use group query timeouts to lower the system 

value by setting the group timeout value to a value lower than the system timeout value. By 

default, the query timeout value for groups is 0 allowing queries to run until all results are 

returned or until the system query timeout limit is met. 

IMPORTANT All users belong to the everyone group and the highest value of 0 (no 

limit) applies for all users. Therefore, to set effective query timeout limits for groups, 

you must first modify the query timeout value for the everyone group. 

The group query timeout option sets the time (in seconds) that any query can run for a 

member of the selected group. 

If a user belongs to multiple groups, the highest timeout setting is applied for that user. For 

example, if a user is in two groups, the Development group (with a 5 second query timeout 

value) and the everyone group (with a 10 second query timeout value), the 10 second limit is 

applied for that user. Therefore, any queries performed by that user are permitted to run for 

10 seconds before they are stopped. 

The group query timeout option is set through the Groups view in the MKS Integrity 

Administration Client. For procedures on setting the query timeout option for groups, see the 

MKS Integrity Server 2009 Installation and Configuration Guide. You can also modify the group 

query timeout setting while editing a group. 

Maximum Query Item Count 

Extremely large queries can demand significant memory resources from both server and 

client. To assist in the management of memory resources, you can set higher or lower limits 

for the number of results returned by a query. The maximum query item count sets a value 

based on the total number of results rather than on the time it takes the query to run. 

The maximum query item count is configured by modifying the value for 

mksis.im.queryGovernor through Workflows and Document > Configuration > Properties in 

the MKS Integrity Administration Client. 

The mksis.im.queryGovernor property governs the computation and return of queries run 

by MKS Integrity, and displays an error message if the number of items returned exceeds the 

specified limit. The setting applies to queries, reports, and charts. The minimum value is 100, 

and the maximum value is unlimited. By default, mksis.im.queryGovernor=10000. For 

239


240 

more information on configuring the property for mksis.im.queryGovernor, see the 


NOTE Setting the mksis.im.queryGovernor property controls the total of all 

pages independent of the client’s page size. 

Configuring Context Based Text Searching 

The text searching feature enables the use of context search indexes. Context search indexes 

are automatically built for text searches, if the underlying database supports it; however, the 

text search queries perform differently using a context search. 

The Search function allows users to carry out simple text searches of the MKS Integrity item 

database. The text search uses a search syntax similar to many common Web search engines. 

The search is carried out by the underlying database and the results are passed back to 


Text searches are available to users through both the GUI and the Web interface using the 

Search field on the toolbar. Text searches look only for information that is in short or long 

text fields. The search does not capture information in other types of fields, such as integer, 

pick, floating point, logical, date, user, or group fields. For more information on the text 

search feature, see the MKS Integrity 2009 User Guide. 

The property for configuring context based text searches is mksis.im.contextSearchOn set 

through Workflows and Document > Configuration > Properties in the MKS Integrity 

Administration Client. By default, mksis.im.contextSearchOn is set to true. 

IMPORTANT For information on the databases that support the text search feature, 

see the MKS Integrity Server 2009 Installation and Configuration Guide. 

If you are migrating an MKS Integrity database from a previous release, certain 

additional steps are required. For more information, see the MKS Integrity Server 

2009 Installation and Configuration Guide and the MKS Integrity Server 2009 Upgrading 


If your users have MKS Integrity queries from a previous release that rely on the old 

text searching behavior, you may want to disable the use of the context search 

indexes temporarily. Otherwise, you can leave context searching enabled if the 

underlying database supports it. 

Synchronizing Database 

If your database does not support the automatic tracking of text field updates in the context 

search indexes, you can set a property to specify an interval for synchronizing that database. 

The property is configured through Workflows and Document > Configuration > Properties in 

the MKS Integrity Administration Client as follows:

mksis.im.contextSearchSync=30 

Setting Up Electronic Signatures 

NOTE This property is ignored for databases that do not require it. Currently only 

the Oracle database uses it. 

Setting the mksis.im.contextSearchSync property forces an update within the time interval 

(in seconds) that you specify. By default, this value is set to 30 seconds—that is, a 

synchronization every 30 seconds. The minimum value is 10 seconds. 

Setting Up Electronic Signatures 

Electronic signatures are required by certain regulatory bodies to ensure the authenticity, 

integrity, and, when appropriate, the confidentiality of electronic records. MKS provides 

electronic signature support for MKS Integrity items by allowing you to require users to 

specify a user name and password when making certain changes to an item. For example, 

you could require a user to provide an electronic signature when they change an item’s state 

to Completed. 

CAUTION If a batch edit causes an item change that requires an electronic signature, 

the batch edit fails. 

Electronic signatures are set up using event triggers for workflows and documents. For 

general information on event triggers and how to use them, see “Overview of Workflow and 

Document Triggers” on page 355. The electronic signature trigger must be set up as a rulebased 

pre-event trigger. When a change to an item matches the rule, the user must enter user 

name, password, and any comments in the Signature Required dialog box. The server 

validates the user’s signature and records it in the item’s delta. 

NOTE 

If a scheduled trigger or a change to a relationship field in a related item causes 

an item change that would normally require an electronic signature, the 

signature requirement is bypassed. 

NTSS-only schemes are not supported for electronic signatures in MKS Integrity. 

In such cases, an error message informs the user and the error is logged. 

Customizing Electronic Signature Trigger 

MKS provides a pre-created script (signatureRequired.js) for the electronic signature 

event trigger. You may need to modify this script to use some advanced features of electronic 

signatures. The script is broken into separate functions that you can modify. Full 

documentation is available in the comments for those functions. 

241


242 

The pre-created script does the following: 

Requires a signature when an item is modified in a way that matches the trigger rule. 

You can restrict your signature requirements further through the isSigningRequired 

method. 

If the signature is valid, stores the signature information in the item history. You can set 

up additional logging using the signatureSuccess method. 

Allows all authenticated users to sign an item modification. You can restrict the users 

allowed to sign for an item modification using the signerRestriction method. 

Logs any signature failures. You can change what happens when an invalid signature is 

used, for example, sending an e-mail to an administrator. Use the signatureFailed 

method. 

Displays a message if no signature is provided. You can customize the message by 

changing the string used by the setSignatureRequired method. 

Displays a message if an invalid signature is provided. You can customize the message 

by changing the string used by the setRetrySignatureRequired method. 

Specific methods are available on the imIssueDeltaBean for signature authentication. For 

details on these methods, refer to the installed Javadocs under: 

installdir/data/documentation/javadocs/triggers/index.html 

However, you should not have to change any of the calls to these methods. 

Admin Provided Objects 

Admin provided objects are objects within the workflow and document object model that 

support solution definition and management, as well as workflow migration. 

Converting a user object to an admin provided object provides a number of benefits: 

it identifies the object as part of a solution, allowing users to distinguish between 

corporate standard user objects and those that other users have created (which may not 

be intended for general use) 

it allows MKS Integrity administrators, in addition to the creator of the original user 

object, to manage and update the object as needed 

admin provided objects are visible to all users, regardless of sharing permissions, 

avoiding potential issues with visibility 

Any object that is a component of a solution must be an admin provided object. The objects 

that can be converted to admin provided objects include: queries, charts, reports, and 

dashboards. Objects are specified as admin provided objects by setting the Admin Provided 

attribute when you create or edit the objects. If an object, such as a query, is required by a

Admin Provided Objects 

dependant component in the solution, such as a scheduled trigger, it is automatically 

registered as an admin provided object. Since triggers can only be defined and managed by 

MKS Integrity administrators and apply to all users, they are by nature part of a solution. 

Converting User Objects to Admin Provided Objects 

You may want to convert some user objects to admin provided objects to control access to 

them by users or so that they can be migrated. Access to admin provided objects is controlled 

by the CreateSharedAdmin permission. Admin provided objects are migrated using the 

Admin Migration Wizard (see “Testing Workflow With Admin Migration Wizard” on 

page 161). 

Note the following about converting user objects to admin provided objects: 

Converting a user object to an admin provided object is an irreversible operation based 

on the assumption that once converted, it is part of a solution and therefore should no 

longer be a privately controlled object that only the creator can manage. 

The creator of the original user object does not retain any special rights to that object 

after it is converted to an admin provided object. 

The creator of the original user object can still edit the admin provided object (if the 

server that hosts that object is not locked by an Admin Staging server) and delete the 

object if it is not referenced by other objects. These privileges are extended to MKS 

Integrity administrators. 

You can migrate admin provided objects as part of the admin migration process. 

Admin provided objects are subject to the lock when the production server is locked. 

Admin provided objects display in the MKS Integrity Administration Client. 

You can share admin provided objects with users who are not administrators to view or 

edit. 

You can convert user objects queries, charts, reports, and dashboards to admin provided 

objects. When those objects are created from the MKS Integrity Administration Client, they 

are always admin provided objects. However, objects created from the MKS Integrity Client 

can be converted to admin provided objects by editing them in the MKS Integrity Client, and 

then selecting the Admin Provided option. For details on editing queries, charts, reports, and 

dashboards, see the MKS Integrity 2009 User Guide. 

Once the object has been converted to an admin provided object, it appears in the 

corresponding subview in the Workflows and Documents view of the MKS Integrity 

Administration Client (see “Tree Pane” on page 14). For example, admin queries appear in 

243


244 

the Queries view that is a subview of the Workflows and Documents view (see “Tree Pane” 

on page 14). 

NOTE If you copy an admin provided object such as an admin query from the 

MKS Integrity Administration Client, the Admin Provided option is selected and 

cannot be changed. If you copy an admin provided object from the MKS Integrity 

Client, the Admin Provided option is cleared by default in the copy. You must select 

that option for the copied object to be an admin provided object. 

To manage admin provided objects in the MKS Integrity Administration Client 

1 Expand the Workflows and Documents node, and select the type of object you want to 

manage (Queries, Reports, Charts or Dashboards). The object view displays. 

By default, the data filter in the object view displays all admin provided objects of that 

type. You can search for a specific chart by typing in the text filter. For more information, 

see “Filtering Data” on page 18. 

2 From the object menu, select Run, Create, Copy, Delete, Edit, or View Definition. For 

information on performing those tasks, see the MKS Integrity 2009 User Guide. 

3 When editing an object or viewing an object’s definition, you can view all the objects that 

refer to it by clicking the References tab. You can then use that information to minimize 

the impact of editing or deleting that object. 

The References panel displays the following information: 

Object Type displays the type of object referencing the viewed object. Possible 

objects include: 

Admin Change Package Type 

Admin Chart 

Admin Dynamic Group 

Admin Project 

Admin Query 

Admin Report 

Admin Type (item) 

Chart (user charts) 

Column Set 

Field (includes computed fields, as well as editability and relevance rules) 

Group Notification Rule 

Item Presentation Template 

Query (user queries) 

Report

Trigger (includes trigger rules and assignments) 

User Notification Rule 

User Name 

Name displays the actual name of the object referencing the viewed object. 

Using Type Properties 

Creator displays the user ID that was logged as creating the object reference. 

Using Type Properties 

Type properties provide custom code (such as triggers and API) with attributes to read and 

to act on based on their values in MKS Integrity. 

Viewing Type Properties 

You can view type properties from the Type dialog box (see “Viewing Types” on page 93) in 

the MKS Integrity Administration Client. To view type properties, click the Type 

Properties node and use the data filter to search for the properties you want to view. 

If you have a solution installed on your MKS Integrity Server, there are likely several type 

properties with values that you can choose to modify as part of your customization of 


Defining Type Properties 

You can define type properties from the Edit Type (or Create Type) dialog box (see “Editing 

Types” on page 91 or “Creating Types” on page 84) in the MKS Integrity Administration 

Client GUI. To define type properties, click the Type Properties node and use the data 

filter to search for the properties you want to define. 

Type properties can be any name=value pairing. For example, a type property can be 

something that solutions or custom configured triggers can look for as a switch in the custom 

code. 

Type Property Fields 

Type properties contain the following fields: 

Name contains the name of the type property. 

Value contains the definition of the type property (see “Defining Type Properties” on 

page 245). 

Description contains an optional description for the type property. 

245


246 

You can perform the following operations on type properties from the type properties pane 

(see “Defining Type Properties” on page 245): 

Operation Procedure 

Operations for Type Properties 

Create type property Click Create. The Create a type property dialog box displays. 

For information on fields, see “Type Property Fields” on page 245. 

Edit type property Select the type property, and click Edit. The Edit a type property 



Copy type property Select the type property, and click Copy. The Copy a property 

dialog box displays. The default name is Copy of 

where is the name of the property copied. 


Delete a type property Caution: You cannot undo deletion of a type property. 

Select the type property, and click Delete. Click Yes to the 

confirmation dialog box.

C HAPTER SIX 

Projects 

Using Projects to Manage Change and Source 

6 

This chapter contains information on using projects with items and members. It is 

important to understand that projects used for managing workflows and documents 

behave differently from projects used for managing configuration management, and that 

the two kinds of projects do not interact with each other. 



“Configuration Management Projects” on page 262 

247

Chapter 6: Projects 


248 

The following table contains a summary of what workflow and document project 

information is available to you: 


Manage workflow and document projects, 

including creating and editing. 

Learn how to work with workflow and document 

projects in the Projects view. 

The following table contains a summary of what configuration management project 

information is available to you: 



“Projects View” on page 249 

Use workflow and document project metrics. “Managing Metadata for Workflow and 

Document Projects” on page 257 

Deactivate workflow and document projects that 

are no longer needed or in use. 

Assign an MKS Integrity administrator for a 

workflow and document project. 


Learn what interfaces are available to you for 

working with and administering configuration 

management projects. 

Organize your configuration management 

projects. 

Work with configuration management projects, 

such as creating, importing, importing members, 

dropping, restoring to a checkpoint, deleting, and 

restoring deleted projects. 

“Deactivating Workflow and Document Projects” 

on page 259 

“Assigning MKS Integrity Project Administrator” 

on page 260 

“Configuration Management Interfaces” on 

page 263 

“Organizing Your Projects” on page 263 

“Working With Projects” on page 265 

Use configuration management project metrics. “Using Configuration Management Project 

Metrics” on page 280 

Use configuration management subprojects. “Working With Subprojects” on page 282 

Share configuration management archives with 

configuration management projects. 

“Sharing Archives With Other Projects” on 

page 287 

When MKS Integrity is used for managing workflows and documents, a project is known as a 

workflow and document project. Workflow and document projects allow you to group items

Projects View 


according to undertakings that are defined in your organization. The projects created by you 

then become available for selection in the Project field—a default field in MKS Integrity. You 

can create projects and subprojects (or child projects) as needed. 

Once a project is created, you can edit it or add a subproject. You can also add a subproject to 

a subproject. If a project has subprojects, it has a plus sign (+) symbol to the left of it. To 

expand the project so you can see its subprojects, click + or double click the project name. 

Through the Project view, you can also designate users or groups as project administrators 

for a specified project. For more information on project administrators, see “Assigning MKS 

Integrity Project Administrator” on page 260. 

Using the MKS Integrity Administration Client, you can manage workflow and document 

projects from one convenient location: the Projects view. 

CLI EQUIVALENT im projects 

To open the Projects view from the MKS Integrity Administration Client, expand the 

Workflows and Documents node, and select Projects. The Projects view displays. For 

general information on the MKS Integrity Administration Client, see “Introduction” on 

page 10. 

The data filter (see “Filtering Data” on page 18) in the Projects view displays the names and 

descriptions of active projects by default; however, you can also configure the view to display 

the backing item ID (if specified), open image, and closed image. For more information, see 

“Creating Workflow and Document Projects” on page 252. 

With MKS Integrity, you can create projects and subprojects, as needed. You can even add a 

subproject to a subproject, as well as edit projects. If a project has subprojects, a + displays to 

the left. To expand the project so you can see its subprojects, click +. To launch a detailed 

view of the project, double click the name itself. 

NOTE To display entries in user and group fields when submitting items, at least 

one project must be shared with each available group, and the users and groups 

must have visibility into that project. 

If you double click a project, the Project dialog box displays for the selected project 

allowing you to view the properties. For more information on viewing projects, see “Viewing 

Workflow and Document Projects” on page 256. 

When you create a project, you can add additional information in a description field. For 

example, you can enter the project objective, start and end dates, name of the project 

manager, resources—anything that pertains to the project. 

249


250 

When creating a project, you can also designate users or groups as MKS Integrity project 

administrators for that project. For more information on project administrators, see 

“Assigning MKS Integrity Project Administrator” on page 260. 

Any changes you make in the Projects view have an immediate effect on your MKS Integrity 

database. The project list is sorted alphabetically. 

Available Menu Commands for Workflow and Document Projects 

Through the Projects view, you can: 

edit the details for existing projects 

view the details for existing projects 

delete projects 

create new projects 

create a child project 

reparent an existing project 

create a backing item 

edit the backing item 

view backing item details 

Setting Workflow and Document Project Visibility 

Project visibility allows you to control access to information throughout your organization. 

Through MKS Integrity, you can manage workflow and document projects that reflect your 

product development. You can use project visibility to ensure that sensitive information from 

one group is not viewed or modified by another group. All items and e-mail notification are 

subject to project visibility rules. 

When you create a project, you can select which user groups can see the project and all items 

assigned to the project. You can also define which user groups can see all projects in the 

database and which ones are restricted to see only certain projects. 

If a user is not a member of at least one group allowed to view the project, that user cannot 

view any items belonging to the project and its subprojects. For users to see a given 

subproject, they must have permission to see the associated parent project. Not all user 

groups with visibility to the project must see all the subprojects under the project. You can 

restrict the subproject visibility to fewer groups than you have chosen to be able to view the 

project. 

Based on project visibility, users are allowed to query the database only for items within 

projects that are visible to them. Projects not visible to users are not displayed in the query 

results. If users try to view an item within a project that is not visible to them, an error 

message displays.


If an item in one project is related to an item in a project not visible to the user, only the item 

ID of the related item displays in the Relationship view. In the History view, the user can see 

only that an edit occurred (Modified by on ). Users cannot see 

if the edit was an addition or removal of a related item. 

If an item previously invisible to users is reassigned to a project that is visible to users, they 

cannot see the previous project name in the History view. Instead, a symbolic Restricted 

Project value displays. 

Example 

Look at an example of three users: one is a member of the Word Processor R&D group, the 

second one is a member of the Spreadsheet R&D group, and the third one is a member of the 

Product Managers group. The assigned workflow and document project permissions are 

recursive and apply to subprojects as follows: 

Word Processor R&D 

Product Managers 

Spreadsheet R&D 

Product Managers 

According to project permissions, the member of the Word Processor R&D group can see 

only the Word Processor project and its subprojects, and all items associated with this project. 

According to project permissions, the member of the Spreadsheet R&D group can see only 

the Spreadsheet project and its subprojects, and all items associated with this project. 

According to project permissions, the member of the Product Managers group can see both 

the Word Processor project, the Spreadsheet project, their subprojects, and all items 

associated with both projects. 

251


252 


To display entries in user and group fields when submitting items, at least one workflow 

and document project must be shared with each available group, and the users and 

groups must have visibility into that project. 

When creating a new project as a root project, the Inherit Permissions from Parent option 

is unavailable. If you are creating a new project as a child project, you can select the 

Inherit Permissions from Parent option, if you want the permissions of the parent project 

to apply to your new project. 

Items that are not part of any project (the project field is blank) are visible to all users. To 

enforce project permissions, you must make the project field mandatory. 

If a user is not a member of at least one group allowed to view the project, that user 

cannot view any items belonging to the project and its subprojects. 

Based on project visibility, users are allowed to query the database only for items within 

projects that are visible to them. 

When creating a project, you can also designate users or groups as project administrators 

for that project. 

Creating Workflow and Document Projects 

You can create workflow and document projects to manage workflows and documents in 

MKS Integrity. Workflow and document projects allow you to group items according to 

undertakings that are defined in your organization. Projects created by you then become 

available for selection in the Project field—a default field in MKS Integrity. 

When creating a project, you can also designate users or groups as project administrators for 

that project. For more information on project administrators, see “Assigning MKS Integrity 

Project Administrator” on page 260. 

To create a workflow and document project in the GUI 

CLI EQUIVALENT im createproject 

1 From the Projects view (see “Projects View” on page 249), select Project > Create. The 

Create Project dialog box displays.


2 In the Name field, type a name for the new workflow and document project. This is the 

name the project is known by in MKS Integrity. This field allows up to 100 alphanumeric 

characters. 

NOTE The qualified project name in MKS Integrity uses a forward slash (/) 

delimiter for all operating systems. 

Underneath the Name field, the following message displays: Project is currently not 

backed by an item. Backing a project with an item allows you to link the current project 

to a specific item that stores project metadata and metrics. For more information, see 

“Managing Metadata for Workflow and Document Projects” on page 257. 

3 Using the Active option, specify whether a project is considered active or inactive in 

MKS Integrity. By default, the project is created active. To deactivate the project, clear 

the Active check box. For more information on deactivating projects, see “Deactivating 

Workflow and Document Projects” on page 259. 

4 To add a descriptive statement for the project, click the Description tab, and type your 

description. 

5 To set the parentage of the project, click the Parentage tab. The Parentage panel displays. 

The parentage of a project determines whether the new project is a parent or child 

project. By default, the new project displays as a parent or top-level project. If you want 

the new project to be a parent project, you can maintain the defaults. If you want the new 

project to be a child project, you can drag it to the parent project you want to add it to. 

6 To associate an icon image with the project field, click the Images tab. The Images panel 

displays the default options for open and closed project folders. 

To use the predefined icon images for either open or closed project folders, select 

Use Default Image. 

To use your own icon image that exists somewhere in your file system, select Use 

Custom Image, and browse for the image file. 

To associate no icon image with the project field, select No Image. 

If you choose to use a custom icon image, the image must be in GIF or JPEG format, and 

no larger than 24 (width) by 16 (height) pixels. 

253


254 

7 You can now set the project permissions, including which groups can view the project. 

To set the project permissions, click the Permissions tab. The Permissions panel 

displays. 

Only groups you add to the Permitted Groups pane can see the project. 

To allow all user groups access to the project, click


child project. In this case, the Inherit Permissions from Parent option on the Permissions 

panel is unavailable. 

7 To associate an icon image with the project field, click the Images tab. The Images panel 

displays the default options for open and closed project folders. 

To use the predefined icon images for either open or closed project folders, select 

Use Default Image. 

To use your own icon image that exists somewhere in your file system, select Use 

Custom Image, and browse for the image file. 

To associate no icon image with the project field, select No Image. 


format and no larger than 24 (width) by 16 (height) pixels. 

8 You can now set the project permissions, including which groups can view the project. 

To set the project permissions, click the Permissions tab. The Permissions panel 

displays. 

9 Select one of the following options: 

Inherit permissions from parent applies the same project permissions to the project’s 

children. 

Restrict access to these groups lets you limit the number of user groups that can see 

a subproject by eliminating selected groups from the groups authorized to see the 

project. 

If you select this option, you must manually choose which user groups can view the 

new project by moving them from the Available Groups pane and adding them to 

the Permitted Groups pane: 

To allow all user groups access to the project, click


256 

Editing Workflow and Document Projects 

You can edit the details of one workflow and document project at a time. 

To edit a workflow and document project in the GUI 

CLI EQUIVALENT im editproject 

1 From the Projects view (see “Projects View” on page 249), select the workflow and 

document project you want to edit. 

2 Select Project > Edit. The Edit Project dialog box displays. 

If the project is backed by an item, the item ID displays under the Name field. Backing a 

project with an item allows you link the project to a specific item that stores project 

metadata and metrics. For more information, see “Managing Metadata for Workflow 

and Document Projects” on page 257. 

3 Edit the project as necessary. For more information on the fields in this dialog box, see 

“To create a workflow and document project in the GUI” on page 252. 

4 To determine all objects that reference the project, click the References tab. For 

information on the contents of the tab, see “To manage admin provided objects in the 

MKS Integrity Administration Client” on page 244. 

5 To view a history of administrative changes for the project, click the History tab. The 



Viewing Workflow and Document Projects 

You can view workflow and document project details. The details are not editable, and you 

can only view the details for one project at a time. 

To view workflow and document project information in the GUI 

CLI EQUIVALENT im viewproject 


document project you want to view. 

2 Select Project > View Definition for a selected project. The Project dialog box 

displays. For more information on the fields in this dialog box, see “To create a workflow 

and document project in the GUI” on page 252. 

TIP You can double click a project in the Projects view to view it.


3 To determine all objects that reference the project, click the References tab. For 

information on the contents of the tab, see “To manage admin provided objects in the 

MKS Integrity Administration Client” on page 244. 

4 To view a history of administrative changes for the project, click the History tab. The 



Deleting Workflow and Document Projects 

You can delete a workflow and document project only if the project and its subprojects have 

not been referenced in any item. To delete an idle project that has subprojects, delete its 

subprojects first. 

To delete a workflow and document project in the GUI 

CLI EQUIVALENT im deleteproject 


document project you want to delete. 

2 Select Project > Delete. A confirmation dialog box displays. 


Reparenting Workflow and Document Projects 

After creating a workflow and document project, you can move it from one location within 

your project hierarchy to another by reparenting it. 

To reparent a workflow and document project in the GUI 


1 From the Projects view (see “Projects View” on page 249), select Project > Reparent. The 

Reparent Projects dialog box displays. 

2 Drag the workflow and document project you want to move to the target folder. 


Managing Metadata for Workflow and Document Projects 

Workflow and document projects enable you to organize and manage items by the projects in 

your organization; however, these projects do not capture in-depth metadata or metrics. By 

creating a Project item type then creating a Project item and linking it to a specific project, the 

257


258 

power and workflow of projects as items becomes available. Important metadata and metrics 

can be recorded in the Project item, for example, the assigned project manager, estimated and 

actual budgets (using computed fields), and important milestone dates. Linking a Project 

item to a project also reduces possible confusion about the details of projects in your 

database. 


A link between a Project item and a workflow and document project is optional. 

Projects and Project items can be used independent of one another; you do not have to 

create a Project type to use the Project field. 

Multiple types can back projects; however, only one item may back a given project. 

To enable the Items of this type back Projects option, you must be an administrator for 

the selected type. The Items of this type back Projects option can be disabled at any time. 

To create the item that backs a project, you must be an administrator for the selected 

project and belong to a group that has permission to create items of that type. 

For Admin Staging, you cannot stage items. Items that back projects created on a staging 

server will not be staged; you must recreate the items that back projects on the 

production server. Rules, queries, or computed fields that explicitly mention the item 

number that backs a project will not work after they have been transferred from the 

staging server to the production server. 

Example 

David, a project manager, manages several projects; however, the current workflow and 

document projects in MKS Integrity only allow him to organize and manage related items, 

such as Features and Defects, by project. David needs a way to capture important 

information about each project, such as milestone dates, and measure project success, for 

example, calculating whether his actual budget is higher or lower than his estimated budget. 

David creates a Project type and defines relevant fields that will allow him to capture 

relevant data and metrics. Next, David creates Project items for the projects he is managing 

and links them to the relevant projects in the Project field. 

David can now more effectively manage his assigned projects. The Project items he created 

allow him to capture project metadata in the available fields and calculate project metrics 

using computed fields. Using queries, charts, reports, and dashboards, David can 

communicate project status to his superiors and teams working under him.

To back a workflow and document project with an Item 

CLI EQUIVALENT im createtype and im edittype 


1 Create a Project type (see “Creating Types” on page 84), and enable the Items of this type 

back Projects option in the Attributes view. 

NOTE To make this option available, the Project field must be selected as a visible 

field for the type. 

2 Add relevant fields to the Project type to capture the metadata you want, for example, a 

user field that identifies the assigned project manager, date fields that record important 

milestones (Feature Freeze, Code Freeze, Project Completion), or computed fields that 

calculate budget information. For information on creating fields, see “Creating Fields” 

on page 127. 

3 Create a workflow and document project that you want to link to a Project item (see 

“Creating Workflow and Document Projects” on page 252). 

4 With the new project selected in the Projects view, select Item > Create Backing Item. The 

Create Item dialog box displays. 

NOTE 

If there is more than one type that can back a project, a Type Selection dialog box 

displays a list of types that have the backs a project option enabled and that you 

have view and modify permissions for. Select the type you want to back the 

project for, and click OK. 

From the Projects view, you can view or edit a project’s existing backing item by 

selecting the project, and selecting Project > View Backing Item Details or Edit 

Backing Item. 

5 Enter the information for the Project item in the fields provided (see the MKS Integrity 

2009 User Guide). 

6 Save the item. The item now holds the project metadata for the specified project in the 

Project field. 

7 Record information in the Project item as you would any other item. Use queries, charts, 

reports, and dashboards to monitor and communicate project status to others. 

Deactivating Workflow and Document Projects 

Setting a workflow and document project to inactive means that it is not displayed in filtered 

project lists, such as Project; however, an inactive project’s name can still be displayed using 

the inactive filter, if available. Inactive projects are denoted with the [Inactive] tag. 

259


260 

By deactivating projects, default project lists are filtered to display only those projects that are 

currently active in MKS Integrity. 

IMPORTANT Inactive values are not accepted in trigger assignments or as field 

values. If the project is referenced in a trigger assignment or as the default value in a 

project field, moving the project from active to inactive displays an error message. 

To deactivate a workflow and document project in the GUI 



document project you want to edit. 

2 Select Project > Edit. The Edit Project dialog box displays. 

3 To deactivate the project, clear the Active check box. 

4 To save the changes, click OK. The changes take effect immediately in the MKS Integrity 

database. In the Projects view, the inactive project is denoted with a blank entry under 

the Is Active column (if displayed). 

TIP You can right click the column header bar to add the Is Active column. 

Assigning MKS Integrity Project Administrator 

The super administrator is responsible for setting up MKS Integrity and therefore has access 

to all administrative objects, including users, groups, dynamic groups, workflow and 

document projects, states, types, fields, and triggers. The super administrator can also 

designate groups or individual users, or a combination of them, to be project administrators 

for selected projects in MKS Integrity. The super administrator can also convert user objects 

to admin provided objects (see “To manage admin provided objects in the MKS Integrity 

Administration Client” on page 244). 

MKS Integrity project administrators are allowed to edit and view workflow and document 

projects. Project administrators can also manage all child projects of the project they are 

approved for. Project administrators cannot edit projects assigned to another project 

administrator, and they can only create and delete subprojects—they cannot create top level 

projects unless they have been granted the CreateProject permission. 

Project administrators can also view all users, groups, and dynamic groups, but they can only 

edit dynamic groups membership for the projects they are assigned to. For more information 

on dynamic groups, see the MKS Integrity Server 2009 Installation and Configuration Guide.


Workflow and document projects are hierarchical; therefore, when creating a top level 

project, the creating super administrator is automatically set as the project administrator. 

When creating a subproject, the administrator list is empty because administrators of the 

parent project are, by default, administrators of its subprojects. The creating administrator 

can modify the default as required. 

If the assigned project administrators are granted the CreateProject ACL permission, they 

are allowed to create top level projects, as well as to delete any top level projects. 

MKS Integrity project administrators who are granted the CreateProject permission can 

also assign other project administrators. For more information on the CreateProject 

permission, see the MKS Integrity Server 2009 Installation and Configuration Guide. 

NOTE Project administrators are not allowed to assign themselves as administrators 

to any other projects or to assign others as project administrator, unless they have 

first been granted the CreateProject permission. 

The list of available users and groups contains all active and inactive members that have been 

imported into MKS Integrity; however, the available list does not necessarily include all users 

and groups available in the realm. For more information, see the MKS Integrity Server 2009 


The following table summarizes the basic functionality available to the project administrator: 

Project administrators can: Project administrators cannot: 

Create new subproject (child project) in workflow 

and document project they are assigned to. 

Edit workflow and document projects they are 

assigned to, including images, descriptions, and 

permissions. 

Edit project memberships in corresponding 

dynamic groups. 

View users, groups, dynamic groups, and 

projects. 

Example 

Create top level workflow and document project 

or create users, groups, dynamic groups, states, 

types, fields, or triggers. 

Edit any other process and control objects such 

as users, groups, states, types, fields, or triggers. 

View states, types, fields, or triggers. 

Delete subproject they have created. Delete top level workflow and document project. 

Create top level workflow and document project 

(if CreateProject permission is allowed). 

Assign another project administrator or view 

administrator information for project they do not 

administer. 

Neil is the project administrator for the SourceCode project. By extension, he is also the 

project administrator for the two subprojects under SourceCode (Client and Server). 

If the super administrator also grants Neil the CreateProject permission, Neil is allowed to 

create top level projects and assign other MKS Integrity project administrators at the time the 

261


262 

project is first created. With the CreateProject permission, Neil can also assign another 

project administrator to the SourceCode project. By extension, all assigned project 

administrators for the SourceCode project are allowed to edit the Client and Server 

subprojects. 


Only the super administrator can automatically assign a project administrator in 


Project administrators are not allowed to assign themselves as administrators to any 

other projects or to assign others as project administrator, unless they have first been 

granted the CreateProject permission. 

To assign an MKS Integrity project administrator 


1 From the Projects view, select the project you want to create a project administrator for. 

2 Select Project > Edit. The Edit Project window displays. 

NOTE Only the super administrator is automatically allowed to assign project 

administrators in MKS Integrity. Project administrators can assign another project 

administrator only if they are first granted the CreateProject permission. 

Through the Create Project window, the super administrator can also assign a 

project administrator while creating a new project. 

3 Click the Administrators tab. The Administrators panel displays. 

4 To assign a specified user or group as a project administrator, see “Filtering Data” on 

page 18. You can assign more than one user or group as a project administrator. 

5 To accept the changes, click OK. The selected user or group is assigned as a project 

administrator. Users and groups displayed in the Assigned column are then allowed to 

manage the selected project in MKS Integrity. 


Software management functionality provides configuration management projects to manage 

members. Configuration management projects are separate from workflow and document 

projects, and are accessed through all interfaces (see “Configuration Management Interfaces” 

on page 263).

Configuration Management Interfaces 


Configuration management functionality is accessible in three interfaces: MKS Integrity 

Client, Configuration Management Web interface, and command line interface (CLI). 

The MKS Integrity Client uses the concept of a Tabbed View Interface (or TVI). A TVI is a 

visual arrangement of multiple views in a single window. For more information on using and 

customizing this interface, see the MKS Integrity 2009 User Guide. All configuration 

management commands are available in the GUI. 

NOTE In this guide, all GUI procedures 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 GUI. 

The Configuration Management Web interface allows you to perform key project 

management tasks. You do not need to install the MKS Integrity Client to access the 

Configuration Management Web interface. To open the Configuration Management Web 

interface, type the name and port number of the MKS Integrity Server in the location or 

address field of your Web browser, for example, xyzBusiness.com:9001. From the 

MKS Integrity Server home page, click the link for Start MKS Integrity Web Interface. 

The CLI allows you to enter MKS commands in a text-based interface. Primary use of the CLI 

is for scripting. It is also useful for environments where there is no GUI. The CLI can be used 

to manage your configuration management projects, Sandboxes, and members, and to 

configure configuration management functionality. To access the command line interface 

from a computer running Windows, from the Start menu select the MS-DOS or Command 

Prompt (depending on the version of Windows). 

You can also choose to work alternately between the GUI and the CLI, because all 

configuration management commands are available in these two interfaces. For example, you 

can perform a command in the CLI and view the results in the GUI. 

Organizing Your Projects 

Before you begin using MKS Integrity to manage the configuration management projects in 

your development environment, you should take a careful look at how projects and 

directories are organized in your repository. The recommended way to use MKS Integrity is 

also the easiest. If you follow these guidelines, MKS Integrity requires no special 

configuration: 

Put all the files for a project in a single directory or directory tree. 

Create the project in the directory at the top of the tree. 

263


264 

Single-tree Projects 

Most sites adopt hierarchical directory structures for related files, because the structure 

reinforces the relationship between files and makes them easier to locate and work with. A 

preferred approach in software development is to place the project makefile at the root of a 

directory tree that includes subdirectories for code files, resources, and header files. This 

example shows one of the simplest and most frequently used structures. 

MKS Integrity records the location of all members relative to the project directory (that is, the 

directory where the project file resides) at the top of the project directory tree. When you 

create a Sandbox for a single-tree project, MKS Integrity clones the project directory tree in 

the Sandbox directory and maintains the relative locations of all members. 

Problems can arise when separate project trees are located in the same directory for the 

purpose of sharing archives. As a result, MKS strongly recommends you keep top-level 

projects in separate directories so that each project can have separate security, configuration, 

and administrative information controlled by separate ACLs. For more information on 

project ACLS, see the MKS Integrity Server 2009 Installation and Configuration Guide. 

You can still share archives across projects that are in separate directories by using shared 

subprojects or common projects. For more information, see “Sharing Archives With Other 

Projects” on page 287. 

IMPORTANT If you have developed a project structure that includes multiple projects 

in the directory, you should contact MKS Customer Care for detailed information on 

how to work with this situation. 

Archives in File System Repositories 

If you are using a file system repository, when you use a single-tree type of project 

organization, you need no further directory configuration. MKS Integrity uses its internal 

defaults and puts archives for the project members in subdirectories—named rcs—in the 

directory where each member resides. 

The final directory tree for the project looks like this:

Code 

Directory 

rcs 

Directory 


When you create a Sandbox, RCS directories are not cloned in the Sandbox directory. 

Working With Projects 

When you are ready to place a related group of files under MKS source control, the first step 

is to create a project. A project is a container for a group of files that reside on the 


Once you create a project, you can add files to it making them members of that project. 

Organizing your files in a project allows you to perform configuration management 

operations on the files as a group. 

Projects are created using the MKS Integrity Client and reside on the MKS Integrity Server. 

Users can then create Sandboxes that point to the project, and all operations are performed 

from those Sandboxes. 

Creating Projects 

Project 

Directory 

Resource 

Directory 

rcs 

Directory 

rcs 

Directory 

When creating a project, you only create the project container. To add files, or members, to the 

project, you must create a Sandbox on your client machine that points to the project and then 

add the project members through that Sandbox. For more information on creating Sandboxes 

and adding project members, see the MKS Integrity 2009 User Guide. 

To create a project, select Project > Create. 

Keep the following points in mind when creating a project: 

Header 

Directory 

rcs 

Directory 

When you specify the name of the new configuration management project, 

MKS Integrity automatically assigns the .pj file extension. If you specify a .pj file 

extension in uppercase or mixed case, MKS Integrity replaces that file extension with the 

correct lowercase .pj file extension. If you specify a file extension other than .pj, 

MKS Integrity appends the .pj file extension to the file name. For backwards 

265


266 

compatibility, you can import projects and subprojects that do not have the .pj file 

extension. 

A single configuration management project name can be used only once in the same 

location. 

For case-insensitive repositories, MKS Integrity does not distinguish between 

configuration management project names differing only in case. For example, if 

project.pj already exists in C:/Aurora_Program, you cannot create PROJECT.pj in 

C:/Aurora_Program. This results in an error and MKS Integrity asks you to specify a 

different path and file name, or a different project name. 

To create a project using the CLI 

1 Log in to the MKS Integrity Server by entering the command: 

where 

si connect --hostname=value --port=value --user=value --password=value 

--hostname=value specifies the MKS Integrity Server name 

--port=value specifies the port number 

--user=value specifies your user name 

--password=value specifies your password 

MKS Integrity establishes a connection with the server. 

2 Enter the command: 

si createproject projname 

where projname specifies the path on the server and the name of the project you want to 

create. MKS Integrity confirms that the project is created. 

NOTE MKS Integrity creates file paths and project names based on the server’s 

operating system. In Windows, always use back slashes when specifying file paths. 

In UNIX, always use forward slashes. 

For more information on the si createproject command, see the MKS Integrity 

2009 CLI Reference Guide for Configuration Management. 

Importing Projects 

Import configuration management projects if you need to do the following: 

restore projects that were dropped in earlier versions of MKS Integrity (including 

MKS Source and Source Integrity) 

migrate projects from Source Integrity Standard (an earlier version of MKS Integrity) 

Importing a configuration management project registers it with the MKS Integrity Server. 

Once a project is imported, MKS Integrity commands can be performed upon it.

To import a project, click Project > Import. 


NOTE The Import Project command is not supported for database repositories. For 

information on how to import projects for database repositories, see the Database 

Repository Migrator document. 

When importing projects, the import process automatically creates histories for any nonarchived 

members and checkpoints any non-archived projects. Before you import a project, 

the project files must already reside in the server repository. 

CAUTION MKS Integrity does not support encrypted archives. If your existing 

project has encrypted archives, you must first decrypt the archives before importing 

and registering the project with the MKS Integrity Server. 

Importing From Earlier Versions 

If you are importing a configuration management project from an earlier version of 

MKS Integrity, once a project has been imported you may not perform commands on it using 

an older version of MKS Integrity. If for some reason you need to use an earlier version of 

MKS Integrity on a project, first drop the project using the Drop Project command. The 

project must be re-imported before it can be used again with this version of MKS Integrity. 

If you are importing an existing Source Integrity Standard project that includes out-of-tree 

members or subprojects, MKS Integrity automatically detects these and imports them into 

the newly registered project. A project member or subproject is considered out of tree when it 

does not reside in the project directory. 

If you are re-importing a dropped project to its former repository location, the project 

namespace must first be reclaimed. For more information on reclaiming project namespaces, 

see “To run server diagnostics in the CLI” on page 417. 

Example 

The xyzBusiness company has an existing project in Source Integrity Standard. This project 

needs to be migrated to the new MKS Integrity Server. To carry out the import operation, the 

administrator first copies the project directory to the new host MKS Integrity Server and then 

imports it. 


If your connection to the MKS Integrity Server is disconnected while you are browsing 

for a file, the file browser does not show any files or directories. 

You cannot import a configuration management project that is already registered. 

For case insensitive repositories, MKS Integrity does not distinguish between 

configuration management project names that differ only in case. For example, if 

project.pj is already registered in C:/Aurora_Program, you cannot import 

267


268 

PROJECT.pj into C:/Aurora_Program. This results in an error and MKS Integrity does 

not import the project. 

The processing of this command may take some time, since it traverses all subprojects in 

the imported project and may perform various operations on them, such as 

checkpointing. 

The administrator may restrict the path names of configuration management projects 

being imported on the server. This is done through the si.serverRoot property in the 

si.properties file on the MKS Integrity Server. If this is set, then any project location 

given must be under that directory. For details, see the MKS Integrity Server 2009 


To import a configuration management project using the CLI 

Use the command: 

si importproject projname 

where projname specifies the path and name of the project you want to import. 

NOTE For more information on the si importproject command, see the 

MKS Integrity 2009 CLI Reference Guide for Configuration Management. 

Importing Members 

When you add a member, it is automatically registered with the MKS Integrity Server; 

however, members added with Source Integrity Standard (an earlier version of 

MKS Integrity) or server resident files must be imported to register them with the 


Do not use the Import Member command to add members that are dropped from a project. 

Instead, use the Add From Archive command. For more information on this command, see 

the MKS Integrity 2009 User Guide. 

NOTE The Import Member command is not supported for database repositories. 


The configuration management project must be registered with the MKS Integrity Server 

before the member is imported. 

Before you begin the import operation, the files to be imported must first reside on the 


Archives cannot be imported. When selecting a file to import, select the working file in 

the project directory. If the working file does not exist, select the project directory and 

enter the file name.


You cannot import members into a shared subproject. For more information on shared 

subprojects, see “Adding Shared Subprojects” on page 284. 

Example 

You have a directory that contains numerous files and subdirectories, and you want to add 

this directory to a configuration management project. First, make sure the target directory 

resides on the MKS Integrity Server. Then use the Import Member command to add the new 

directory as a member to your project, selecting the Recurse Into Directories option to include 

all of the associated files and subdirectories in the project. 

To import a member in the GUI 

1 .From a Project or Sandbox view, select Member > Import. The Import Members Wizard 

displays. 

2 To import a list of files to the project, click Add File. To import a directory and its 

contents, click Add Directory. The Select One or More Members to Import to the Project 


3 Select one or more files from the displayed list navigating to the desired directory if 

necessary. 

NOTE If your connection to the MKS Integrity Server is disconnected while you are 

browsing for a file, the file browser does not show any files or directories. 

4 To add the operation to a change package, from the Change Package list select a change 

package. To create a change package, click Create. For information on how to create a 

change package or specify a change package when performing an operation, see the 


5 Click OK. The files are added to the members list. To remove files, select the files, then 

click Remove. 

6 To modify the Import Member options, click Options. For detailed information on the 

Import Members Wizard options, see the online help. 

7 Click Finish to import files without specifying options. The Import Member dialog box 

displays. 

8 If the member is being imported to a deploy project, specify the deploy type for the 

member in the Deploy Type field. This field only displays if you are licensed to use 

Deploy. For more information, see the MKS Deploy 2009 Administration Guide. 

9 To modify the Import Member options, click Options. For detailed information on the 

Import Member options, see the online help. 

10 To complete the operation, click OK. To make changes, click Back. The members display 

in the Project or Sandbox view. 

269


270 

To import a member using the CLI 


where 

si import --project=value filename 

--project=value specifies the path and name of the target project 

filename specifies the path and name of the non-member files to be imported to the 

project 

NOTE Include the server-side path and path to the working file. Do not include the 

path to the archive. 

Other command options for si import include: 

--author=name specifies an author name for the file 

--binaryFormat specifies that the file contains unprintable characters or lines too long 

to be handled by text editors 

--textFormat specifies that file is in a format expected by text file editors 

--revision=value specifies a revision number for the member 

--description=value specifies a description of the member 

--[no]createSubprojects specifies whether subprojects are created 

--[no]unexpandKeywords specifies whether literal values in the revision are replaced 

with keywords 

--[no|confirm]recurse imports members that exist in the specified directory location 

recursively (if you want MKS Integrity to confirm the recurse option, use 

--confirmrecurse) 

NOTE For a complete list of command options, see the MKS Integrity 2009 CLI 

Reference Guide for Configuration Management. 

Dropping Projects 

When a configuration management project has outlived its usefulness or just does not belong 

on the MKS Integrity Server anymore, you can remove it. 

To drop a configuration management project means that the projectis no longer registered 

with the MKS Integrity Server. Dropped projects can still be accessed as read only from the 

Change Package and Locks views until the project is purged or reclaimed by your 

administrator.


To drop a configuration management project, select a project in the Projects view, and click 

Project > Drop. 

CAUTION If a project is dropped and any Sandboxes or variants are associated with 

it, those Sandboxes or variants no longer function. 

Dropping a configuration management project unregisters it from the MKS Integrity Server, 

but it does not delete the project. Dropped configuration management projects can be added 

back into MKS Integrity. 

For more information on adding projects, see the MKS Integrity 2009 User Guide. 

To drop a project in the CLI 


si dropproject projname 

where projname specifies the path and name of the project you want to drop. 



Restoring Project to Previous Checkpoint 

The Restore Project command allows you to restore a configuration management project to a 

previously checkpointed revision. Restoring a project is useful when development must 

revert back to an earlier version and there are no plans to proceed from the current version of 

the project. Any further development then proceeds from the restored project revision. The 

Restore Project command can be applied to both normal and variant projects. 

NOTE The Restore Project command can potentially restore and checkpoint dropped 

subprojects that existed at the target revision, even if they are not currently a 

member of the project. 

To restore a project through the GUI, select the configuration management project that you 

want to restore in either a Project or Sandbox view, and select Project > Restore. 

NOTE When you work through a Sandbox or sub Sandbox, the corresponding 

master project is referenced. 

IMPORTANT Do not use the Project > Restore command to create a new development 

branch from a previously checkpointed project revision. For new development 

paths, you should instead create a development path (see the MKS Integrity 2009 

User Guide). 

271


272 

How Restore Project Command Works 

MKS Integrity performs the Restore Project command as follows: 

A checkpoint is performed on the current configuration management project revision. 

The configuration management project is restored to the target revision. 

A final checkpoint of the restored revision is made. 

Therefore, for each configuration management project you restore, two revisions are 

generated. For example, if the head revision of the project is 1.4 and you decide to restore it to 

revision 1.2, the following project revisions are generated: 

1.6final checkpoint 

1.5pre-checkpoint 

You would then continue your project development work from revision 1.6. 

Selecting Checkpoint to Restore 

You can select the checkpoint to restore by selecting a Pre-Defined Revision or a Specific 

Revision. 

If you want to restore a pre-defined revision, select one of the following: 

Head revision, which represents the latest checkpoint on the default branch of 

development (or on the mainline, if no default is specified) 

Trunk Tip, which represents the latest checkpoint on the mainline independent of the 

default branch settings. 

If you want to restore a specific revision, you can select the revision based on a checkpoint 

number or label by clicking the appropriate tab. The default revision is the most recent 

checkpoint. 


When a configuration management project is restored, all restored members return to 

the initial state. 

The Project > Restore command can be applied to both normal and variant projects. 

You can effectively undo the Project > Restore command by restoring the configuration 

management project to the pre-checkpointed revision. 

You cannot restore a build project using the Project > Restore command. 

You cannot restore a project that is associated with a deploy stage. For more information 

on deploy stages, see the MKS Deploy 2009 Administration Guide. 

You cannot retore a project if a checkpoint is in progress on that project. 

To restore a variant project to a specific project revision, the development path must 

exist in all subprojects referenced by the project revision.

To restore a project or subproject in the CLI 


where 


si restoreproject --revision=value --reason=value --project=value 

--revision=value specifies the revision number you want the project restored to. 

--reason=reason specifies the reason for restoring the project. 

--project=value specifies the path and name of the project or subproject to be restored. 

--devpath=value specifies the development path and name of the variant project or 

subproject. 



Deleting Projects and Archives From Database 

To delete specified projects that are no longer in use from the database, use the 

si deleteproject command. Deleting a project from the database deletes the project itself 

and its history. Deleting a project from the database also deletes all of the member archives 

for members in that project. However, shared projects and archives are retained in the 

database. You can also specify to delete only specified archives rather than projects by using 

the si deletearchive command. 

Deleting projects and archives is a multi-phase process referred to as delete session. Delete 

session is identical for both si deleteproject and si deletearchive, but only one type 

of session may be in progress for the same database and server. At any phase before the final 

commit of the delete, you can roll back the operation and end the delete session with the 

projects and archives intact. 

CAUTION Once the delete session has been completed, you cannot roll back the 

changes to the database. To restore deleted projects, see “Restoring Deleted 

Projects” on page 279. 

As part of the delete session, projects and archives marked for removal from the database are 

archived (if using the --dump subcommand) and can later be restored by migrating them 

back into the database. However, broken linkages between deleted projects and those 

projects retained in the repository are not restored. 


Both si deleteproject and si deletearchive commands require either the 

AdminServer or DebugServer ACL permission. The deleteproject and 

deletearchive permissions are required to delete projects and their member archives. 

273


274 

Only one type of delete session can be in process at one time (either si deleteproject 

or si deletearchive). If the command type does not match the type of an existing 

session, an error is returned. 

The unit of delete is an entire member archive or a project and all its variants. There is no 

support for purging only member revisions, only some variants, or for purging revisions 

or checkpoints based on date. 

References by name to deleted objects are not modified by the delete. These references 

include change package entries, ACLs, policies, trigger registrations, pending 

operations, lock origination, and Sandbox registries. 

Restoring deleted objects does not re-establish links between those objects and objects 

not deleted. Links are permanently broken by a delete operation. 

You cannot delete a project if a checkpoint is in progress on that project. 

Logs of the delete session are provided as part of the si migrate command 

functionality. For more information, see the Database Repository Migrator Guide. 

Before deleting projects and archives, consult the key considerations for restoring them 

(see “Restoring Deleted Projects” on page 279). 

The si deletearchive command is intended for global clean-up of files, (not for 

removing individual archives), because links may exist between that archive another 

objects in the database. For more information, refer to documentation on the 

--nodeleteIfInUse option in the subsequent sections. 

Delete Session Phases 

Before describing the commands and their subcommands in more detail, the following 

diagram shows generally the delete session phases:

Mark 

Dump 

Commit 

Delete session phases 

Rollback 

NOTE At any time during the delete session, you can run the --status 

subcommand to determine the status of the delete session. 


1 The Mark phase specifies projects or archives that are new candidates for deletion. It 

(and consequently the delete session) begins by using the --mark subcommand to 

specify objects to be deleted. If projects are specified, the --mark subcommand 

determines what objects are to be deletion targets (projects or archives to be deleted) and 

what objects are to be kept candidates. 

IMPORTANT The MKS Integrity Server only supports one delete session at a time and 

additional targets cannot be added with a second invocation of the --mark 

subcommand. 

275


276 

Kept candidates are subprojects or members that are not deleted for one of the following 

reasons: 

Subprojects or members are not located in the directory tree of any of the projects 

specified. 

You do not have DeleteProject permission for the specified project or its 

development paths. 

You do not have DeleteArchive permission for the specified or affected member 

archives. 

You used the --nodeleteIfInUse option, and the projects are referenced by an 

outside link. The link can be that the projects are shared subprojects in projects not 

specified for the delete session. Links also include every past or present subproject 

and member archive of every branch of the project specified (mainline, variant, or 

dropped variant). 

You used the --nodeleteIfInUse option, and the members are referenced by an 

outside link. The link can be to any revision referenced in another project. 

NOTE If you restore deleted projects at a later date, the kept candidates do not 

maintain their linkages with restored projects. 

The Mark phase is complete when all candidates are converted to kept candidates or 

delete targets. At this time, you can use the --status subcommand to view information 

on delete targets and kept candidates. 

IMPORTANT All delete targets are marked by the server such that they cannot be 

changed, and links to them cannot be added by user operations. Existing links can 

be duplicated (such as creating a development path) as this does not change the 

results of --mark. Kept candidates are not restricted. 

2 The Dump phase creates backups of the marked projects in the database using the 

--dump subcommand. If projects are marked, the command recursively creates backups 

of the projects and archives to a backup table in the database (dumping them). However, 

the subcommand does not backup all of the members, subprojects, and variants that are 

referenced by those projects, only the in-tree objects. 

IMPORTANT At any phase before Commit, you can run the --rollback 

subcommand to discard the target information, and end the delete session with the 

database unchanged. Once the subcommand completes, you can begin a new delete 

session with the --mark subcommand.


CAUTION The Dump phase is not available for the si deletearchive command. 

Using this command deletes archives without creating backups for them. Archive 

backup (and restore) is not available for individual archives; only projects that 

include archives. If you require archive backups, use the si deleteproject 

command instead. 

Alternatively, projects can be copied to the backup schema without using 

si deleteproject --dump, by using si migrate --dumpToBackup projectList, where 

projectList is a selection of projects. For more information on si migrate, see the 

Database Repository Migrator Guide. 

3 The Commit phase deletes all of the delete targets identified in the Mark phase, breaks 

links to deleted objects, and ends the delete session. Begin the commit phase using the 

--commit subcommand. 

Viewing Repository Post-Delete 

A command is provided to view the state of the repository after the delete session. To view or 

print a list of all projects, archives, and directories contained in the repository directory, use 

the following command: 

si diag --diag=showrepdir --param=dirname 

where dirname is the directory containing the repository. For more information on the 

si diag command, see “To run server diagnostics in the CLI” on page 417. 

To delete projects from the database using the CLI 

NOTE Detailed help on using si deleteproject is available from the CLI using 

the man command, or see the MKS Integrity Server 2009 Administration CLI Reference 


From the CLI, use the following command: 

si deleteproject [subcommmand] value 

where value is used with the --mark subcommand and specifies projects for the current 

delete session. 

Subcommands for si deleteproject include: 

--commit commits the deletion by permanently deleting the marked objects. 

--dump dumps the objects marked for deletion in the current delete session. If projects 

are marked, the command recursively creates back ups of the projects in backup tables in 

the database (dumping them). However, the subcommand does not export all of the 

members, subprojects, and variants that are referenced by those projects, only the in-tree 

objects. The project back-ups can be restored later (see “Restoring Deleted Projects” on 

page 279). 

277


278 

--mark starts a delete session by marking objects and their dependents as new 

candidates. The subcommand determines what objects are to be delete targets (projects 

or archives to be deleted) and what objects are to be kept candidates. 



subcommand. 

When later restoring deleted projects, the kept candidates do not maintain their linkages 

with restored projects. 

--rollback cancels a delete session leaving the database unchanged. This 

subcommand can only be used in phases prior to Commit. 

--status displays the status of the current delete session. 

Command options for si deleteproject include: 

--[no]deleteIfInUse, used with the --mark subcommand, specifies if to delete 

targets that are still in use. Something is marked as in use if it refers to a particular 

project or archive that is out of tree. 

--[no]links, used with the --status subcommand, displays a list of all links that are 

broken upon commit. 

--[no]recurse, used with the --mark subcommand, specifies if to recurse into 

subprojects. The default is to recurse. 

--[no]targets, used with the --status subcommand, displays all delete targets and 

kept reasons. 

To delete archives from the database using the CLI 

NOTE Detailed help on using si deletearchive is available from the CLI using 

the man command, or see the MKS Integrity Server 2009 Administration CLI Reference 


From the CLI, use the following command: 

si deletearchive [subcommmand] value 

where value is used with the --mark subcommand and specifies projects for the current 

delete session. 

CAUTION The --dump option cannot be used with the si deletearchive 

command. Using this command deletes archives without creating backups for them. 

Archive backup (and restore) is not available for individual archives; only projects 

that include archives. If you require archive backups, use the si deleteproject 

command instead.

Subcommands for si deleteproject include: 


--commit commits the deletion by permanently deleting the marked objects. 

--mark starts a delete session by marking objects and their dependents as new 

candidates. The subcommand determines what objects are to be delete targets (archives 

to be deleted) and what objects are to be kept candidates. 



subcommand. 

--rollback cancels a delete session leaving the database unchanged. This 

subcommand can only be used in phases prior to Commit. 

--status displays the status of the current delete session. 

Command options for si deletearchive include: 

--[no]deleteIfInUse, used with the --mark subcommand, specifies if to delete 

targets that are still in use. Something is marked as in use if it refers to a particular 

project or archive that is out of tree. 

--[no]links, used with the --status subcommand, displays a list of all links that are 

broken upon commit. 

--[no]targets, used with the --status subcommand, displays all delete targets and 

kept reasons. 

Restoring Deleted Projects 

You can restore deleted projects by using the si migrate command with the 

--restoreFromBackup option. 

To restore a deleted project, specify the command in the following form: 

si migrate --restoreFromBackup=projectNames 

where projectNames specifies the names of projects to restore from the backup tables in the 

database. 

Review the migration logs to ensure no errors occurred, and then manually publish the 

restored projects (or members). For more information on si migrate, see the Database 

Repository Migrator Guide. 


If no project names are specified, all projects from the database are restored. If project 

names are specified, only those projects are restored. 

279


280 

Currently there is no mechanism to browse the backup tables to determine which 

projects are available for restoration, so it is recommended you refer to the log that was 

generated during backup or contact MKS Customer Care for assistance. 

The restore operation migrates the backup tables to the latest version of the schema 

before beginning the migration. 

If during the restore, a project (or archive) is encountered in the repository with the same 

name as the one being restored from the backup table, the project (or archive) is skipped 

(and any children such as subprojects or members). 

Restoring deleted objects does not re-establish links between those objects and objects 

not deleted. 

When restoring deleted objects, si migrate does not restore subprojects or archives 

that correspond to kept objects. Kept objects only correspond to dumped objects if they 

were within the tree of the project deleted. If there are missing archives or projects, the 

migrator creates a stub in the tree. 

Using Configuration Management Project Metrics 

You can track metrics for top-level configuration management projects and calculate them 

through event triggers. Calculated metrics can be viewed for a configuration management 

project or through a computed field on a workflow and document project item. Metrics 

provide information on a project as of a specific checkpoint. 

MKS Integrity provides some standard physical metrics you can use. You can also create 

your own metrics using a third party tool. 

NOTE Metrics are only supported for database type repositories. 

Metrics Included With MKS Integrity 

MKS Integrity provides the following metrics: 

physical lines 

number of characters in text files 

number of bytes in binary files 

number of revisions in archives 

number of normal members 

number of subproject members 

number of checkpoints 

number of java source files

number of binary files 

number of text files 

number of C or CPP files 

largest number of members in any subproject 

largest number of subprojects in any subproject 

These metrics are calculated by the following event triggers: 

check in 

checkpoint 

add member 


Metric calculations generated by operations in subprojects are automatically rolled up to the 

parent project. 

Tracking Project Metrics 

If you decide to track metrics for a project that has already been checkpointed, you can 

calculate metrics for existing checkpoints using the Calculate Project Metrics command in the 

GUI or the si calculateprojectmetrics command in the CLI. 

Viewing Project Metrics 

You can view the calculated metrics for a project in the Project Metrics view or through the 

si viewmetricsinfo CLI command. 

You can also view calculated metrics in the workflow and document project item that is 

associated with the configuration management project. The workflow and document project 

item must have an si project data type field that links it to the configuration management 

project and a computed field that displays the metric calculations that you want to view. For 

example, if you want to see the number of members in an configuration management project 

in the corresponding workflow and document project item, you would create a Number of 

Members field with the following expression: 

SIMetric("siproject-name","Number of Members") 

You could checkpoint the configuration management project nightly and update the build 

revision encoded in the si project field; so any changes in the number of members would be 

reflected in the workflow and document project item. 

For more information on creating si project fields for MKS Integrity items, see “Creating 

Fields” on page 127. For more information on creating computed fields for MKS Integrity 

items, see “Creating Computed Fields” on page 313. 

281


282 

Using Third Party Metrics Tool 

You can use a third party tool to track additional configuration management metrics. Metrics 

tracked by a third party tool must be defined in MKS Integrity and recorded for a specific 

project checkpoint. You define a metric by specifying a name and description for it using the 

si createmetricinfo CLI command. To define a metric you need the Metrics 

permission. For more information, see the MKS Integrity Server 2009 Installation and 


You can use a third party tool to calculate metrics for Java. For example, you can use a tool 

such as JavaNCSS 1 to calculate the number of Java source files in a project. You need to write 

a script to add the metrics calculated by a third party tool to a specific project checkpoint. For 

more information on creating a script for metrics, see the comments in the sample script 

metrics.js. You can update this file by adding your file suffix to one of the tables and 

creating a new JavaScript function to implement the metrics. 

NOTE If you run custom Java code from a script, your custom Java code can be put 

into the installdir/data/java/classes directory as individual class files or 

packaged as one or more JAR files in the installdir/data/java/jars directory. 

You can use both directories at the same time if you want some classes packaged up 

and some exposed individually. 

You can use a third party tool to calculate metrics for C or C++ in the context of a Sandbox. 

You add the calculated value of the metric to a project checkpoint using the 

si addprojectmetric CLI command. For more information on the CLI commands see the 

MKS Integrity 2009 CLI Reference Guide for Configuration Management. 

Performance With Metrics 

There may be a performance impact when using project metrics. The first time you 

checkpoint a project with a large number of members that existed before implementing 

metrics, the metric calculation may take a significant amount of time. The increase in time is 

due to the need for the metrics to be initially computed for the pre-existing members, while 

subsequent metric calculations are aggregated for members of the project. 

Working With Subprojects 

MKS Integrity allows you to create large configuration management projects composed of 

smaller component projects. These smaller projects are known as subprojects. Subprojects 

behave in the same way as projects and can be accessed with most project and Sandbox 

commands. 

1 JavaNCSS is supported but not shipped with MKS Integrity.


For example, you could have subprojects for the following types of components: 

source files for creating individual executables 

source files for common libraries 

HTML files 

graphic files 

documentation 

Each component usually has several related files. Each component can be kept in its own 

project. If you have two or more products that share these common components, you can 

create a separate master project for each product and include the projects for the common 

components as subprojects of each appropriate master project. 

NOTE Subprojects are not the same as project members. You can only perform 

project-level operations on subprojects. 

Creating Subprojects 

You create a new subproject, then add members and configure the subproject as necessary. 

For example, if you had a financial toolkit application that you wanted to add a new 

calculator application to, you would create a new subproject in the toolkit project to contain 

the calculator application source code. 

To create a subproject in the GUI, select the project or Sandbox to create a subproject in, and 

select Project > Subproject > Create. 

For information on the Change Package field, creating a change package, or the Create 

Subproject options see the MKS Integrity 2009 User Guide. 

Adding Subprojects 

When a subproject is dropped from a project, the subproject’s historical information remains. 

You can add the subproject back. 

To add a dropped subproject to a project in the GUI, select Project > Subproject > Add, and 

follow the instructions on the Add Subproject wizard. 

Selecting Subproject Type 

When adding a subproject you can specify one of the following types: 

Normal adds a working subproject based on the mainline. 

283


284 

Variant adds a subproject based on a specific development path. 

NOTE The Variant option is unavailable if there are no available development paths. 

For information on creating a development path, see the MKS Integrity 2009 User 


Build adds a static subproject based on a specific checkpoint of the master project that is 

used for building or testing the project, but not for further development. You can specify 

the checkpoint through its checkpoint number or label. 

Default adds a subproject as the same type as the parent project. 

NOTE If you do not select a subproject type, the subproject is added as the same type 

as the parent project. 

Specifying Subproject to Add 

You can type in or select the subproject to add. For detailed information about entering 

project paths and selecting projects, see the MKS Integrity Client 2009 Getting Started Guide. 

Using Change Packages 

For information on the Change Package field and creating a change package, see the 


Adding Shared Subprojects 

A shared subproject is a subproject that is a member of more than one configuration 

management project. You can share a subproject between two or more projects by referencing 

the original subproject. A shared subproject allows you to access common members across 

many projects. Shared subprojects are not required to be located within the same directory 

structure or project hierarchy. 

To add a shared subproject, select the project or Sandbox you want to add the shared 

subproject to, and select Project > Subproject > Add Shared. 

Example 

Ryan maintains the North American and German Web sites for ABC Financial. Both Web 

sites are under version control and use the same images, but they contain different content. 

To avoid duplication and ensure both Web sites contain the same images, Ryan adds the 

images to a subproject and shares it between the two projects. 

Shared Project Behavior 

A shared subproject functions the same as an unshared subproject and is accessible by the 

same commands. The shared subproject continues to reside within its original master project, 

but is referenced by the other project and shown as a shared subproject.


When working with shared subprojects, MKS Integrity uses the actual name of the subproject 

in the repository rather than its relative name in the project hierarchy for the purposes of 

resolving ACLs, policy statements, event triggers, and change package entries. This enhances 

the portability of change packages across different projects. 

You cannot import members into a shared subproject from its shared location. 

Shared Projects From Source Integrity Standard 

Shared subprojects (out-of-tree subprojects) that were created in Source Integrity Standard 

(an earlier version of MKS Integrity) are detected as they are accessed by MKS Integrity 

without disrupting the operation. The format of these subprojects is retained until you 

change or update it to the new format by reconfiguring it. 

Selecting Subproject Type 

When adding a subproject you can specify one of the following types: 

Normal adds a subproject based on the working subproject on the mainline 

Variant adds a subproject based on a specific development path of the master project. 




Build adds a static subproject based on a specific checkpoint of the master project that is 

used for building or testing the project, but not for further development. You can specify 

the checkpoint through its checkpoint number or label. 

Default adds a subproject as the same type as the parent project. 

NOTE If you do not select a subproject type, the subproject is added as the same type 

as the parent project. 

Specifying the Shared Subproject 

You can type in or select the subproject for sharing. For detailed information about entering 

project paths and selecting projects, see the MKS Integrity Client 2009 Getting Started Guide. 

Specifying Destination Directory 

When you type the subdirectory for the shared subproject, the subproject name must reside 

in the project directory. 


For information on the Change Package field or creating a change package, see the 


285


286 

Configuring Subprojects 

Once you create or add a subproject, you can modify the type to suit your needs. For 

example, you can change a normal subproject to a build subproject to suspend development, 

or you can change a variant subproject to a normal subproject to continue development on 

the main trunk. 

Interface Procedure 

GUI Select Project > Subproject > Configure. 

Web Select Project > Configure Subproject. 

Example 

Jen wants the ABC Tools development team to work with revision 1.2 of amortization/ 

project.pj, the last known stable version of the code. Jen does not want the general 

development team to do any further development on this release, so she configures the 

amortization/project.pj subproject to be a build subproject. 

Changes Between Configurations 

Any changes you make when configuring a subproject affects the project as a whole and any 

shared subprojects within it. Deltas reflecting these changes appear in the Project or Sandbox 

view. Some differences you may see include: 

Members existing in the original version and configured version of the subproject 

display a delta if the working revision in the Sandbox is different from the new member 

revision. 

Members that did not exist in the original version of the subproject, but do exist in the 

configured subproject, display a delta to indicate that the Sandbox does not have a 

working file for the new member. 

Members that existed in the original version of the subproject, but do not exist in the 

configured subproject, display as former members. 

Subprojects that existed as members in the original version of the subproject, but do not 

exist in the configured subproject, display as former subprojects. 

To resolve the differences, resynchronize the subSandbox. 

Configuring Shared Subprojects 

When configuring shared subprojects, remember that each shared subproject is configured 

independently. This means that when you configure a shared subproject, the reconfiguration 

does not change all instances of that subproject. For example, if the subproject tools/ 

project.pj is shared in the two projects, Aurora/project.pj and Libra/project.pj, a 

change to the configuration of Aurora/tools/project.pj does not affect the configuration 

of Libra/tools/project.pj.

Source Integrity Standard Subprojects 


Configured subprojects or frozen subprojects created in Source Integrity Standard (an earlier 

version of MKS Integrity) are detected as they are accessed by MKS Integrity without 

disrupting the operation. The format of these subprojects is retained until you change or 

update it to the new format by reconfiguring it. 

Selecting Subproject Configuration Type 

When configuring a subproject you can specify one of the following types: 

Normal configures a subproject to the working subproject on the mainline. 

Variant configures a subproject to a specific development path. 




Build configures a static subproject to a specific checkpoint of the project that is used for 

building or testing the project, but not for further development. You can specify the 

checkpoint through its checkpoint number or label. 


For information on the Change Package field or creating a change package, see the 


Configuring Subproject Using CLI 

For information on how to configure a subproject in the CLI, see the 

si configuresubproject command in the MKS Integrity 2009 CLI Reference Guide for 

Configuration Management. 

Sharing Archives With Other Projects 

Teams within organizations often reference the same files for several different products. This 

section describes two possible approaches to sharing resources using a simplified example in 

which two teams use a single header file. 

In this scenario: 

Team 1 works within configuration management project team1.pj and has one 

member, code.c. 

Team 2 has its own project, team2.pj, and has two members, program.c and 

header.h. 

287


288 

Team 2 was the first to use header.h and has the original file in its subdirectory. Team 1 

needs to access header.h for code.c. 

MKS Integrity allows you to control archive sharing. For more information on the 

permissions required to restrict archive sharing, see the MKS Integrity Server 2009 Installation 


Some general administrative concerns with sharing resources are as follows: 

File ownership is uncertain 

Normally the team that first creates a resource owns it. However, when a resource is 

shared, its ownership comes into question. Who is authorized to make updates to 

header.h? Team 2 originally owned the file but team 1 may now need to make changes 

to it. Alternately, team 2 may want to retain ownership of header.h, restricting changes 

from team 1 members. 

Once an archive is shared, the ACLs used to control permissions for that archive depend 

on how the shared archive is accessed. For example, if the archive is accessed through 

team1.pj, the ACLs for team1.pj control permissions, and, if the archive was accessed 

through team2.pj, the ACLs for team2.pj control permissions. 

Update and compatibility concerns 

When team 2 checks in a new version of header.h, it normally only tests its correctness 

and compatibility with program.c. The changes may not be compatible with team 1’s 

code.c and could lead to a loss of functionality for code.c, if team 1 were to accept 

team 2’s changes. This could be solved by using different variants of the shared 

subproject for team 1 and team 2. 

A related concern is the stability of the changes made to a shared resource. Teams 1 

and 2 may have different release schedules and criteria. Even if team 2’s changes to 

header.h were technically compatible with team 1’s project, team 1 may still hesitate to 

accept any changes. 

NOTE ACLs on shared subprojects are based on the canonical name of the 

subproject. For example, if project c:/test/project.pj accesses d:/common/ 

library.pj as a shared subproject, the ACL would be based on the name for d:/ 

common/library.pj. 

The next section presents two possible solutions and briefly explores the related 

administrative concerns, along with ways you can use MKS Integrity to help.

Shared Subprojects 


A possible solution is to create a shared subproject that is a component in team1.pj and 

team2.pj. For example, the following shows the shared subproject header.pj that allows 

both teams to access the header files that are common to both projects. 

NOTE Wherever possible, it is preferable to share entire subprojects rather than 

individual archives. For example, if you have 30 common files, it is preferable to 

group these into a subproject and share this subproject rather than sharing 30 files 

individually. 

When carrying out development in this structure, users create a Sandbox of their respective 

master projects and recurse into the relevant subprojects, including the shared subproject, 

header.pj. 

Common Projects 

Another alternative is to use common projects. You can create a master project that contains 

three projects (team1.pj, team2.pj, and header.pj) as subprojects. 

In this structure, ownership of the shared resources is flexible. Both teams may be given 

ownership and right to modifications on the common project. 

Alternatively, you could use ACL permissions to grant ownership and modification rights to 

one team but not to the other. This solution suggests a second alternative where a separate 

team is created with responsibility for all changes in the common project. This alternative 

also addresses the compatibility issue in that the team making changes in the common project 

should be aware of the other projects that include the common project as a subproject. This 

ensures compatibility. 

Teams 1 and 2 can now focus on updating their own code, with general confidence that 

shared files are compatible with their code. Any problems in compatibility can be brought to 

the attention of the compatibility team who can deal with the problems. 

When carrying out development in this structure, users create a Sandbox of the master 

project and recurse into the relevant subprojects. There may be some resistance to the idea of 

working with files located in different subprojects. This change in working environment 

requires time to adjust to a new operating procedure. 

Recursing from the master project raises the concern of updates and release criteria. 

However, this solution also offers some control over that concern. There is no requirement 

for users within a team to start from the master project. Instead, a user can create a Sandbox 

of their team’s project and then create a separate Sandbox of the common project. This 

separation allows for flexibility in deciding on the version of the common project that is 

desired. 

In this situation, the common project has its own release cycles and is checkpointed on each 

cycle. Each team can then choose to create a build Sandbox of the common project based on a 

given release of the common resources and use that in their development. 

289


290 

Alternatively, a team may want to continue development within the common project from a 

given release baseline, while isolating their changes from other teams and other team’s 

changes from the common project. The team can then create and use a variant Sandbox of the 

common project. 

A final alternative is to create a normal Sandbox from the common project and use it as is, 

accepting that it may be in a state of flux. This alternative may be acceptable, and even 

desirable, in the early stages of development. This type of project structure provides this 

flexibility and even allows for decisions to be changed during development. 

Potential Problems With Common Projects 

Although common projects provide a flexible method for managing development processes, 

two issues may arise when using this approach: 

Versioning of the common project is not team specific 

The version of the common project used by an individual team is not automatically 

referenced with that team’s project, especially when you are using a build or variant 

Sandbox of the common project to ensure stability and isolate changes from other teams. 

Each team must keep track of the version of the common project specific to their project. 

One solution is to use different variants of the shared subproject for each team. 

Another solution is to record the version of the common project in the build files 

maintained by the team. These build files can then be added to and archived with the 

team’s project thereby serving as a permanent record of the complete build environment 

including the version of the common project. 

Changes to build specifications 

This solution requires changes to build specifications because working file locations are 

changed. 

MKS Integrity can manage source files anywhere on your server’s repository. MKS Integrity 

identifies project members in the same directory or its subdirectories using a path relative to 

the project file.

C HAPTER SEVEN 

Computed Expressions 

Performing Calculations Between Fields 

7 

In addition to recording information in fields, MKS Integrity can also perform 

calculations between fields, storing the result as a read-only value in a computed field or 

displaying it as a read-only value when you run a chart or report. For example, in a 

Feature item, MKS Integrity can add the values in the QA Estimated Time and 

Development Estimated Time fields, storing the result in the Total Estimated Time field 

(the computed field). Storing results in computed fields is useful for historical reporting. 

Another example of using computed expressions is to create a report that adds the 

Budget fields in a list of Project items to display a budget total. Performing calculations 

in charts and reports is useful if your administrator has not created computed fields 

and/or you want to reduce the dependencies of storing results in computed fields. 

In addition to calculating numeric values, you can also calculate text values by 

combining text and numeric fields with text functions. For example, by combining an 

item’s ID with the appropriate text functions, MKS Integrity can create a unique 

identifier for an item, such as REQ-00001234, and display it in a computed field. 


“Computed Expression Types” on page 292 

“Computed Expression Rules” on page 293 

“Creating Computed Fields” on page 313 

“Calculating Static Computed Fields” on page 315 

“Using Computed Fields to Chart Historical Trends” on page 316 

“Scheduling Computation Times” on page 318 

“Using Computed Fields to Calculate State Metrics” on page 319 

“Security” on page 321 

“Performance and Scalability” on page 321 

291

Chapter 7: Computed Expressions 


292 

The following table summarizes the steps you should follow to set up computed expressions: 


Learn the available types of computed 

expressions. 

Computed Expression Types 

To perform calculations between fields, MKS Integrity uses computed expressions similar to 

any expression you would find in a programming language. Using specific syntax, operators, 

functions, and operations, you can create simple or complex expressions that calculate field 

information in a single item or against a list of items. 

You can create two types of computed expressions: 

“Computed Expression Types” on page 292 

Construct rules for computed expressions. “Computed Expression Rules” on page 293 

Create a computed field. “Creating Computed Fields” on page 313 

Calculate a static computed field. “Calculating Static Computed Fields” on 

page 315 

Chart historical trends. “Using Computed Fields to Chart Historical 

Trends” on page 316 

Calculate state metrics. “Using Computed Fields to Calculate State 

Metrics” on page 319 

Understand implications on performance and 

scalability of the MKS Integrity Server when 

using computed expressions. 

“Performance and Scalability” on page 321 

Intra-item expressions perform calculations between fields in a single item, storing the 

result in a computed field, for example, adding the QA Estimated Time and Development 

Estimated Time fields in a Feature item to produce a value in the Total Estimated Time 

field (the computed field). Computed fields are created by administrators in the 

MKS Integrity Administration Client. To users computed fields display as read-only 

fields in items; however, administrators can configure the field visibility. For more 

information on creating computed fields, see “Creating Computed Fields” on page 313. 

Intra-item expressions can also retrieve information from an item using external 

information functions, such as CPECount(), which counts the number of change package 

entries in an item. Using external information functions in expressions allow you to 

retrieve metrics about your workflow. Once you define an intra-item expression using 

external information functions, you can use queries, charts, reports, and dashboards to

Computed Expression Rules 

collect the metric data and report on it. For more information on state metrics, see “Using 

Computed Fields to Calculate State Metrics” on page 319. 

Inter-item or aggregate expressions use aggregate functions, such as sum or average, to 

perform calculations against fields in a list of items. For example, using the sum(field) 

aggregate function in a report, you can add the Estimated Cost field in a list of Project 

items to produce a total estimated cost. Aggregate expressions can be created in a chart 

or report by any user in the MKS Integrity Client or MKS Integrity Administration 

Client. For more information on using aggregate expressions in charts and reports, see 

the MKS Integrity 2009 User Guide. 


General Syntax 

You must create computed expressions using syntax, operators, functions, and operations. 

Computed expressions use the following general syntax: 

To specify field names, surround the field name with double quotes, for example, 

"Actual Cost". 

Spaces are ignored, except within quotes, for example, "Defect Count". 

Identifiers followed by “(“ (a parenthesis) are considered functions. 

Identifiers not followed by a parenthesis are considered field names. 

Spaces and special characters within quotes are acceptable. 

Computed fields are valid as fields used in another computed field or computed 

expression; however, they may not recurse. 

Arithmetic Operators 

The following arithmetic operators are supported in computed expressions: 

* (multiplication) 

/ (division) 

+ (addition) 

- (subtraction) 

- (unary negation) 

Boolean-exp?true_exp:false_exp (conditional ternary) 

293


Boolean Operators 

294 

The following Boolean operators are supported in computed expressions: 

== (equal) 

= (contains) 

!= (not equal) 

(does not contain) 

< (less than) 

> (greater than) 

= (greater than or equal to) 

and 

or 

Empty Fields 

For Boolean fields, two keywords are Boolean constants: true and false. When a computed 

field is marked against a Boolean field, the result of the computed expression must be a 

Boolean value, for example: 

expression boolean-operator expression 

In MKS Integrity, a field without a value is referred to as empty. A computed expression that 

incorporates a field with an empty value results in an empty value, except in aggregate 

expressions. 

For example, to determine if the Project End Date date field is empty, type: 

or 

"Project End Date"-today() > 0 

"Project End Date" - today()

Dates, Times, and Time Zones 

The following rules apply to dates, times, and time zones: 


Dates and dates/time are considered separate date types in computed expressions, and 

cannot be assigned to one another. 

Displayed date fields do not change based on the time zone that a user is operating in; 

however, displayed date/time fields and time entries vary based on the time zone that a 

user is operating in. 

Computed expressions return dates/times in the MKS Integrity Client’s time zone and 

perform calculations in the MKS Integrity Server’s time zone where appropriate. 

Computed expressions do not include a function for converting date/time information 

to date-only. This applies in all cases where an expression returns a timestamp (date plus 

time) value. Where date/time information is required, use the computed expression 

with a timestamp field. For more information on functions, see “Function Classes” on 

page 296. 

Date expressions accept all standardized date and timestamp formats. 

Timestamp Operations 

The following operations are supported with timestamps in computed expressions: 

IMPORTANT You cannot mix dates and timestamps. 

timestamp + integer constant; integer constant + timestamp 

timestamp - integer constant 

timestamp("timestamp-constant") 

timestamp - timestamp 

timestamps can be subtracted or added to a constant integer, for example, now()+5 or 

now() - 5 

Integer constants are treated in units of days; for example, timestamp + integer constant 

takes the specified time and adds a specified number of days. When subtracting two 

timestamps, the number of days between the two dates rounded to the nearest day is the 

result. Using other operators or a floating point results in an error. 

295


Date Operations 

296 

To perform date manipulation in computed expressions, the following date operations are 

supported: 

datediff() returns the difference between two specified timestamps or dates, or a 

combination of the two as an integer in seconds. 

now() returns the current timestamp. 

today() returns the current date. 

User and Group Fields 

Data Conversion 

You can compare single- and multi-valued user and group fields in computed expressions, 

for example, "Assigned User" = jriley, or "Assigned Group" = Development. By 

creating a computed expression that includes a user or group field comparison, you can 

incorporate the result of the computed field into an editability rule. 

NOTE You cannot compare two user fields in a computed expression, for example, 

“Assigned User” = “Created By”. 

TIP You can also use the symbolic me user name to indicate the user retrieving the 

item. 

The following data conversions occur when combining various field data types in a 

computed expression: 

Function Classes 

Two integers produce an integer. 

Two floating points produce a floating point. 

An integer and floating point produce a floating point. 

Constant integers can be added to timestamps, for example, 5+now(). 

Timestamps using other operators produce an error. 

In a computed expression, you can use the following function classes:


An arithmetic function can be applied in any computed expression type, for example, 

adding two field values and rounding the resulting value to the nearest integer. For a 

complete list of arithmetic functions, see “Arithmetic Operators” on page 293. 

NOTE Node, segment, and shared item, and test types are used by the document 

model. To learn more these types and the document model, see “Setting Up 

Documents” on page 97. 

A day/time function is used to return or quantify date/time information. For example, the 

number of days an item spends in a specific state, or the earliest date/time recorded 

against an item. For a complete list of date/time functions, see “Date/Time Functions” 

on page 299. 

An aggregate function is only permitted when performing an aggregate operation, for 

example, using the sum function to add the expressions calculated against each item that 

the aggregation is running against. Attempting to use an aggregate function for a normal 

expression results in an error. For a complete list of aggregate functions, see “Function 

Classes” on page 296. 

A text function is used to perform text calculations with text and numeric fields. For 

example, using an item’s ID to create a computed field that calculates a unique identifier 

for an item, such as REQ-00001234. 

To perform text calculations, string expressions in text functions accept short and long 

text fields. For a complete list of text functions, see “Function Classes” on page 296. 

CAUTION Text strings in text calculations cannot exceed 1 kilobyte. Exceeding this 

limit may cause the MKS Integrity Server to fail. 

An external information function can only operate against a single item and allows you to 

extract information from an item, for example, how many times the item has been in the 

Submit state. Attempting to use an external information function in an aggregate 

expression results in an error. For example, SICPEntryCount()is an invalid aggregate 

expression, but sum(SICPEntryCount())is valid because the argument to an aggregate 

function is a normal expression. SICPEntryCount() is part of the normal expression 

and is therefore valid. 

For example, it is valid to use DaysInState() when accessing a single item, since it 

results in a single number; however, if you use it against a list of items, no results can be 

returned. To apply an external information function to each item in a list, embed it in an 

aggregate function, for example, avg(DaysInState()). 

For a complete list of external information functions, see “Function Classes” on page 296. 

297


298 

Arithmetic Functions 

Name and Description Return Value 

abs(numeric-expression) 

Returns absolute value of numeric expression. 

sign(numeric-expression) 

Returns -1 if expression evaluates to < 0, 0 if it evaluates to 0, and +1 if it evaluates to 

positive number. 

round(numeric-expression) 

Returns expression rounded to nearest integer. 

truncate(numeric-expression) 

Returns expression truncated to nearest integer. 

floor(numeric-expression) 

Returns largest integer less than or equal to given numeric expression. 

ceil(numeric-expression) 

Returns smallest integer greater than or equal to given numeric expression. 

mod(numeric-expression1, numeric-expression2) 

Returns remainder of first expression divided by second expression. 

If either expression is not integer, then expression is: 

(abs(e1) - floor(abs(e1)/abs(e2)) * abs(e2)) * sign(e1) 

isEmpty(expression1, expression2) 

First expression evaluated. If result not empty, it becomes return value for function. If 

empty, second expression evaluated and is return value for function. Both expressions 

must evaluate to same type. Expression can be numeric, time, or Boolean. 

emptyint() 

Returns an empty value in an integer field. 

emptyfloat() 

Returns an empty value in a floating point field. 

emptytime() 

Returns an empty value in a date/time field. 

emptydate() 

Returns an empty value in a date field. 

emptylogical() 

Returns an empty value in a logical field. 

emptytext() 

Returns an empty value in a text field. 

emptyuser() 

Returns an empty value in a user field. 

Integer or floating 

point, same as 

expression 

Integer or floating 

point, same as 

expression 

Integer 

Integer 

Integer 

Integer 

Integer if both 

expressions integers; 

otherwise, floating 

point 

Type in expression 

none 

none 

none 

none 

none 

none 

none

emptygroup() 

Returns an empty value in a group field. 

timestamp(quoted-string) 

Converts supplied string into timestamp constant. Using Java SimpleDateFormat, 

following formats are attempted in order until one succeeds: 

Java DateTimeInstance(LONG, LONG) 

Java DateTimeInstance(SHORT, SHORT) 

MMM d, yyyy hh:mm a 

MMM d, yyyy HH:mm 

MMM d, yyyy HH:mm:ss 

Note: Parsing done on the client using client's locale. Timestamp evaluated into timestamp 

constant during parsing. When expression displayed, displays in standard format for 

locale. 

now() 

Returns current time. 

Note: Current time is time when expression evaluated not parsed. To return number of 

days an item has existed, type: 

now() - "Created Date" 

SelectionCount(field-name) 

Returns the number of entries selected in a multi-valued field on an item. If the field is 

empty, returns 0; if the field is not empty but is not multi-valued, returns 1. 

Not valid for attachment, relationship, or computed fields. 

DateDiff(starttime, endtime) 

Returns number of seconds between two dates with times. If starttime larger than 

endtime, result positive, otherwise negative. 

Date/Time Functions 



none 

Timestamp 

Timestamp 

Integer 

Integer 


DaysInState(state-name) 

Returns number of days item in specific state rounded to nearest day. Individual state 

times are added together in seconds; the resulting sum is rounded to days. 

To specify unspecified state, type "Unspecified", for example, 

DaysInState("Unspecified"). 

DaysInPhase(phase field name, phase name) 

Returns number of days item in specific phase rounded to nearest day. Individual phase 

times are added together in seconds; the resulting sum is rounded to days. 

DaysCurrentState() 

Returns number of days item in current state rounded to nearest day. 


DaysCurrentState("Unspecified"). 

Integer 

Integer 

Integer 

299



DayOfYear(date/timestamp/field) 

Returns the day of the year for the specified date. 

dayOfWeek(date/timestamp/field) 

Returns the day of the week for the specified date. Sunday is 1, Monday is 2, and so on. 

weekOfYear(date/timestamp/field) 

Returns the week of the year for the specified date. 

monthOfYear(date/timestamp/field) 

Returns the month of the year for the specified date. 

weeksDiff(dateA, dateB) 

Returns the number of weeks between two specified dates. 

Note: This is the number of actual weeks, not the number of days divided by 7. 

monthsDiff(dateA, dateB) 

Returns the number of months between two specified dates. 

Note: This is the number of actual months, not the number of days divided by 30. 

weekdaysDiff(dateA, dateB) 

Returns the number of week days between two specified dates. Saturdays and Sundays 

are not included. 

DayOfWeekName(date/timestamp) 

Returns day of week for the specified date or date and time, for example, Monday. 

getDay(date/timestamp/field) 

Returns the date for the specified date or date and time, for example, 23. 

getYear(date/timestamp/field) 

Returns the date for the specified date or date and time, for example, 2009. 

MonthOfYearName(date/timestamp/field) 

Returns month of the year for the specified date or date and time, for example, October. 

getHour(timestamp/field) 

Returns the hour for the specified time, for example, 2. 

Note: Hours are specified in 24-hour time. For example, midnight is 0 and 7pm is 19. 

getMinute(timestamp/field) 

Returns the minute for the specified time, for example, 05. 

getSecond(timestamp/field) 

Returns the second for the specified time, for example, 33. 

DaysCurrentPhase(phase-field-name) 

Returns number of days item in current phase rounded to nearest day. 

dateFirstEntered(state-name) 

Returns date specified state first entered. 

300 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Text 

Integer 

Integer 

Text 

Integer 

Integer 

Integer 

Integer 

Timestamp

dateLastEntered(state-name) 

Returns date specified state last entered. 

SecondsInState 

Returns number of seconds item in specific state. If item in state multiple times, seconds 

for each occurrence added together. 


SecondsInState("Unspecified"). 

SecondsInPhase 

Returns number of seconds item in specific phase. If item in phase multiple times, 

seconds for each occurrence added together. 

To specify unspecified phase, type "Unspecified", for example, 

SecondsInPhase("Unspecified"). 

SecondsCurrentState 

Returns number of seconds item in current state. 

SecondsCurrentPhase 

Returns number of seconds item in current phase. 

sumTimeEntry[(date("startdate"),date("enddate"))] 

or 

sumTimeEntry[(symbolicdate(),symbolicdate())] 

Returns total time spent (rounded to hour) on item in optional timeframe. 

sumTimeEntryByUser(user[,user...] 

[,date("startdate"),date("enddate")] 

or 

sumTimeEntryByUser(user[,user...] 

[,symbolicdate(),symbolicdate()] 

Returns total time spent (rounded to hour) on item by specified users in optional 

timeframe. 



sumTimeEntryByGroup(group[,group...] 

[,date("startdate"),date("enddate")]) 

or 

sumTimeEntryByGroup(group[,group...] 

[,symbolicdate(),symbolicdate()]) 

Returns total time spent (rounded to hour) on item by specified groups in optional 

timeframe. 

sumTimeEntryByPhase(phaseField, 

phase[,date("startdate"),date("enddate")]) 

or 

sumTimeEntryByPhase(phaseField, 

phase[,symbolicdate(),symbolicdate()]) 

Returns total time spent (rounded to hour) on item while in phase for specified phase 

field. 

Timestamp 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

301



sumTimeEntryByPhaseByUser(phaseField, phase, 

user[,user...][,date("startdate"), 

date("enddate")]) 

or 

sumTimeEntryByPhaseByUser(phaseField, phase, 

user[,user...][,symbolicdate(),symbolicdate()]) 

Returns total time spent (rounded to hour) on item by specified users while in phase for 

specified phase field. 

sumTimeEntryByPhaseByGroup(phaseField, phase, 

group[,group...][,date("startdate"), 


or 

sumTimeEntryByPhaseByGroup(phaseField, phase, 

group[,group...][,symbolicdate(), 

symbolicdate()]) 

Returns total time spent (rounded to hour) on item by specified groups while in phase for 

specified phase field. 

sumTimeEntryByState(state[,date("startdate"), 


or 

sumTimeEntryByState(state[,symbolicdate(), 

symbolicdate()]) 

Returns total time spent (rounded to hour) on item while in specified state. 

Note: MKS Integrity gathers time entries on a daily basis and assigns the time entry to 

the date (to midnight). MKS Integrity records state changes to the exact milli-second. 

Using time entries to determine how long an item has been in a particular state is only an 

approximation. Therefore, this function is only guaranteed correct if the item contains 

only one state transition for the entire day. 

For example, an item is posted, moves through several states (Investigate, 

In Development, Development Done), and is closed (Built) in a single day. Then, 

the user working on the item enters the total time spent on the item in a time 

entry. Because MKS Integrity cannot subdivide this time entry (hours spent on the item) 

into multiple pieces of information (hours spent in each state), the 

sumTimeEntryByState function assigns the time entry to a single state – the state that 

the item had on midnight on the day of the entry (Built). 


sumTimeEntryByState("Unspecified"). 

sumTimeEntryByStateByUser(state, 

user[,date("startdate"),date("enddate")]) 

or 

sumTimeEntryByStateByUser(state 

(user[,symbolicdate(),symbolicdate()]) 

Returns total time spent (rounded to hour) on item by specified users while in specified 

state. 

302 

Integer 

Integer 

Integer 

Integer


group[,date("startdate"),date("enddate")]) 

or 


group[,symbolicdate(),symbolicdate()]) 

Returns total time spent (rounded to hour) on item by specified groups while in specified 

state. 

countTimeEntry(date("startdate"), 

date("enddate")) 

or 

countTimeEntry(symbolicdate(),symbolicdate()) 

Returns number of time entries for item with duration greater than zero in optional 

timeframe. 

countTimeEntryByUser(user[,user...] 


or 

countTimeEntryByUser(user[,user...] 


Returns number of time entries for item by specified users with duration greater than zero 

in optional timeframe. 

countTimeEntryByGroup(group[,group...] 


or 

countTimeEntryByGroup(group[,group...] 


Returns number of time entries for item by specified groups with duration greater than 

zero in optional timeframe. 

Aggregate Functions 



firstTimeEntryDate() 

Returns earliest date time recorded against item. 

lastTimeEntryDate() 

Returns latest date time recorded against item. 

Integer 

Integer 

Integer 

Integer 


sum(numeric-expression) 

Adds expressions calculated against each item that the aggregation running against. 

avg(numeric-expression) 

Adds expressions calculated against each item that the aggregation running against, 

then divide by number of non-empty entries. 

Date 

Date 

Integer or floating point, 

same as expression 

Floating point 

303



min(numeric-expression or timestamp) 

Finds smallest of expressions from each item that the aggregation running against. If all 

expressions empty, result empty. 

max(numeric-expression or timestamp) 

Finds largest of the expressions from each item that the aggregation is running against. If 

all expressions are empty, the result is empty. 

count() 

Returns number of items that the aggregation is running against. 

sumTimeEntrySecs 

[(date("startdate"),date("enddate"))] 

or 

sumTimeEntrySecs 

[(symbolicdate(),symbolicdate())] 

Returns the total time spent (in seconds) on an item in an optional timeframe. 

sumTimeEntrySecsByUser 

(user[,user...][,date("startdate"),date("enddate")] 

or 

sumTimeEntrySecsByUser 

(user[,user...][,symbolicdate(),symbolicdate()] 

Returns the total time spent (in seconds) on an item by specified users in an optional 

timeframe. 

sumTimeEntrySecsByGroup 

(group[,group...][,date("startdate"),date("enddate")]) 

or 

sumTimeEntrySecsByGroup 

(group[,group...][,symbolicdate(),symbolicdate()]) 

Returns the total time spent (in seconds) on an item by specified groups in an optional 

timeframe. 

sumTimeEntrySecsByState 

(state[,date("startdate"),date("enddate")]) 

or 

sumTimeEntrySecsByState 

(state[,symbolicdate(),symbolicdate()]) 

Returns the total time spent (in seconds) on an item while in the specified state. 

sumTimeEntrySecsByStateByUser 

(state, user[,date("startdate"),date("enddate")]) 

or 

sumTimeEntrySecsByStateByUser 

(state (user[,symbolicdate(),symbolicdate()]) 

Returns the total time spent (in seconds) on an item by specified users while in the 

specified state. 

304 

Integer, float point, or 

timestamp same as 

expression 

Integer, floating point, 

or timestamp same as 

expression 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer

sumTimeEntrySecsByStateByGroup 

(state, group[,date("startdate"),date("enddate")]) 

or 

sumTimeEntrySecsByStateByGroup 

(state, group[,symbolicdate(),symbolicdate()]) 

Returns the total time spent (in seconds) on an item by specified groups while in the 

specified state. 

sumTimeEntrySecsByPhase 

(phaseField, phase[,date("startdate"),date("enddate")]) 

or 

sumTimeEntrySecsByPhase 

(phaseField, phase[,symbolicdate(),symbolicdate()]) 

Returns the total time spent (in seconds) on an item while in phase for the specified 

phase. 

sumTimeEntrySecsByPhaseByUser 

(phaseField, phase, 

user[,user...][,date("startdate"),date("enddate")]) 

or 

sumTimeEntrySecsByPhaseByUser 


user[,user...][,symbolicdate(),symbolicdate()]) 

Returns the total time spent (in seconds) on an item by specified users while in phase for 

the specified phase. 



sumTimeEntrySecsByPhaseByGroup 

(phaseField, phase, group[,group...][,date("startdate"), 


or 

sumTimeEntrySecsByPhaseByGroup 


group[,group...][,symbolicdate(),symbolicdate()]) 

Returns the total time spent (in seconds) on an item by specified groups while in phase 

for the specified phase. 

LastResultAgg() 

Returns the internal ID of the most recent test result record for a group of items. This 

function must be used with the Aggregate, AggregateByTree, or Query functions. 

For example, AggregateByTree (LastResultAgg()). This function must be used 

with the TestVerdictName function to convert the internal ID to a display string. For 

example, TestVerdictName(LastResultAgg()). 

Integer 

Integer 

Integer 

Integer 

Integer 

305


306 

Text Functions 


Text(string) 

Creates text constant. 

Note: If string does not contain special characters, quotes not required. For example, 

text("REQ") and text(REQ) identified as same string. 

Length(string-expression) 

Returns length of string. 

Upper(string-expression) 

Converts string into uppercase. 

Lower(string-expression) 

Converts string into lowercase. 

Concat(string-expression, string-expression[, ...]) 

Concatenates two or more strings. 

Substring(string-expression, start, count) 

Takes substring of string. Substring starts at first character and goes for count characters. 

start offset is origin 1. start and count must be positive integer constants. 

Following conditions return empty string: 

start less than or equal zero. 

start greater than length of string being processed. 

count less than zero. 

If start plus length greater than length of string being processed, then return from 

start to end of string; no blank padding. 

Locate(string-expression, string-expression) 

Searches for first string in second string. 

To add startsWith, type Locate(x, y) == 1. 

Value offset into second string first string found, where if second string starts with first, 

value one (1). If not found, returns zero (0). 

Trim(string-expression) 

Removes leading and trailing spaces from string. 

LTrim(string-expression) 

Removes leading spaces from string. 

RTrim(string-expression) 

Removes trailing spaces from string. 

Text 

Integer 

Text 

Text 

Text 

Text 

Integer 

Text 

Text 

Text

ToText(number-expression) 

Converts number to string. 

ToTextZeroPad(number-expression, size) 

Converts number to string with zero padding. 

size must be positive integer constant. 

If formatted size of number greater than or equal to specified size, it returns unchanged; 

otherwise, padded on left with the zero (0) character. If number negative, negative sign (-) 

first character. 



Text 

Text 

307


308 

External Information Functions 


SICPCount([cpstate, ...]) 

Returns number of change packages associated with item. Specify one or more of 

following change package states to include in count: 

Closed 

Open 

Submitted 

Accepted 

Rejected 

Discarded 

CommitFailed 

If you do not specify any arguments, count of all change packages returned. 

SICPEntryCount([cpentrytype, ...]) 

Returns number of change package entries associated with item. Specify one or more of 

following change package entry types to include in count: 

Update 

Add 

Drop 

Lock 

RenameFrom 

RenameTo 

UpdateRevision 

UpdateArchive 

Import 

AddFromARchive 

MoveMemberFrom 

MoveMemberTo 

CreateSubproject 

AddSubproject 

AddSharedSubproject 

DropSubproject 

ConfigureSubprojectFrom 

ConfigureSUbprojectTo 

MoveSubprojectFrom 

MoveSubprojectTo 

If you do not specify any arguments, count of all unique change package entry 

operations returned, for example, rename operation only counted as one entry rather 

than separate entries for RenameFrom and RenameTo operations. 

SICPBytesAdded() 

Returns sum of bytes added by each change package entry for all change packages 

associated with item. 

Returns 0 for text files. 

Integer 

Integer 

Integer

SICPBytesDeleted() 

Returns sum of bytes deleted by each change package entry for all change packages 


Returns 0 for text files. 

SICPDaysOpen() 

Returns total number of days changes packages associated with item open. 

If change package currently open, current time used to calculate number of days. 

If function used based on date and time in past, count based on specified time. Any 

change packages created after specified time not counted. Number of days open for any 

change packages closed after specified time calculated using specified time as close 

time. 

SICPLinesAdded() 

Returns sum lines added by each change package entry for all change packages 


Returns 0 for binary files. 

SICPLinesDeleted() 

Returns lines deleted by each change package entry for all change packages associated 

with item. 

Returns 0 for binary files. 

SIMetric(siproject-field-name, metric name) 

Returns calculated value of metric for configuration management project. For more 

information on configuration management metrics, see “Using Configuration 

Management Project Metrics” on page 280. 

SIMetricCount(siproject-field-name, metric name) 

Returns number of items that make up metric value for configuration management 

project. 

NumberOfEntriesToState(state-name) 

Returns number of times specified state entered. 


NumberOfEntriesToState("Unspecified"). 



numberOfHistoryEntries() 

Returns number of deltas associated with item. Means number of times item edited. 

numberOfModifications(field-name) 

Returns number of deltas specified field changed in. 

HistoricFieldValue(field-name, timestamp-constant) 

Returns value of specified field at specific point in history. 

Warning: Operation can take long time to complete. 

RelCount(relationship-field) 

Returns number of related items through specified relationship field. Function equivalent 

to: aggregate(relationship-field, count()). 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Type of specified field 

name 

Integer 

309



RelExists(relationship-field) 

Returns whether relationships exist through specified relationship field. 

Aggregate(relationship-field, 

ByDocument(recurseInclude,recurseReference)[, ...], aggregateexpression) 

Aggregate operates against a single item, using that single item to find multiple items that 

it then runs an aggregate expression against to product a single value. 

Note: Aggregate is not an aggregate function. 

At least one relationship field must be specified. A set of items is made by following the 

first relationship field. Then that set is augmented by all items that the set points to 

through the next relationship field, and onward for each specified relationship field. 

The ByDocument function treats items found through the relationship field as 

documents, find all their nodes, and recurses into included and referenced documents. 

Query(query-name-string[, correlation-field[, ...]], aggregateexpression) 

Operates against single item using that single item to find multiple items it aggregates 

into for single value. query-name-string is name of query as quoted string in syntax 

"username:queryname". If no correlation-fields given, value of current item 

not used, and result of expression is constant. Aggregation expression runs against all 

items that satisfy query. Otherwise, query modified to require each specified 

correlation-field to match source item. Resulting list of items has 

aggregate-expression run against it and returned. 

Query(query-name-string[, source-correlation-field, targetcorrelation-field[, 

...]], aggregate-expression) 

More generalized form of the previous Query function; however, if sourcecorrelation-field 

is the same as target-correlation-field, use the 

previous Query function. This Query function takes list of fields that match between 

source and target items. Useful when you want to match between master item that has 

field set equal to values on all related items, in particular, Project field. 

QueryCorrelated(query-name-string[, source-correlation-field, 

target-correlation-field[, ...]], aggregate-expression) 

To express Query as QueryCorrelated function, specify aggregation-field from 

Query as both source-correlation-field and target-correlation-field. 

Allows you to specify matching fields on both sides, which is useful for item backed pick 

list (IBPL) fields. For example, if you have an item type that defines a set of something, 

like applications, the IBPL links each member of application back to application while a 

query backed relationship (QBR) field is used for linking between each application to 

each of its members. You can use the QueryCorrelated function on application using 

item ID from Application item correlated with IBPL representing Application on Defect 

that is a member of it, for example: 

QueryCorrelated("All Defects", ID, "Application IBPL", count()) 

310 

Boolean 

Type of aggregate 

expression 

Integer or float, 

depending on 

aggregation-expression 


depending on 

aggregation-expression; 

see Query function 


depending on 

aggregation-expression; 

see Query function

Item Information Functions 



IsState(statename[, ...]) 

Returns true if item’s state any of states specified in its argument list. 


IsState("Unspecified"). 

IsType()(typename[, ...]) 

Returns true if item’s type any of types specified in its argument list. 

IsNode() 

Returns true if item any of type node. 

IsSegment() 

Returns true if item any of type segment. 

IsSharedItem() 

Returns true if item any of type shared item. 

IsContent() 

Returns true if item any of types content. 

IsSubsegment() 

Returns true if item any of type subsegment. 

IsMeaningful() 

Returns true if item any of type node or segment is meaningful. 

IsNonMeaningful() 

Returns true if item any of type node or segment is non meaningful. 

IsGroupDocument() 

Returns true if item any of type segment what has the Group Document flag set. 

IsTestCase() 

Returns true if item type has a test management role of Test Case. 

IsTestSession() 

Returns true if item type has a test management role of Test Session. 

IsTestStep() 

Returns true if item type has a test management role of Test Step. 

IsTestSuite() 

Returns true if item type has a test management role of Test Suite. 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

311


312 

Test Functions 


TestVerdict(test-verdict-name) 

A test verdict name constant that can be used in a comparison. For example, 

LastResult()==TestVerdict(Passed). 

TestVerdictByType(verdict-type-name) 

A test verdict type constant corresponding to the pass, fail, or other. 

TestVerdictName(id) 

Returns the display name of the verdict corresponding to the ID. For example, 

TestVerdictName(TestVerdict(Passed) would return Passed; 

TestVerdictName(LastResult()) would return the last test result as a string. 

TestVerdictTypeName(verdict-type-id) 

Returns the name of the test verdict type. For example, 

TestVerdictTypeName(TestVerdictByType(pass)) would return Pass 

VerdictToType(verdict-id-expression) 

Returns the numeric verdict type value for the given verdict ID. Can be applied to 

LastResult() to check the verdict type of a result. For example, 

VerdictToType(LastResult())==TestVerdictByType(pass) would check if a 

result was a pass verdict type. 

ResultCount(test-verdict-name) 

Returns the number of test results with a specific verdict. For example, 

ResultCount(Passed)would return the number of successful test results. This function 

is intended to be used with test session type items. 

ResultCountByType(verdict-type-name) 

Returns the number of test results with a specific verdict type (pass, fail, other). For 

example, if you have two test verdicts with a verdict type of fail, the function 

ResultCountByType(Fail)would return the number of test results with either verdict. 

This function is intended to be used with test session type items. 

ResultCount(Relationship-field, test-verdict-name) 

Returns the number of test results with a specific verdict in related test session type items. 

ResultCountByType(Relationship-field, verdict-type-name) 

Returns the number of test results with a specific verdict type (pass, fail, other) in related 

test session items. 

LastResult() 

Returns the internal ID of the most recent test result for the current item. This function 

must be used with the TestVerdictName function to convert the internal ID to a display 

string. For example, TestVerdictName(LastResult()). 

Text 

Text 

Text 

Text 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer

Creating Computed Fields 

Creating Computed Fields 

Computed fields allow you to perform calculations between multiple fields in an item, 

storing the result as a value in a read-only field (the computed field). Date, floating point, 

integer, logical, and short text field types are the only field data types that can be configured 

as computed fields. However, only date, floating point, integer, short text, and long text 

fields can be used in the computation. 


If you create an expression using one or more fields that a user does not have permission 

to view, the user sees only the fields they have permission to view. 

Computed fields are calculated in the order that they appear in the item; however, if a 

computed field depends on the value of another computed field, it is calculated after the 

computed field containing the dependent value. Depending on the number of items in 

your database and the number of items containing computed fields that contain 

dependencies, it may take a long time to calculate the value of the computed fields. 

Using the im analytics --recomputehistory -g command, you can calculate a 

computed field within a specific time frame, storing the value in the item history. This 

command is useful for historical trend charting; however, it does not allow you to 

“correct” the history of current item data. For more information, see the “Using 

Computed Fields to Chart Historical Trends” on page 316. 

Computed text fields only accept numeric, short text, and long text fields. 

You cannot create editability rules for field value attributes backed by any computed 

field. For more information about editability rules, see “Setting Field Editability” on 

page 135. 

To create a computed field 

1 From the Create Field dialog box, select Date, Floating Point, Integer, Logical, or 

Short Text from the Data Type list. The relevant data type settings display. 

2 Select the Computation Values option. 

3 In the Computation Definition field, create a computed expression using the rules 

described in “Computed Expression Rules” on page 293. 

For example: 

To determine how many days a Defect item has not been worked on, create a date 

field called Days Inactive and type the following expression: 

now() - "Modified Date" 

313


314 

The Days Inactive field displays the number of days elapsed since the last edit of the 

Defect item. 

If a Project item type contains Actual Cost and Expected Cost fields, and you want 

to determine if and how much the actual cost of a project exceeds the expected cost, 

create an integer or floating point field called Cost Overrun and type the following 

expression: 

"Actual Cost" - "Expected Cost" 

If the value of the Actual Cost field exceeds the value of the Expected Cost field, the 

Cost Overrun field appears after editing the item, displaying how much the actual 

cost overran the expected cost. 

To determine whether the actual cost of a project exceeded 90 percent of what you 

budgeted for, type the following expression: 

"Actual Cost" > .90 * "Expected Cost" 

If the value of the Actual Cost field exceeds the value of the Expected Cost field by 

90 percent, the Cost Overrun field appears after editing the item, displaying the 

percentage that the actual cost overran the expected cost. 

As project manager, you could closely monitor project budgets by creating a query 

or e-mail notification that identifies Project items where the cost has exceeded 

90 percent of the estimated budget. 

4 To indicate how often the computed field should be calculated and stored in the item’s 

history, select a frequency from the Store to History Frequency list. Selecting a frequency 

is useful for historical charting. never is the default. 

To specify a custom frequency, select never from the list, and create an event trigger that 

specifies the desired frequency. For more information on configuring the frequency at 

which the field computes, see “Scheduling Computation Times” on page 318. 

5 From the How to Run Computations list, select one of the following computation types: 

static calculates the field based on a schedule and stores it in the item’s history 

based on the value selected in the Store to History Frequency list. Columns for static 

fields are stored in the item’s row of the database. MKS recommends you select 

static if your expression involves intensive external functions, such as query or 

aggregate functions. 

dynamic calculates the field every time field values are retrieved. By default, 

columns for dynamic fields are not stored in the item’s row of the database; 

however, you can select dynamic and a frequency from the Store to History 

Frequency list. dynamic is the default.

NOTE 

Calculating Static Computed Fields 

Because dynamically computed fields are not stored in the database, dynamically 

computed short text fields cannot be located with an all text field search in the 

MKS Integrity Client. To search for dynamically computed short text fields, 

create a query that includes a specific “field contains” comparison. If the query 

does not include additional filters, the query may not return optimal results. 

To avoid performance issues when working with queries, do not use dynamic 

computed fields in query definitions. As a workaround you could create a rule 

based event trigger that fires when a relationship field changes, storing the count 

in a regular integer field. 

To avoid performance issues when working with large documents, ensure that 

any computed fields in MKS Requirements are static, not dynamic. To learn more 

about MKS Requirements, see the MKS Integrity for Requirements Management 

Solution Guide. 

6 Fill out the remaining fields and tabbed panels as described in “To create a field in the 

GUI” on page 131. 


Calculating Static Computed Fields 

If you created a static computed field, you specify how to display a value in the computed 

field. 

To calculate a static computed field 

NOTE To calculate a static computed field, the How to Run Computations field must 

be set to Static. 

1 In the MKS Integrity Administration Client, select the computed field you want to 

calculate, and select Field > Edit. The Edit Field dialog box displays. 

2 To calculate the computed field immediately, select Compute Now. Selecting this option 

only calculates the field in items where the values of the underlying fields used in the 

computed expression have changed since the last computation. 

3 If you changed the computed field’s underlying computed expression and you want to 

calculate the field in all items containing the field, selecting Recompute All resets the last 

computation time associated with the computed field and recalculates the computed 

field in all items containing the computed field. 

4 If the computed field has been computed before, Last Evaluation At displays the date and 

time that the field was last computed. If Store to History Frequency is set to never and 

How to Run Computations is set to dynamic, Last Evaluation At displays never. 

5 To calculate the field, select Compute Now. 

315


316 

6 Click OK. The computed field calculates and the Compute Now option resets in the Edit 

Field dialog box. To recalculate the field, repeat the procedure. 

Using Computed Fields to Chart Historical 

Trends 

When you create a computed field, you typically configure it to calculate at a specific time in 

the future, storing the value in the history of each item containing the computed field. 

Command im analytics --recomputehistory -g calculates what the value of the 

computed field would have been at specific times and stores the value in the history of each 

item containing the computed field. This command is useful for discovering historical trends, 

such as how long a Defect item typically remained in state In Development in a current 

project compared to that of a previous project. 


The command is required only if a new calculation is required over existing historical 

data. 

To use the command, you must either be an administrator or have type administrator 

permissions for all types that the specified field displays in. 

Depending on the options specified, the command may delete or modify item history. 

The command may take a long time to complete depending on: 

complexity of the underlying computed expression 

number of items containing the specified computed field 

The command renders item data as it existed at the specified time. For non-history data 

source (attachments, change packages containing entries that have moved, permissions, 

and administrative objects), the command approximates the historical data. To render 

non-history data sources as they were known at a specific time, MKS recommends 

defining computed fields that use the static option under How to Run Computation, 

which captures historical values. 

Computed fields are calculated in the order that they appear in the item; however, if a 

computed field depends on the value of another computed field, it is calculated after the 

computed field containing the dependent value. Depending on the number of items in 

your database and the number of items containing computed fields that contain 

dependencies, it may take a long time to calculate the value of the computed fields. 

This command can be canceled at any time; however, it will not take effect until the 

specified interval calculation has completed. If you cancel this command, previous field 

values remain stored in the database. If the clear history option is selected and you 

cancel this command, item history is still cleared.

Example 

Using Computed Fields to Chart Historical Trends 

Using the im analytics --recomputehistory command from the command line 

interface, this example illustrates how to determine the historical trend for defects in projects. 

1 Create a new type to represent projects, for example, Project. 

2 Create some Project items to represent projects. 

3 Create a computed field, for example, Defect Count, that calculates the number of defects 

related to each project: 

im createfield --type=integer --computation='Query("Financial Toolkit 

Defects: In Dev", Project, count())' --name='Defect Count' 

4 Make the Defect Count field visible in the Project type only. 

5 Project the Defect Count field back in time: 

im analytics --recomputehistory –-starttime=06/01/2002 –-endtime=08/ 

24/2009 –-increment=1 –-incrementtype=week –-field='Defect Count' 

6 Create a query that lists all Project items, for example, All Projects. 

7 Create a chart: 

im createchart –-trendstep=week –-charttitle='Defect Count' 

--startdate=06/01/2002 –-enddate=02/01/2009 –-computations='"Defect 

Count"' –-query 'All Projects' –-charttype='Item Fields Trend' 

--issueidentifier {Summary} 

To calculate a computed field within a specific time frame 

1 From a command line, type: 

im analytics --recomputehistory -g 

The Recompute Expression History For Field dialog box displays. 

317


318 

2 Select the following: 

From the Field to Compute list, select the computed field that you want to calculate. 

From the Start Time calendar, specify the starting calculation date and time. 

From the End Time calendar, specify the ending calculation date and time. 

From the Increment field, specify the interval to use for calculating the computed 

field. For example, if you select 1 Week, the computed field is calculated once a 

week. 

To clear previous history entries for the selected field between the specified times, 

select the Clear previous history option. 

3 To calculate the computed field, click OK. MKS Integrity calculates the compute field, 

storing the value in the history of the each item containing the computed field. 

Scheduling Computation Times 

To chart a computation over time, you can configure computed fields to create deltas daily, 

weekly, or monthly. For a static computed field, this configuration also saves the values to 

the computed field’s column in the item row of the database. By default, the MKS Integrity 

Administration Client includes scheduled event triggers that perform daily, weekly, and

Using Computed Fields to Calculate State Metrics 

monthly computations. You can edit the triggers to create your own schedule for when 

computations occur. 

IMPORTANT When you run a scheduled computation trigger, computed fields are 

calculated in field order. If an item contains a computed field that depends on the 

value of another computed field, the computed field containing the dependent value 

must come first in the field order. For example, if Field B depends on the value in 

Field A, then Field A must come before Field B in the field order. 

For more information on editing and running event triggers, see “Managing Event Triggers” 

on page 362 and the imFieldBean.computeHistoryNow() bean in the Event Trigger Java 

Documentation on the MKS Integrity Server home page. 

Using Computed Fields to Calculate State 

Metrics 

Using external information functions in computed fields, you can generate state metrics. State 

metrics are useful for determining item responsiveness. For example, you could use the 

DaysInState(state-name) function in a computed expression to calculate how many days 

a Defect item has been in the In Development state. The computed value is then stored in 

the computed field. For more information on creating computed fields, see “Creating 

Computed Fields” on page 313. 

Other possible metrics you can generate about your workflow are: 

how long an item stays in the workflow cycle 

how many times an item goes through the workflow cycle 

how many state transitions an item goes through 

the number of items that have not been modified in a certain time period 

The following external information functions are applicable to state metrics: 

DaysCurrentState() 

DaysCurrentPhase() 

DateFirstEntered(Submit) 

DateLastEntered(Submit) 

NumberOfEntriesToState(Submit) 

NumberOfHistoryEntries() 

NumberOfModifications(fieldName) 

DaysInState(Submit) 

DaysInPhase(Terminal) 

319


320 

For detailed information on the external information functions applicable to state metrics, see 

“Function Classes” on page 296. 

If you are using MKS Integrity’s configuration management and workflow and document 

management functionality, you can also generate the following types of metrics: 

Project metrics extract information from change packages to report how an individual 

project is progressing. 

Code metrics extract information from source code to report on a product’s status, also 

known as Portfolio Metrics. 

For more information on configuration management metrics, see “Using Configuration 

Management Project Metrics” on page 280. 

Example 

In the ABC Financial organization, a Defect type typically goes through the following 

workflow: 

Posted (initial state) 

In Development 

In QA 

Fixed (terminal state) 

Scenario 1 

To determine how many days a Defect spends in the Development phase, you create a 

computed field named Fix Time with the following underlying expression: 

daysInPhase(Development) 

Next, you query on Defects by the Fix Time field. To create a query, see the MKS Integrity 2009 


Using the query you created, you create a report or chart that summarizes the query data. To 

create a report or chart, see the MKS Integrity 2009 User Guide. 

Scenario 2 

To determine how many times a Defect went through the complete workflow cycle, meaning 

the number of times a Defect went from Posted to Fixed, you create a computed field named 

Number of Times Through the Workflow with the following underlying expression: 

numberOfEntriesToState(Posted) 

Next, you query on Defects by the Number of Times Through the Workflow field. To create 

and run a query, see the MKS Integrity 2009 User Guide. 

Using the query you created, you create a report or chart that summarizes the query data. To 

create a report or chart, see the MKS Integrity 2009 User Guide.

Security 

Security 

An administrator creates computed fields, which display as read-only fields that cannot be 

edited; however, an administrator may want to allow only certain users or groups to view 

them. To configure a computed field’s visibility, see “Setting Field Relevance” on page 133. 

If you create an expression using one or more fields that a user does not have permission to 

view, the user sees the calculated field value; however, they may be able to extrapolate 

backwards the value of a field that they do not have permission to view. 

In charts and reports, any user can create a computed expression. However, the fields that 

make up the computed expression must be visible to the user. 

Performance and Scalability 

When creating computed expressions, consider the following performance and scalability 

issues: 

The complexity of a computed expression and the following may result in long 

calculation times and impact the performance of the MKS Integrity Server: 

aggregate, query, and historical external information functions, such as 

HistoricFieldValue 

using the query external information function with the im analytics 

--recomputehistory command 

any historic report that includes fields using external information functions 

Depending on the number of dynamic computed fields in an item and the complexity of 

the underlying computed expressions, an item may take a long time to display because 

all of the computed fields in the item are calculated before viewing. 

Querying for items that include state metrics in computed fields may take a long time, 

for example, querying for items where DaysInState(Submit) > 365. You can 

improve the performance of the query by configuring the computed field as a static field. 

Static fields are computed periodically on a schedule and although they may take a long 

time to calculate initially, they may be indexed as columns in the items table after the 

calculation. Indexing calculated fields improves query performance. 

Do not create computed expressions for types that include vast amounts of items. For 

example, do not create computed expressions for only one type, such as a Defect type, 

that potentially includes tens of thousands of items. Instead, include computed 

expressions for an aggregate type, such as a Project type, that includes maybe 20 to 30 

items, but are related to tens of thousands of Defect items. 

321


322

C HAPTER EIGHT 

Change Packages 

Administering and Customizing Change Packages 

8 

This chapter provides information on customizing change packages for use with 

MKS Integrity and integrations. This chapter also contains information on administering 

configuration management change packages as part of a review process. 


“MKS Integrity Change Packages” on page 324 

“Configuration Management Change Packages” on page 343 

323

Chapter 8: Change Packages 

Where to Go From Here 

324 

The following table summarizes the available content for administering change packages: 

To Do This... See... 

Learn about change package types. “MKS Integrity Change Packages” on page 324 

Perform tasks with change package attributes, 

such as viewing, creating, editing, and deleting. 

Perform tasks with change package entry 

attributes, such as viewing, creating, editing, and 

deleting. 

Learn about the available operations users can 

perform on created change package types. 

How to create, edit, and delete entries used with 

created change package types. 

Learn about using configuration management 

change packages. 

Manage change packages by implementing a 

review process. 

MKS Integrity Change Packages 

“Modifying Change Package Attributes” on 

page 333 

“Modifying Change Package Entry Attributes” on 

page 336 

“User Operations for Created Change Package 

Types” on page 340 

“Modifying CP Entries for Created CP Types” on 

page 342 

“Configuration Management Change Packages” 

on page 343 

“Using Change Package Reviews” on page 344 

A change package is a group of changes made by a single user that can be considered a logical 

unit of work. Only the creator of a change package may add entries to that change package. 

Change package entries take the form of operations, both deferred and committed. When 

reviews are mandatory, change package entries take the form of pending entries before they 

are committed 

By default, MKS Integrity includes two change package types: configuration management 

and Implementer. A change package type consists of change package attributes and change 

package entry attributes. 

Users can query and filter items based on change package types and their attributes. Users 

can also generate reports to display information on change packages of the defined change 

package type. By default, all users are permitted to view configuration management and 

Implementer change packages.


The super administrator can customize and view permissions for the configuration 

management (si) change package type. 

NOTE For information on the Implementer change package type, see the 

MKS Implementer 2009 Installation and Administration Guide. For information on other 

integrations, such as the MKS integration with CA Endevor, contact MKS Customer 

Care. 

The GUI functionality for change package types is primarily intended for managing user and 

group permissions of change package types. 

The CLI provides powerful functionality for creating new change package types and 

modifying their attributes. The ability to create new change package types and modify their 

attributes is intended for use in creating custom integrations. The functionality is provided to 

define the schema for a change package to reproduce the attributes and entry types in 

MKS Integrity that exist in a third party tool for the purpose of creating compatibility 

between products. 

The CLI command documentation is provided in this section with specific options. For 

information on general options for CLI commands, see the MKS Integrity 2009 CLI Reference 

Guide for Workflows and Documents or man pages. The commands are also available through 

the MKS API. For information on using the MKS API, see MKS Integrity 2009 Integrations 

Builder Guide. 

Viewing Change Package Types 

Using the MKS Integrity Administration Client, you can manage change package types from 

one convenient location. Managing change package types is carried out through the Change 

Package Types view. 

To open the Change Package Types view from the MKS Integrity Administration Client, 

expand the Workflows and Documents node, and select Change Package Types. The 

Change Package Types view displays. 

By default, the data filter in the Change Package Types view displays all existing change 

package types. You can search for a specific change package type by typing in the text field. 

For more information, see “Filtering Data” on page 18. 

To view change package types in the CLI 

From the CLI, type the following command: 

im cptypes 

[--fields=field1[:width1],field2[:width2]...] 

[--fieldsDelim=value] 

cptypeID1, cptypeID2... 

325


326 

where: 

--fields=field1[:width1],field2[:width2]... specifies the fields and their width to display 

for change package types; fieldn can be any of: 

attributes displays the names of the change package attribute for the change 

package type. 

description displays the description for the change package type if one is 

available. 

displayName displays the name of the change package type that is displayed to 

users. 

entryAttributes displays change package entry attributes for the change package 

type. 

entryKey displays the entry key for the change package type. 

id displays the change package type ID. 

name displays the name of the change package type. 

permittedAdministrators displays a list of administrators who are permitted to 

edit the change package type. 

permittedGroups displays a list of groups who are permitted to edit the change 

package type. 

position displays the position order of the change package type. 

references displays any references to the change package type from other objects. 

--fieldsDelim=value specifies the string to be used as a delimiter between fields. 

cptypeID1, cptypeID2... specifies the IDs of the change package types you want to view. If 

no change package type IDs are specified, all change package types display. 

Changing Change Package Type Order 

You can change the position order of the change package type. 

To change the position order of a change package type 

1 From the MKS Integrity Administration Client, expand the node for Workflows and 

Documents, and select Change Package Types. The display pane shows the available 

change package types. 

2 Select Change Package Type > Reposition. The Reposition Change Package Types dialog 

box displays. 

3 Select the change package type in the list, and click Move Up or Move Down to change its 

order.


Editing Change Package Types 


Only partial editability of change package types is available from the GUI. For full editability, 

use the CLI. 

Only users assigned as change package administrators or a super administrator with Admin 

permission under the mks:im ACL are permitted to edit a change package type. For more 

information on the required ACL permission, see the MKS Integrity Server 2009 Installation 


IMPORTANT By default, the everyone group is allowed to view configuration 

management change packages. Once new permissions are set for the configuration 

management change package type, the default settings are overwritten. If you set 

new permissions where no parameters are specified, then no one can view 


NOTE You cannot edit the si (configuration management) change package type 

from the GUI. The change package type can only be modified through the CLI. 

To edit a change package type in the GUI 

1 From the MKS Integrity Administration Client, expand the node for MKS Integrity, 

and select Change Package Types. The display pane shows the available change 

package types. 

2 To search for the specific change package type you want to edit, type in the text filter (for 

more information, see “Filtering Data” on page 18). 

3 Highlight the change package type you want to edit, and select Change Package Type > 

Edit. The Edit Change Package Type dialog box displays. 

4 Edit options as necessary: 

To enter a description for the change package type, click the Description tab, and 

type in the field. 

To customize the order the change package types display in the list, click the 

Position tab to display the Position panel, and use the Move Up and Move Down 

buttons to change the order in the list. 

To specify which groups are allowed to view and modify change packages of the 

specified type, click the Permitted Groups tab. By default, the everyone group is 

permitted to view change packages of the specified type. 

327


328 


The Assigned list specifies the groups that are allowed to view or modify 

change packages of the change package type being edited. 

To assign permissions to a group, move the group from the Groups list to the 

Assigned list. 

To permit members of a group to modify changes packages for the editing 

change package type, in the Modify column click the corresponding check box. 

To specify which users and groups are allowed to administer the change package 

type, see “To assigning administrators to change package types” on page 329. 

To determine all objects that reference the change package type, click the References 

tab. For information on the contents of the tab, see “To manage admin provided 

objects in the MKS Integrity Administration Client” on page 244. 

To view a history of administrative changes for the change package type, click the 

History tab. The record of changes displays. 


To edit a change package type in the CLI 


where: 

im editcptype 

--entrykey=cpentryattribute1,cpentryattribute2,... 

--displayName=value 

--permittedAdministrators=u=user1,user2,…;g=group1,group2,… 

--permittedGroups=group1,group2:modify,… 

--description=value 

--position=|first|last|before:|after: 

cptypeID 

--entrykey=cpentryattribute1,cpentryattribute2,... specifies the entry key for the change 

package. The entry key is used as a unique identifier of a change package entry. An entry 

key must be defined for each change package type, or change packages cannot be 

created for that type. To create a change package entry attribute to use as the entry key, 

see “Creating Change Package Entry Attributes” on page 338. 

--displayName=value specifies the name of the change package that users see when 

creating change packages of that type. 

--permittedAdministrators=u=user1,user2,…;g=group1,group2,… specifies the 

users and groups that are allowed to view and edit permissions for the change package 

type.


--permittedGroups=group1,group2:modify,… specifies the groups that are allowed to 

view and edit change packages of the specified type. To allow a group to view and edit 

change packages of this type, append the group name with :modify, for example: 

--permittedGroups=everyone:modify 

--description=value specifies a description for the change package type. 

--position=|first|last|before:|after: specifies the 

position of the change package type. 

cptypeID specifies the ID of the change package type you are editing. 

For example, the command: 

im editcptype --permittedAdministrators=u=mchang 

--permittedGroups=QA,Development si 

sets user mchang as a permitted administrator who can edit and view the configuration 

management change package type, and also sets the groups QA and Development as the only 

groups having permission to view change packages of the configuration management type. 

To assigning administrators to change package types 

1 From the Edit Change Package Type dialog box (see “Editing Change Package Types” on 

page 327), display the Administrators tab. 

2 To query for one or more users or groups using a text search, type a name in the Show 

Principals containing text field. A list of users and groups displays in the results list 

becoming more specific as you type. 

To query for one or more users using pre-existing filters or to restrict your text query 

further, select one or more of the following filters from the that are filter list: 

Non LDAP Principals queries for users from non LDAP domains. This filter is 

enabled by default and displays as the active filter under the Show principals 

containing text field. Use the text search to query for one or more users in non LDAP 

domains. 

LDAP Principals queries for one or more users from an LDAP domain. The LDAP 

Query dialog box displays. 

329


330 

Using LDAP query syntax, type a query string, and click OK. The query results 

display in the results list of the Realm User Selection dialog box, and the LDAP 

Principals filter displays as the active filter under the Show principals containing text 

field. 

NOTE 

To create an LDAP query string, you should be familiar with your LDAP schema 

and LDAP query syntax. 

The MKS Integrity Administration Client does not perform syntax checking on 

LDAP query strings. 

After you query for a user in the LDAP Search Filter dialog box, you can query 

for a user in the results list using the Show principals containing text field. 

To clear the that are filter, select that are > Reset. 

3 From the results list, select the users and groups, and then do one of the following: 

To add the selected users or groups to the Assigned Administrators list, click +. 

To remove the selected users or groups from the Assigned Administrators list, 

click -. 

TIP To hide the principals list or Assigned Administrators list, click . To display 

the principals list or Assigned Administrators list, click . 

4 To assign administrators to the change package type, click OK. 

Viewing Change Package Types 

You can view the current permissions and other information for a change package type. 

To view information for a change package type in the GUI 

1 From the MKS Integrity Administration Client, expand the MKS Integrity node, and 

select Change Package Types. The display pane shows the available change package 

types. 

2 Highlight the change package type you want to customize permissions for, and select 

Change Package Type > View Definition for a selected change package. The Change 

Package Type dialog box displays. 

3 Information displayed in fields and lists is non-editable. For field and list descriptions, 

see “Editing Change Package Types” on page 327. When you are finished viewing the 

information, click Close.

To view information for a change package type in the CLI 

From the CLI, run the following command: 

where: 

im viewcptype 

--[no]showAttributes 

--[no]showEntryAttributes 

--[no]showEntryKey 

--[no]showHistory 


--[no]showAttributes displays the change package attributes. 


--[no]showEntryAttributes displays the change package entry attributes. 

--[no]showEntryKey displays the change package entry key. 

--[no]showHistory displays the history of changes to the change package type 

attributes. 

cptypeID1, cptypeID2... specifies the IDs of the change package types you are viewing. 


im viewcptype si 

displays information on the configuration management change package type, including 

attributes, entry attributes, permitted groups, and administrators. 

Creating Change Package Types 

The ability to create new change package types is intended for use in creating custom 

integrations. The functionality is provided to define the schema for a change package to 

reproduce the attributes and entry types in MKS Integrity that exist in a third party tool for 

the purpose of creating compatibility between products. 

IMPORTANT An entry key must be defined for the change package type you are 

creating, or you cannot create entries for any change packages of that type. For more 

information, see “Editing Change Package Types” on page 327. 

To create a change package type in the CLI 


im createcptype 


--permittedAdministrators=u=user1,user2,…;g=group1,group2,… 

--permittedGroups=group1,group2:modify,… 


--position=|first|last|before:|after: 

331


332 

where: 

--displayName=value specifies the name of the change package type. 

--permittedAdministrators=u=user1,user2,…;g=group1,group2,… specifies the 

users and groups that are allowed to view and edit permissions for the change package 

type. 

--permittedGroups=group1,group2:modify,… specifies the groups that are allowed to 

view and edit change packages of the specified type. To allow a group to view and edit 

change packages of this type, append the group name with :modify, for example: 

--permittedGroups=everyone:modify 

--description=value specifies a description for the change package type. 

--position=|first|last|before:|after: specifies the 

position of the change package type. 


im createcptype 

--displayName=ExternalCPs 

--permittedAdministrators=u=mchang 

--permittedGroups=QA,Development si 

creates change package ExternalCPs and sets user mchang as a permitted administrator 

who can edit and view the change package type, and also sets the groups QA and 

Development as the only groups having permission to view change packages of the type. 

Deleting Change Package Types 

You can delete change package types that are not needed; however, you cannot undo an 

im deletecptype operation or restore deleted change package types. You cannot delete the 

si (configuration management) change package type. 

To delete a change package type in the CLI 


where: 

im deletecptype 

--[no]confirm 


--[no]confirm specifies if to confirm deletion of the change package type. The default 

is to confirm. 

cptypeID1, cptypeID2... are the IDs of the change package types you are deleting.


im deletecptype --noconfirm devcp 

deletes change package devcp without confirmation. 

Modifying Change Package Attributes 


The ability to modify change package attributes is intended for use in creating custom 

integrations. The functionality is provided to define the schema for a change package to 

reproduce the attributes and entry types in MKS Integrity that exist in a third party tool for 

the purpose of creating compatibility between products. 




the MKS API. For information on using the MKS API, see the MKS Integrity 2009 Integrations 


Viewing Change Package Attributes 

To view change package attributes in the CLI 


im cpattributes 

--cpType=change package type 

--fields=field1[:width1],field2[:width2]... 

--fieldsDelim=value 

cpattributeID1, cpattributeID2... 

where 

--cpType=change package type specifies the type of change package to view attribute 

details for. 

--fields=field1[:width1],field2[:width2]... specifies the attribute fields to display, where 

fieldn can be any of the following: decimalPlaces, description, displayFormat, 

displayName, id, isMandatory, isReadOnly, maxLength, name, position, strings, 

type. 


cpattributeID1, cpattributeID2... specifies the IDs of the change package attributes you 

want to view information for. If no IDs are specified, all change package attributes for 

the specified change package type are displayed. 

333


334 

Viewing Change Package Attribute Details 

To view change package attribute details in the CLI 


where 

im viewcpattribute 




--cpType=change package type specifies to display details for change package attributes 

of specified change package type. 

--[no]showHistory specifies if to display the history of changes to the change package 

attribute. 


want to view details for. 

Creating Change Package Attributes 

To create a change package attribute in the CLI 


where: 

im createcpattribute 

--dataType=[integer|stringlist|float|logical|date|string|user|cpid] 

--maxLength=value 


--decimalPlaces=value 

--displayFormat=[truefalse|tf|yesno|yn] 


--[no]mandatory 

--strings=value 


--name=value 

--position=[first|last|before:|after:] 


specifies the attribute data type. 

--maxLength=value specifies the maximum length of value for the attribute. This option 

is valid for data types string, stringlist, and cpid. 

--cpType=change package type specifies the name of change package type the attribute is 

being created for. 

--decimalPlaces=value specifies the number of decimal places in the value the 

attribute takes. This option is valid for data type float.


--displayFormat=[true|false|t|f|yes|no|y|n] specifies if to display the format 

of the change package attribute value. This option is valid for data type logical. 

--displayName=value specifies if to display name of the change package attribute. 

--[no]mandatory specifies if the change package attribute value is mandatory. 

--strings=value specifies string values for the attribute. This option is valid for data 

type stringlist. 

--description=value specifies a short description for the attribute. 

--name=value specifies the name for the attribute being created. 

--position=[first|last|before:|after:] specifies the position of 

the attribute you are creating in the attribute order. 

Editing Change Package Attributes 

To edit a change package attribute in the CLI 


where: 

im editcpattribute 









cpattributeID 




attribute takes. This option is valid for data type float. 


of change package attribute value. This option is valid for data type logical. 

--displayName=value specifies if to display the name of the change package attribute. 

--[no]mandatory specifies if the change package attribute value is mandatory. 




335


336 


the attribute you are creating in the attribute order. 

cpattributeID specifies the ID for the change package attribute you are editing. 

Deleting Change Package Attributes 

You cannot undo the im deletecpattribute operation, and you cannot restore deleted 

change package attributes. 

To delete a change package attribute in the CLI 


where: 

im deletecpattribute 


--[no]confirm 


--cpType=change package type specifies the change package type to delete the change 

package attribute from. 

--[no]confirm specifies if to confirm the change package attribute deletion. The 

default is to confirm. 



Modifying Change Package Entry Attributes 






Viewing Change Package Entry Attributes 

To view change package entry attributes in the CLI 


im cpentryattributes 


--fields=field1[:width1],field2[:width2]... 

--fieldsDelim=value 

cpattributeID1, cpattributeID2...

where: 


--cpType=change package type specifies the change package type for the change package 

entry attribute. 

--fields=field1[:width1],field2[:width2]... specifies the fields to display, where fieldn 

can be any of the following: decimalPlaces, description, displayFormat, 

displayName, id, isMandatory, isReadOnly, maxLength, name, position, strings, 

type. 



want to view. If no IDs are specified, all change package attribute IDs are displayed. 

Viewing Change Package Entry Attribute Details 

To view change package entry attribute details in the CLI 


where: 

im viewcpentryattribute 






--[no]showHistory specifies if to display the history of changes to the change package 



want to view details for. If no IDs are specified, all change package attribute IDs are 

displayed. 

337


338 

Creating Change Package Entry Attributes 

To create a change package entry attribute in the CLI 


where: 

im createcpentryattribute 


--maxLength=value 








--name=value 



specifies the attribute data type. 

--maxLength=value specifies the maximum length of value for the entry attribute. This 

option is valid for data types string, stringlist, and cpid. 

--cpType=change package type specifies the name of change package type the entry 

attribute is being created for. 




of change package entry attribute value. This option is valid for data type logical. 

--displayName=value specifies if to display name of the change package entry attribute. 

--[no]mandatory specifies if the change package entry attribute value is mandatory. 




--name=value specifies the name for the change package entry attribute being created. 


the change package entry attribute you are creating in the attribute order.

Editing Change Package Entry Attributes 

To edit a change package entry attribute in the CLI 


where: 

im editcpentryattribute 









cpentryattributeID 







of value. This option is valid for data type logical. 

--displayName=value specifies if to display the name of the change package entry 

attribute. 

--[no]mandatory specifies if the change package entry attribute value is mandatory. 

--strings=value specifies a string of values for the change package entry attribute. This 

option is valid for data type stringlist. 

--description=value specifies a short description for the change package entry 

attribute. 


the change package entry attribute you are creating in the attribute order. 

cpentryattributeID specifies the ID for the change package entry attribute you are editing. 

Deleting Change Package Entry Attributes 

You cannot undo an im deletecpentryattribute operation, and you cannot restore deleted 

change package attributes. 

339


340 

To delete a change package entry attribute in the CLI 


where: 

im deletecpentryattribute 


--[no]confirm 




--[no]confirm specifies if to confirm deleting the change package entry attribute. The 

default is to confirm. 



User Operations for Created Change Package Types 

This section contains commands available to perform user operations on change package 

types created for your system. 






TIP In addition to the commands in this section, you can also use commands 

im viewcp and im cps on change package types you have created. See the man 

pages for details on using those commands. 

Creating Change Packages 

To create a change package in the CLI 


im createcp 

--attribute=value 

--issueID=value 

--type=change package type

where: 


--attribute=value specifies the attribute of the form name=value, where name is the 

attribute name and value is the new value of that attribute. 

NOTE You must enter using option --attribute=value any attribute that is 

mandatory for the change package type. 

--issueID=value specifies the item ID to create the change package for. 

--type=change package type specifies the type of the change package to be created. 

Editing Change Packages 

To edit a change package in the CLI 


where: 

im editcp 


--filter=type:name 

cpid 

--attribute=value specifies the attribute of the form name=value, where name is the 

attribute name and value is the new value of that attribute. 

--filter=type:name specifies the filter used to refine change package selections. 

cpid specifies the change package you are editing. 

Deleting Change Packages 

You cannot undo an im deletecp operation, and you cannot restore deleted change 

packages. 

To delete a change package in the CLI 

where 

im deletecp 

--[no]confirm 

--[no|confirm]deleteEntries 

cpid1, cpid2... 

--[no]confirm specifies if to confirm each individual change package being deleted. 

--[no|confirm]deleteEntries specifies if to delete (or confirm deleting) the change 

package entries. 

cpid1, cpid2... specifies the change packages you are deleting. 

341


Modifying CP Entries for Created CP Types 

342 






Creating Change Package Entries 

To create change package entries in the CLI 


where: 

im createcpentry 


--changePackageID|--cpid=value 

--attribute=value specifies the value of a change package entry attribute (value is of 

the form attributeName=attributeValue). 

--changePackageID|--cpid=value specifies the ID of the associated change package. 

Editing Change Package Entries 

To edit change package entries in the CLI 


im editcpentry 



cpentry 

where: 

--attribute=value specifies the value of a change package entry attribute (value is of 

the form attributeName=attributeValue). 


cpentry specifies the name of the change package entry you editing. The format of cpentry 

is determined by the entry key for the change package type. For example, an 

Implementer change package entry is specified as member:objectcode. 

Deleting Change Package Entries 

You cannot undo an im deletecpentry operation, and you cannot restore deleted change 

package entries.

To delete change package entries in the CLI 


where: 

im deletecpentry 

--[no]confirm 


cpentry 

Configuration Management Change Packages 

--[no]confirm specifies if to confirm deleting the change package entry. The default is 

to confirm. 


cpentry specifies the name of the change package entry you deleting. 


A change package is a group of changes made by a single user that can be considered a logical 

unit of work. Only the creator of a change package can add entries to that change package. 

Change package entries are added when you specify a change package while performing 

member operations. 

A change package acts as a log of both the changes to members and subprojects that have 

already been committed to the repository (server), and the changes that are only visible to the 

user on the desktop and not committed to the repository (deferred). When change package 

reviews are mandatory, a change package acts as a control placed on changes to the 

repository by making them pending before they are committed. 

A change package is open until you close it, which signifies that work on the change is 

completed. When reviews are mandatory, a change package has additional states before it is 

closed. 

The following rules apply when using change packages: 

Each change package has a unique change package ID (CP ID). The CP ID is a colon 

separated identifier of the form: 

: 

NOTE If the MKS Integrity integration is enabled, the item ID is used as the 

container ID. 

343


344 

Only the creator of a change package or a change package administrator can close a 

change package. 

Once a change package is closed, it can only be re-opened by a change package 

administrator. If a change package has been propagated through Apply CP or 

Resync CP, it cannot be reopened, even by a change package administrator. 

You can expand the capabilities of change packages by associating them with items to take 

advantage of MKS Integrity’s workflow and document management. 

For information on integrating workflow and document management with configuration 

management, and setting up configuration management change packages, see the 


Using Change Package Reviews 

A change package review is a review of changes by specified reviewers before the changes 

are committed to the server repository. 

If change package reviews are mandatory globally, then all change packages must progress 

through the change package review process. 

If change package reviews are mandatory at the project level only, then a change package 

only progresses through the review process if it contains at least one entry associated with a 

member in a project that requires a review. Change packages follow the review process 

before the changes are successfully committed to the server repository. All other change 

packages function as non-review change packages. 

A change package reviewer is a user specified by your administrator to review change packages 

containing members associated with specific projects. The reviewer may be individually 

specified or a member of a specified reviewer group. In the case of a reviewer group, any 

member of that group casts an accept or reject vote on behalf of the entire group. 

A change package watcher is a user specified by your administrator who is notified when a 

reviewed change package is closed after being successfully committed to the repository. 

Change package watchers may be individually specified or a member of a specified watcher 

group. 

A super reviewer is a user with permission to vote on change packages, but who is not 

required to be a listed reviewer for the change package. Voting as a super reviewer overrides 

all other votes. For example, casting an accept vote as a super reviewer is sufficient for 

accepting the change package. 

For more information on setting up change package reviewers and watchers, see the 

MKS Integrity Server 2009 Installation and Configuration Guide.

How Change Package Review Works 


The following summarizes how the change package review process works: 

1 The review starts when a developer (change package creator) submits a change package 

containing deferred and member lock entries and subproject entries (or any combination 

of deferred, pending, or committed entries). 

2 MKS Integrity creates a pending change package entry for each deferred and member 

lock entry, and, where necessary, pending revisions. 

3 Change package reviewers (possibly a mentor or a senior developer) accept or reject the 

change package. 

4 The change package entries are either committed to the database (accepted case), or the 

developer opens the change package and continues development (rejected case). 

NOTE Although the review process describes submitting change packages with 

deferred entries thereby creating pending entries, if deferred operations are not 

mandatory you can create pending entries at the time the operation is completed by 

clearing the deferred option. You can then submit the change package containing 

the pending entries for review. Subproject operations are always created as pending 

entries in a change package when reviews are mandatory. 

Pending Entries 

and Revisions 

Reviewers 

Developer 

Submit Change 

Package 

Accept or Reject 

Accept 

Change Package review process 

Reject 

Committed 

Open and Work 

Repository 

Developer 

The MKS Integrity 2009 User Guide gives full details of the change package review process. 

The change package review process is controlled through the use of policies and permissions. 

345


Review Benefits 

346 

For information on required policies and permissions, see the MKS Integrity Server 2009 


The benefits of using reviews are: 

Reviews provide a formal and enforceable review process. 

Reviews force changes to be reviewed before they are committed to the repository 

thereby providing control over what changes are accepted into a project by making 

operations pending. Unlike deferred operations, which are stored only client side, 

pending operations are stored server side and so are visible to all users. This can be 

useful near the end of a release cycle as a pre-commit review of changes before they are 

included in a release build. 

Pending revisions are not a part of the current state of the project until they have been 

reviewed (not at member revision); however, they remain in the member history and can 

be checked out (without a lock) by users (other than the creator) for review. 

If the project is one that users will be building from, reviews can remove the need for 

using a variant project to review changes manually. 

Reviews provide an alternative to manual post-commit review while recording all of the 

review information. 

Change Package Review E-mail Notification 

By default, e-mail notifications are sent to the change package creator, reviewers, and 

watchers when events occur in the review process. MKS Integrity uses a server-side event 

trigger to provide e-mail notifications. The events that trigger an e-mail notification are 

described as part of the review workflow in the MKS Integrity 2009 User Guide. 

If you are using e-mail notification for change package reviews, ensure that triggers are 

enabled in the si.properties file (see “Overview of Configuration Management Triggers” 

on page 374). 

If you are using LDAP, e-mail addresses are obtained from the realm. Otherwise, e-mail 

addresses take the following form (the domain must first be specified in the 

env.properties file): 

@domain 

For e-mail notifications, you can change the following: 

who receives e-mail (the reviewer, creator, or watcher) 

when users receive e-mail (what events trigger the script) 

subject and body content of the e-mail (what information the e-mail contains)


You can modify the trigger events that cause an e-mail notification by editing the following 

file: 

installdir/data/triggers/events/global.events 

For more information on events, see “The syntax for an event is:” on page 375. 

You can modify the trigger script by editing the following file: 

installdir/data/triggers/scripts/samples/changePackageNotification.js 

For more information on scripts provided by MKS, see “Sample event triggers are provided 

in:” on page 390. 

347


348

C HAPTER NINE 

Event Triggers 

Using Scripts to Automate Tasks and Calculate Data 

9 

An event trigger is a block of code that the MKS Integrity Server or MKS Integrity Client 

runs when a predefined event occurs. The block of code that runs is called a trigger script. 

For example, you could set up an event trigger that sends an e-mail notification to a user 

when a user’s lock is downgraded, or changes the assigned user when an item’s state 

changes. 

This chapter contains the following sections: 

“Event Categories” on page 350 

“About Trigger Scripts” on page 350 

“JavaBeans” on page 354 

“Overview of Workflow and Document Triggers” on page 355 

“Overview of Configuration Management Triggers” on page 374 

“Debugging Configuration Management Client-Side Environment Variables” on 

page 392 

“Using the MKS API in Event Triggers” on page 396 

“Running Custom Java Code” on page 397 

“Tips and Best Practices” on page 399 

349

Chapter 9: Event Triggers 

Event Categories 

350 

An event trigger is an association between a predefined event and the script that is to be 

executed when that event occurs. These scripts fall into two categories based on when they 

occur and if they modify entries in the database. The two categories are as follows: 

Pre-event triggers are executed before the event occurs, for example, they can modify an 

item being changed and prevent changes to an item. 

Pre-condition triggers are pre-events pertaining to items that exist under the 

document model, and operate under the same principles as pre-event triggers. 

Post-event triggers are executed after the event occurs, for example, returning 

information on items in the database and perform actions such as sending mail, but they 

cannot make modifications to items. 

About Trigger Scripts 

Event triggers are scripted using JavaScript (JavaScript is not the same as Java; however, 

trigger scripts do support Java code) and follow the standard established by the European 

Computer Manufacturers Association (ECMA) in ECMAScript. Additional information on 

ECMAScript is available at the ECMA Web site: 

http://www.ecma-international.org/ 

NOTE Document Object Model (DOM) objects are unsupported in trigger scripts. 

JavaScript is used to access JavaBeans on the MKS Integrity Server to work with workflow 

and document data, and configuration management data. For more information on 

JavaBeans, see “JavaBeans” on page 354. 

CAUTION JavaScripts are expressive and allow scripts to perform most operations 

that could be programmed using Java. The scripts run under the permissions of the 

administrator. The administrator is responsible for ensuring trigger scripts do not 

perform any operations that could affect system or file security.

JavaScript Language Elements 


The intent of this section is not to teach JavaScript, as MKS recommends that you already be 

familiar with JavaScript. This section outlines useful JavaScript language elements commonly 

used in trigger scripts. 

Variables 

JavaScript variables are type independent (integer, floating point, string, etc.) and can hold 

Java objects (sets, strings, etc.). Unlike Java, you do not have to declare the type for JavaScript 

variables and the type can be reset by simply assigning a different value. 

IMPORTANT JavaScript variables are case-sensitive, for example, the variable myvar 

is different from myVar. Case sensitivity can be the cause of some trigger file bugs. 

To declare a variable, use the following syntax: 

var = ; 

for example, the variable “i” can be reassigned to the following different types: 

var i = 0; 

var i = 1.5; 

var i = “This is a string” 

var i = Packages.com.mks.api.IntegrationPointFactory.getInstance() 

Operators 

NOTE Many MKS Beans return Java objects that can be stored in JavaScript 

variables. 

Most of the operators used in trigger scripts are similar to other programming languages; 

however, there are some slight differences. For example, there is a fundamental difference 

between the assignment operator “=“ and the comparison operator “==“. Be careful not to 

use “=“ to mean “equal to” in a comparison statement. 

TIP The string operator “+” is very useful for constructing error and log messages in 

trigger scripts. 

351


352 

The following tables outlines operators used in script triggers: 

Arithmetic Operators Comparison Operators 

Addition: + 

Subtraction: - 

Multiplication: * 

Division: / 

Modulus: % 

Increment: ++ 

Decrement: -- 

Control Structures 

To execute code based on conditions, use the if…else statement, for example: 

if (condition) { 

// Code to be executed if condition is true 

} else { 

// Code to be executed if condition is not true 

} 

To execute code a specified number of times, use the for loop, for example: 

for (var=startvalue;var 

Greater than or equal to: >= 

Less than: < 

Less than or equal to:

Control Structures and Functions 


To execute code a specified number of times while a condition is true, use the while loop, for 

example: 

while (var


JavaBeans 

354 

Exception Handling 

To trap errors in trigger scripts, use the try…catch…finally control structure, for example: 

where: 

try { 

// Code to be executed 

} catch (error) { 

// Code to execute there is an error 

} finally { 

// Optional – always execute this code 

} 

The try block contains the code you want to run. 

The catch block contains the code you want to run if an error occurs. 

The finally block (optional) contains code that always runs before the control structure 

ends. 

TIP As a best practice, MKS recommends using try..catch whenever possible. 

A JavaBean is a reusable Java software component (conforming to Sun’s Enterprise JavaBean 

specification) used to pass information from the MKS Integrity Server to the trigger script. 

Beans are accessed through JavaScript using the lookupBean() function from the Bean 

Scripting Framework (BSF). For example: 

var envBean = bsf.lookupBean("siEnvironmentBean"); 

There are different Beans for workflow and document management, and configuration 

management information. Deploy specific Beans are included with both types of Beans. 

The siEnvironmentBean is used by both types of Beans, even though it starts with “si”.

Overview of Workflow and Document Triggers 

Information on available MKS Beans is located in the Event Trigger Java Documentation on 

the MKS Integrity Server homepage: 

http://localhost:port/documentation/javadocs/triggers/index.html 

When writing triggers, refer to the Event Trigger Java Documentation frequently to see what 

Beans and methods to use. 

Note the following about using the Event Trigger Java documentation: 

The lower left frame is a listing of all the available Beans. 

LocalTriggerManager Beans are for workflow and document management, and the 

rest are a mixture of workflow and document management; configuration management; 

and Deploy Beans. 

Search for names that contain the command or object you want to work with. 

To get the name of a Bean to use in a look up statement, review the documentation for 

the Bean’s getExposedName() method. 

The Index link at the top of the right frame lists all the methods alphabetically and is 

useful to search if you know the first part of a method you want to use. 


Workflow and document event triggers execute in response to an action by the MKS Integrity 

Client, and reside on the MKS Integrity Server where they are executed (client-side triggers 

are unsupported). 

Administration of workflow and document event triggers is performed in the MKS Integrity 

Administration Client; however, you can also create, edit, and run them from the CLI. For 

more information on managing workflow and document event triggers, see “Using 

Workflow and Document Event Triggers” on page 361. 

355


Workflow and Document Event Categories 

356 

Workflow and document triggers fall into three categories of events: 

Rule based events run because of an action made by a user. The following are some of the 

ways you can use rule-based change triggers: 

When an item changes to a specified state, iterate over the change packages and 

then resync them into the reference tree. 

When an item is updated, change a field in a related item. 

If an item is in an open state and all of the reverse related items (items pointing to it) 

are in a final state, move the item into a final state as well. 

For more information on rule based triggers, see “Creating Rule Based Change Triggers” 

on page 363. 

Scheduled events run in isolation and do not require an action by a user. The following 

are some of the ways you can use scheduled triggers: 

If the item is in a state and unchanged for a specified length of time, send e-mails to 

assigned users and relevant managers. 

If the priority is at the maximum level, send an e-mail to the manager. 

If a critical item has been in a beginning state for a number of days, send an e-mail to 

the project manager. 

For more information on scheduled event triggers, see “Creating Scheduled Triggers” on 

page 367. 

Other events run when: 

time entry is changed by a user, for example, when a time entry is changed on an 

item, update the payroll system 

item tree is copied 

item is branched 

item is labeled 

test result is created, modified, or deleted 

For more information on other event triggers, see “Creating Other Triggers” on 

page 370.



Triggers fire in their position order. If there are two rule-based triggers with the same 

rule, the higher position (lower number) trigger fires first. If there are two scheduled 

triggers set for the same date and time, the high position (lower number) trigger fires 

first. 

Triggers have administrator privileges and may override user permissions, but the 

history records the changes as having been performed by the user. 

If a pre-event trigger modifies or creates another item, the secondary item becomes part 

of the transaction. Either all of the modifications made to all of the items succeed or none 

do. 

To ensure a pre-event trigger does not run more than once, when it has completed, other 

secondary triggers are not permitted to obtain that item. 

Transactionality of Workflow and Document Event Triggers 

The event trigger operation occurs in the following sequence: 

Transaction occurs, and a commitment is made that the pre-event trigger will run. 

Pre-event trigger runs before any modifications have been made to the database. If an 

error occurs (or a trigger veto) in the pre-event trigger, no changes are made to the 

database, the transaction is rolled back, and the database is returned to its original state. 

All scripts, triggers, and assignments are stopped. 

Commit occurs where the change is made to the database. 

Post-event trigger runs only after all data has been committed to disk. 

357


358 

Other items can only be modified by running a chain of pre-event triggers. When the server 

starts a transaction, the server runs in order: transaction, pre-event trigger chain, commit 

transaction, and post-event trigger chain. 

NOTE Chains of scheduled triggers run separately from chains of rule-based change 

triggers. For more information on rule-based triggers, see “Overview of Workflow 

and Document Triggers” on page 355. 

If a pre-event trigger attempts to modify another item or create another item, the secondary 

item is added to a list of items that become part of the current transaction. 

Either all of the modifications made to all of the items must succeed or none of them. This 

means any pre-event triggers for the secondary item must also run, and they are subject to 

the same rules as the triggers running for the primary item. 

To ensure a pre-event trigger does not run more than once, when the pre-event trigger has 

completed, other secondary triggers are not permitted to obtain that item again. 

All changes made by event triggers bypass the server permission checking. While the history 

records all changes as having been performed by the user, the trigger is not required to 

conform to the permissions for that end user. 

Planning Workflow and Document Triggers 

To avoid unpredictable event trigger behavior, plan your event triggers in the following way: 

1 Decide if you want to create a trigger that runs on a specific day and time, or a trigger 

that runs based on an action by a user. 

2 If it is a rule-based trigger decide if it is going to be a pre-event trigger or post-event 

trigger. 

3 Determine the base tasks the trigger needs to perform, and select the required scripts 

from the library. 

4 Determine what fields, if any, the trigger will change or what information the trigger 

collects from the database. 

5 Identify which user permissions are overridden by the trigger and how that affects 

security. 

6 Identify potential constraint based conflicts, such as mandatory fields for state changes 

or closed change package requirements. 

Script Library for Workflow and Document Triggers 

Workflow and document event triggers use pre-created scripts from a server-side library. 

You can modify existing scripts or add new ones to build the library over time.


MKS Integrity provides pre-created scripts, which are available in the script library found in: 

installdir/data/triggers/scripts 

The list of pre-created scripts provided may vary depending on the server implementation of 

an organization. Some of the pre-created scripts available include: 

assignment.js automatically assigns an item based on a file-driven set of criteria. 

signatureRequired.js requires an electronic signature for changes to items. For more 

information, see “Setting Up Electronic Signatures” on page 241. 

sum.js computes simple metrics through a relationship tree. This trigger is 

automatically installed by the Rules panel when editing fields and when a Summation 

of Relationship Tree rule is installed. 

Coding Workflow and Document Triggers 

The following section provides an overview of workflow and document trigger coding. For 

detailed information about creating, editing, and managing workflow and document trigger 

scripts, see “Using Workflow and Document Event Triggers” on page 361. 

Script Description 

The initial comment text in a workflow and document trigger script displays on the 

Description tab in the MKS Integrity Administration Client. HTML tags provide additional 

formatting. 

For example, the following script code: 

// MKS Integrity PRE-Event Trigger 

// 

// Enforce mandatory fields on a State Transition 

// 

// Base MKS Integrity has the notion of a mandatory field; however, 

this makes a field mandatory when it is given a state, no matter how 

it got into that state. 

displays as the following in the Description tab: 

MKS Integrity PRE-Event Trigger 

Enforce mandatory fields on a State Transition 

Base MKS Integrity has the notion of a mandatory field; however, this 

makes a field mandatory when it is given a state, no matter how it got 

into that state. 

359


360 

Script Parameters 

Trigger scripts take parameters to promote script reuse, rather than limiting a script by hardcoding 

values in it. 

Parameter lines are placed after the description code block. Commented lines starting with 

@param define the script parameters. The first word after @param is the field type (String, 

Boolean, MultiString). 

After the field type, the remaining text is the name of the parameter. The parameter name 

appears on the Parameters tab in the MKS Integrity Administration Client. Commented lines 

until the next @param or end of comments appear as tooltips for the parameter. 

For example, the following script code: 

// &param String Mandatory Fields 

// Name of the mandatory field, or fields. If a list, then each must 

// be separated by commas. 

where String is the field type and Mandatory Fields is the parameter name. 

displays as: 

Field Parameters 

To get a list of types, use @param Type: 

// @param Type New Type 

To get a list of states, use @param State: 

// @param State New State 

To get a list of fields, use @param Field:: 

For example, to get a list of relationship fields type: 

// @param Field:relationship New Relationship 

This prevents introducing typographical errors into trigger parameters and having to look up 

type, state, and field names. The syntax for all field types is the field type name (all lowercase 

and no spaces), for example, Long Text is “longtext”.


Referencing Workflow and Document Beans in Trigger Scripts 

First, you need to reference the applicable workflow and document Beans you want to use in 

your script. Refer to the Event Trigger Java Documentation off the server homepage. Beans 

prefaced with LocalTriggerManager are workflow and document Beans. 

TIP You can get the name of a Bean by looking at the GetExposedName() method 

in the Event Trigger Java Documentation. 

Once you know the Bean name, look up the Bean in the trigger script, for example: 

var params = bsf.lookupBean(“parametersBean”); 

Useful workflow and document Beans include: 

ScriptEnvironmentBean 

Contains information about the environment in which the script is running. 

ScriptParametersBean 

Contains any parameters passed to the script. 

LocalTriggerManager.ScriptServerBean 

Contains MKS Integrity Server information (types, states, etc.). 

LocalTriggerManager.ScriptIssueDeltaBean 

Contains item information before a change and after. 

Example of a Workflow and Document Trigger 

Once you have referenced the necessary Beans, you can begin coding the rest of the trigger 

according to your needs. For example, to retrieve and set workflow and document data type 

the following: 

Save the trigger script to the trigger library installdir/data/triggers/scripts. 

Using Workflow and Document Event Triggers 

To use workflow and document event triggers, you need to know the following: 

361


362 

“Managing Event Triggers” on page 362 

“Creating Event Triggers” on page 363 

“Viewing Event Triggers” on page 372 

“Editing Event Triggers” on page 372 

“Deleting Event Triggers” on page 373 

“Resolving Event Triggers” on page 373 

Managing Event Triggers 

You can manage event triggers from one convenient location. Managing event triggers is 

carried out through the Triggers view. 

To open the Triggers view, in the MKS Integrity Administration Client under Workflows 

and Documents select Triggers. (For general information about the MKS Integrity 

Administration Client, see “Introduction” on page 10.) The Triggers view displays. 

By default, the data filter in the Triggers view displays all existing event triggers. You can 

search for a specific event trigger by typing in the text field. For more information, see 

“Filtering Data” on page 18. 

TIP To show the last run time for a trigger, you can also add a column for the Last 

Run Time. To add this column, right click the column header bar, and select Last 

Run Time.

You can perform the following tasks: 

create a new event trigger that runs: 


by a set of rules (see “Creating Rule Based Change Triggers” on page 363) 

on a schedule (see “Creating Scheduled Triggers” on page 367) 

whenever a time entry is changed (“Creating Other Triggers” on page 370) 

whenever a test result is created, modified, or deleted (“Creating Other Triggers” on 

page 370) 

copy an event trigger (see “Copying Event Triggers” on page 371) 

run a scheduled event trigger (see “Running Scheduled Triggers” on page 371) 

edit an event trigger (see “Editing Event Triggers” on page 372) 

view an event trigger’s details (see “Viewing Event Triggers” on page 372) 

delete an event trigger (see “Deleting Event Triggers” on page 373) 

change the order of event trigger resolution (see “Resolving Event Triggers” on 

page 373) 

NOTE Chains of scheduled triggers run separately from chains of rule-based change 

triggers. Consider the order that scheduled triggers are listed in separately from the 

order rule-based change triggers are listed in. 

Any changes you make in the Triggers view have an immediate effect on your MKS Integrity 

database. 

Creating Event Triggers 

You can create a rule-based event trigger, scheduled event trigger, or time entry event 

trigger. Each trigger requires a name and position in addition to the rule or schedule 

parameters. 

Creating Rule Based Change Triggers 

Rule-based change triggers run whenever an item is changed by a user in a manner matching 

a defined rule. Any modifications appear as if made by the original user who modified or 

created the item that caused the trigger to run. 

NOTE When using a trigger to prevent a user action, ensure the trigger displays an 

error message to the user and the user has a course of action available. 

The general steps required to create a rule-based change trigger are as follows: 

1 Select the rule-based change trigger type. 

363


364 

2 Provide a description for the trigger. 

3 Define a rule for when the trigger runs. 

4 Select a script file from the library for the trigger to run. Then, if required, fill out the 

parameters for it. 

NOTE Backlashes (\) in parameters are truncated after you save and run the trigger, 

for example, in a directory path. To avoid this, use forward slashes (/). 

5 Assign values to the fields the trigger modifies when it runs (if the trigger is one that 

modifies field values in the database). 


Ensure each field the user is required to update is legally updateable by that user. 

If the state of an item is being changed, ensure the state transition is valid. 

If the state of an item is being changed and the new state is one that does not allow open 

change packages, ensure all of the change packages are closed before the state change is 

made. 

Ensure all fields that are mandatory for the final state in the workflow contain values. 

Validations are performed before any trigger code runs. The pre-event trigger only runs 

if all validations are successful. Be aware that the trigger has administrator privileges 

and may override the user permissions. 

If your rule contains only one condition, you do not need to use And and Or nodes. 

If no rule is defined for a rule-based change trigger, the trigger runs every time any user 

performs an action on any item in MKS Integrity. 

Pre- and post-options are not available for scheduled triggers. 

Scripts listed under the samples directory (for example, samples/ 

breakLockNotification.js) are for configuration management and are not 

applicable to workflow and document management. 

To create a rule-based change trigger in the GUI 

1 In the Triggers view (see “Managing Event Triggers” on page 362), select Trigger > 

Create. The Create Trigger dialog box displays the Type panel. 

2 In the Name field, type a name for the new event trigger. 

3 Select Rule. 

4 To enter a description for the event trigger (optional), click the Description tab. The 

Description panel displays. 

5 Type a description in the field.


6 To define a rule for the event trigger, click the Rule tab. The Rule panel displays. 

CAUTION If no rule is defined for a rule-based change trigger, the trigger runs every 

time any user performs an action on any item in MKS Integrity. 

a) If certain conditions are met, nodes specify if the trigger runs. Select a node option by 

clicking a button: 

And specifies that all of the conditions specified must be true for the trigger to 

run. For example, if an item’s assigned group = documentation and the 

project = editor, then the event trigger runs. 

Or specifies that one or more of the conditions must be true for the trigger to 

run. For example, if an item’s state = submitted or the priority is not equal 

to high, then the event trigger runs. 

Swap replaces the selected node with the opposite node. For example, 

swapping an Or node replaces it with an And node. 


NOTE You do not need to use And and Or nodes if your rule contains only one 

condition. 

b) Under Condition, define the conditions this trigger should run under. For more 

information, see “Defining Rules” on page 43. 

For example, in a workflow with the states Development > Testing > Release, 

you can create a rule-based trigger to perform an action whenever an item is 

changed to the Testing state (State=Testing). Another example is to perform an 

action every time the assigned user of an item is changed to the specified user, such 

as in the following example: 

Assigned UserAssigned User 

Assigned User=mchang 

Using the same workflow of Development > Testing > Release, you could 

create a rule-based trigger to perform an action for all items existing in the Testing 

state (State=Testing). Another example is to perform an action for all items that 

are currently assigned to the specified user (such as, Assigned User=mchang). 

For specific use cases pertaining to the creation of pre-condition rules for triggers 

that operate on items under document model, see ALM Knowledge Base. 

c) To add the condition to the rule, click Add. To replace an existing rule with a new 

rule, select the rule in the rules list, then click Replace. 

d) To copy a rule from another trigger, under Copy do one of the following: 

365


366 

Click Add to copy notification conditions. The copied conditions are appended 

to any existing rules. 

Click Replace to copy notification conditions and replace any existing rules. 

The Rule Selection dialog box displays. 

e) In the Objects with Rules list, select the trigger you want to copy a rule from. If the 

trigger has a rule, that trigger displays in the Preview area. 

Click OK. The rule displays in the Rule panel. 

Repeat as necessary to copy other rules. 

7 To select scripts for the new trigger, click the Trigger tab. The Trigger panel displays. 

a) To specify the script file or files the event trigger runs when scheduled, do one of the 

following: 

In the Script File field, enter the name of the JavaScript file. For more than one 

file, place a comma between file names. 

Click Browse, select a script file from the list in the viewer, and click OK. 

Selected scripts display in the Trigger panel. 

TIP Press CTRL to multi-select scripts or clear a selection. Multi-selected scripts 

appear in the Script field on the Triggers panel delimited by commas. 

For information on pre-created JavaScript files see the “Workflow and 

document event triggers use pre-created scripts from a server-side library. You 

can modify existing scripts or add new ones to build the library over time.” on 

page 358. 

b) If the trigger is a pre- or post-event, or both, enable the option or options 

accordingly. 

c) Enter trigger parameters, if any, in the relevant Parameters fields. Point to the field 

name to view a tooltip containing more information about the parameter. For 

information on the JavaScript files provided with MKS Integrity, see “Workflow 

and document event triggers use pre-created scripts from a server-side library. You 

can modify existing scripts or add new ones to build the library over time.” on 

page 358. 

NOTE Backlashes (\) in parameters are truncated after you save and run the trigger, 

for example, in a directory path. To avoid this, use forward slashes (/).


8 To assign values to specific fields when the event trigger is run, click the Assignment tab. 

Depending on the scripts they run, some triggers may not require assignments (for 

example, if the assignments are coded in the scripts). The Assignment panel displays. 

You can create a list of assignments that occur when the rule matches by specifying a 

field and the value the trigger enters in that field when it runs. Standard fields, which are 

not writable (such as ID, Type, Created Date, Created By, Modified Date, and Modified By) 

and item backed picklist fields with rule-based relationships are not available for 

assignments. 

NOTE A field can only have one assignment. The last assignment you add to the 

Assignment panel is the one that the MKS Integrity Server uses. Configuration 

management project fields cannot be assigned. 

When you select the Assigned User or Assigned Group fields, you can click the 

Select button to choose from a full list of users or groups, including inactive ones. 

a) From the Field list, select the field name. 

b) From the Value list, select a value for the selected field. For detailed information on 

choosing values for user or project fields, see “Filtering Data” on page 18. 

c) To add the assignment to the list, click Add. 

Repeat steps a) and b) for additional assignments. To replace an assignment with a 

new one, in the list select the assignment to be replaced, and click Replace. 

d) To remove an assignment, select the assignment in the list, and click Delete. 

NOTE Assignments made on the Assignments panel occur after any assignments 

made by code in the script file are performed. 

9 To set the trigger, click OK. 

Creating Scheduled Triggers 

Scheduled triggers run on a specified schedule against all items matching the specified query. 

Any modifications appear as if the user selected in the Run As list made them. 

The general steps required to create a scheduled event trigger are as follows: 

1 Select the schedule trigger type, and assign a user to be recorded as performing the script 

the trigger runs. 


3 Specify the schedule the trigger runs on. 

367


368 

4 Select an existing query to specify which items the query runs on. 

NOTE Because scheduled triggers are based on queries, triggers are subject to 

visibility rules. Visibility rules restrict access to specific information based on project 

or item type. For more information, see “Setting Workflow and Document Project 

Visibility” on page 250 and “Setting Field Visibility for Types” on page 120. 

5 Select a script file from the library for the trigger to run, and fill out the parameters for it. 

NOTE 




Backlashes (\) in parameters are truncated after you save and run the trigger, for 

example, in a directory path. To avoid this, use forward slashes (/). 

6 Assign the values to the fields the trigger modifies when it is run (if the trigger is one 

that modifies field values in the database). 


All triggers run sequentially. This prevents an increase in the use of server resources 

each time a new trigger is added. 

Scheduled event triggers are evaluated on the MKS Integrity Server’s time zone. 

Schedules are recomputed after any given run, at system startup, and when the triggers 

are changed. If a set of triggers takes longer to run than the next scheduled trigger is set 

to run at, the next schedule run of the trigger is missed. 

All modified items from a single scheduled trigger are part of one single transaction. If 

the trigger fails, no items are modified. Unlike rule-based triggers, since each trigger 

operates independently of its own batch of items, each trigger commits the change to the 

database independently. 

When the server is shut down or the service is stopped, the server does not reschedule 

triggers that were not able to run to during that time. 

To create a scheduled event trigger in the GUI 




3 Enable Schedule.


4 From the Run As list, select the user MKS Integrity records as performing the action. For 

detailed information on selecting users, see “Filtering Data” on page 18. 

NOTE You must specify a user in the Run As list or you cannot save the trigger. 



6 Type a description in the field. 

7 To define the schedule the trigger runs on, click the Schedule tab. The Schedule panel 

displays. 

8 Under Frequency, select the frequency the trigger runs on: 

Manual disables scheduling of the trigger and can be used with the CLI scheduling. 

Use this option to disable a scheduled trigger instead of deleting it. 

Hourly runs trigger at a specified point within an hour. In the Start Time field, type 

the number of minutes past the hour you want the trigger to run. From the Hourly 

On list, select the hour(s) you want the trigger to run. The Hourly On list represents 

time in the 24 hour format. 

Daily runs the trigger at specified time on selected day(s). Enter a time in the 24 hour 

format in the Start Time field. From the Daily On list, select which day(s) you want 

the trigger to run on. 

Monthly runs the trigger at a specified time and day on selected month(s). Enter a 

time in the 24 hour format in the Start Time field. From the Monthly On list, select 

which month(s) you want the trigger to run on. From the Day Of Month list, select 

the day you want the trigger to run on. 

The Last Run Time field displays the date and time the trigger last successfully ran. 

9 To specify the items the trigger runs on, click the Query tab. The Query panel displays. 

10 Select a query from the list. You cannot save a trigger without selecting a query. 

NOTE If you select a query that contains the Me symbolic filter on a user field, the 

filter fails and does not match any items. 

11 To select scripts for the new event trigger, click the Trigger tab. The Trigger panel 

displays. 

12 To assign values to specific fields when the event trigger is run, click the Assignment tab. 

Depending on the scripts they run, some triggers may not require assignments (for 

example, if the assignments are coded in the scripts). The Assignment panel displays. 

13 Click OK to finish and save the event trigger. 

369


370 

Creating Other Triggers 

In addition to schedule- and rule-based triggers, you can create triggers that run when one of 

the following actions occur: 

time entry is changed 

item tree is copied 

item is branched 

item is labeled 

test result is created, modified or deleted 

TIP The triggers for item actions are currently used in the MKS Requirements 

solution, and are useful for document management. The trigger for test results is 

useful for test management. 

The general steps required to create another trigger are as follows: 

1 Select the other trigger type. 


3 Select a script file from the library for the trigger to run, and fill out the parameters for it. 

NOTE 




Backlashes (\) in parameters are truncated after you save and run the trigger, for 

example, in a directory path. To avoid this, use forward slashes (/). 


The Rule, Schedule, Query, and Assignment tabs are not meaningful to other triggers, 

and are therefore disabled in the Create Trigger dialog box. 

For non-batch processing of time entry triggers, a single time entry PRE event is fired 

before each operation, then the operation is performed and committed to the database, 

and finally the POST event is fired. In this way, the method used for non-batch 

processing of time entries triggers is consistent with the method used for batch 

processing. 

All operations are available to you in the POST event. For example, if you submit 200 

time entry edits, there will be 200 PRE triggers, then the 200 operations will process, and 

finally there will be a single POST trigger that references all 200 operations.


The test results trigger will fire before and after each batch of test result creates, edits, 

and deletes. If the test result is modified by the tm setresults command, any creates 

(if they exist) will fire a trigger, and any edits (if they exist) will fire another trigger. 

To create an other trigger 




3 Enable Other. 

4 From the Run triggers whenever list, select an option. 



6 Type a description in the field. 

7 To select scripts for the new trigger, click the Trigger tab. The Trigger panel displays. 

8 Click OK to finish and save the event trigger. 

Copying Event Triggers 

You can copy an event trigger to create a new event trigger. Copying an event trigger is 

useful for quickly creating a new event trigger that shares common details with an existing 

event trigger. 

When naming a copied event trigger, you cannot use a name that already exists. 

To copy an event trigger in the GUI 

1 In the Triggers view (see “Managing Event Triggers” on page 362), select Trigger > Copy. 

The Copy Trigger dialog box displays the Type panel (if you are copying a non scheduled 

trigger) or the Schedule panel (if you are copying a scheduled trigger). 

2 In the Name field, type a new name for the event trigger. 

3 Edit the trigger as required. For more information see the following: 

“Creating Rule Based Change Triggers” on page 363 

“Creating Scheduled Triggers” on page 367 

“Creating Other Triggers” on page 370 


Running Scheduled Triggers 

Once you have created a scheduled trigger, you can run it. You can only run scheduled 

triggers manually by this method. 

371


372 

To run a scheduled trigger in the GUI 

1 From the Triggers view, select the event trigger(s) you want to run. For more 

information on the Triggers view, see “Managing Event Triggers” on page 362. 

2 Select Trigger > Run, the scheduled trigger runs. 

Viewing Event Triggers 

You can view the details of an event trigger without making the trigger editable. The details 

of the event trigger can be viewed through the Triggers view. When in view mode, you 

cannot change any of the information for the selected trigger. 

NOTE If the trigger you are viewing is based on a query that is invisible to you, the 

query does appear in the Query list. However, this query is not available when you 

are creating a trigger. 

To view an event trigger in the GUI 

1 From the Triggers view, select the event trigger you want to view. For more information 

on the Triggers view, see “Managing Event Triggers” on page 362. 

2 Select Trigger > View Definition. The View Trigger dialog box displays. 

3 Click a tab to view its contents. 

4 To finish, click Close. 

Editing Event Triggers 

You can edit the details of a workflow and document event trigger through the Triggers 

view. 

NOTE 

If the trigger you are editing is based on a query that is a non-favorite, the query 

appears in the Query list. However, this query is not available when you are 

creating a trigger. 

Inactive values are not accepted in trigger assignments. If you specify inactive 

values for a trigger assignment containing existing user, group, or project field 

values, the existing values are cleared. For multi-valued user and group fields, 

the entire trigger assignment definition is cleared even if you specified one 

inactive value. 

To edit an event trigger in the GUI 

1 From the Triggers view, select the event trigger you want to edit. For more information 

on the Triggers view, see “Managing Event Triggers” on page 362. 

2 Select Trigger > Edit. The Edit Trigger dialog box displays.


3 Select a tab to edit its contents. For more information, see “Creating Rule Based Change 

Triggers” on page 363 and see “Creating Scheduled Triggers” on page 367. 

4 To determine all objects that reference the field, click the References tab. For information 



5 To finish and save the changes, click OK. 

Deleting Event Triggers 

When a workflow and document event trigger is no longer needed, you can delete it in the 

Triggers view. 

IMPORTANT If you delete a relationship field used in a rule-based trigger, the field 

associated with the relationship field and rule trigger are automatically deleted. 

To delete an event trigger in the GUI 

1 From the Triggers view, select the event trigger you want to delete. For more 

information on the Triggers view, see “Managing Event Triggers” on page 362. 

2 Select Trigger > Delete. The Confirm Trigger Deletion dialog box displays. 

CAUTION You cannot undo deletion of an event trigger. 

3 To delete the event trigger, click Yes. 

Resolving Event Triggers 

You can change the order of event trigger resolution, that is, which event triggers run first, by 

changing the order they appear in the list. 

NOTE All pre-event triggers must complete first before any post-event triggers can 

run. 

To change the resolution order of event triggers in the GUI 

1 From the Triggers view, select Trigger > Reposition. The Reposition Triggers dialog box 

displays. 


To run the event trigger before other triggers, click Move Up the necessary number of 

times. 

To run the event trigger after other triggers, click Move Down the necessary number 

of times. 

373


Overview of Configuration Management Triggers 

374 

A configuration management event trigger is an association between a pre-defined 

configuration management event and the script that is to be executed when that event occurs. 

Configuration management triggers run on the following: 

MKS Integrity Server (server-side) 

For more information on server-side triggers, see “Overview of Configuration 

Management Server-Side Triggers” on page 374. 

MKS Integrity Client (client-side) 

For more information on client-side triggers, “Overview of Configuration Management 

Client-Side Triggers” on page 383. 

Overview of Configuration Management Server-Side Triggers 

Configuration management server-side triggers execute in response to an action on the 

MKS Integrity Client, and reside on the MKS Integrity Server where they are executed. 

Server-side triggers are administered through the file system of the MKS Integrity Server and 

are enabled by default through Configuration Management > Configuration > Properties in the 


Some uses for configuration management server-side triggers include: 

Send an e-mail to the change package creator, reviewer, or watcher if change package 

review is enabled 

Apply a label to a revision with the name of the user who checked in the revision 

Prevent users from adding members of a certain file type 

Ensure change package entries occur on the same development path for a change 

package 

Send an e-mail to the configuration management administrator when configuration 

management projects or subprojects are added or dropped 

Configuration Management Event Categories 

An event is a defined point in configuration management operation. The four categories of 

events connected with configuration management operations are: 

member 

configuration management project 

revision

Member Events 

server 


By default, the global.events definition file is contained in the following directory: 

installdir/data/triggers/events 


NOTE If the events directory contains more than one global.events definition 

file, all files are loaded. If the files contain identical events, the values in the last read 

file are used. 

You can change the directory by editing the following property under Configuration 

Management > Configuration > Properties in the MKS Integrity Administration 

Client: 

mksis.si.triggers.events 

For more information on the events definition file, see “To update the global events definition 

template” on page 383. 

The syntax for an event is: 

.. 

for example: 

Member.freeze.pre 

Project.importSubproject.post 

The following tables list the events in each category: 

freeze.pre freeze.post 

thaw.pre thaw.post 

setAttribute.pre setAttribute.post 

dropAttribute.pre dropAttribute.post 

lockRevision.pre lockRevision.post 

unlockRevision.pre unlockRevision.post 

checkIn.pre checkIn.post 

checkOut.pre checkOut.post 

setMemberRevision.pre setMemberRevision.post 

rename.pre rename.post 

setrule.pre setrule.post 

clearrule.pre clearrule.post 

375


Project Events 

376 

checkpoint.pre checkpoint.post 

restore.pre restore.post 

addMember.pre addMember.post 

dropMember.pre dropMember.post 

moveMember.pre moveMember.post 

newSubproject.pre newSubproject.post 

importSubproject.pre importSubproject.post 

configureSubproject.pre configureSubproject.post 

dropSubproject.pre dropSubproject.post 

moveSubproject.pre moveSubproject.post 

newVariant.pre newVariant.post 

deleteVariant.pre deleteVariant.post 

setDescription.pre setDescription.post 

dropProjectAttribute.pre dropProjectAttribute.post 

setProjectAttribute.pre setProjectAttribute.post 

Revision Events 

promoteTo.pre promoteTo.post 

demoteTo.pre demoteTo.post 

addLabel.pre addLabel.post 

deleteLabel.pre deleteLabel.post 

appendToDescription.pre appendToDescription.post 

Server Events 

newProject.pre newProject.post 

importProject.pre importProject.post 

dropProject.pre dropProject.post 

submitChangePackage.pre submitChangePackage.post 

acceptChangePackage.pre acceptChangePackage.post 

rejectChangePackage.pre rejectChangePackage.post 

closeChangePackage.pre closeChangePackage.post

Server Events 


commitChangePackage.pre commitChangePackage.fail 

commitChangePackage.post 

discardChangePackage.pre discardChangePackage.post 

discardChangePackageEntry.pre discardChangePackageEntry.post 

moveChangePackageEntry.pre moveChangePackageEntry.post 

Server.archivemetric.manual 

Server.projectmetric.manual 

Server.setarchivemetric.manual 

Server.setprojectmetric.manual 

Deploy Events 

These events are only applicable if you are licensed to use Deploy. For more information, see the MKS Deploy 2009 

Administration Guide. 

Project.promoteChangePackage.pre Project.promoteChangePackage.fail 

Project.promoteChangePackage.post 

Project.deployChangePackage.pre Project.deployChangePackage.fail 

Project.deployChangePackage.post 

Project.undeployChangePackage.pre Project.undeployChangePackage.fail 

Project.undeployChangePackage.post 

Project.cancelDeployRequest.pre Project.cancelDeployRequest.post 

Project.deleteDeployRequest.pre Project.deleteDeployRequest.post 

Project.editDeployRequest.pre Project.editDeployRequest.post 

Project.startDeployRequest.pre Project.startDeployRequest.post 

Project.stopDeployRequest.pre Project.stopDeployRequest.post 

Project.initDeployTarget.pre Project.initDeployTarget.post 

Project.syncDeployTarget.pre Project.syncDeployTarget.post 

Project.restoreStage.pre Project.restoreStage.post 

Project.deployRequestStateChange.post 

Project.deployTargetConnectionStatusChange.post 

377


378 

Configuration Management Commands 

The following tables list the available configuration management commands and their 

associated event identifiers under the four categories of events: 

Member Command Member Event Identifier 

si freeze Member.freeze 

si thaw Member.thaw 

si addmemberattr Member.setAttribute 

si dropmemberattr Member.dropAttribute 

si lock Member.lockRevision 

si unlock Member.unlockRevision 

si ci Member.checkIn 

si co Member.checkOut 

si updaterevision Member.setMemberRevision 

si rename Member.rename 

si setmemberrule Member.setrule 

Member.clearrule 

Project Command Project Event Identifier 

si checkpoint Project.checkpoint 

si restore Project.restore 

si add Project.addMember 

si drop Project.dropMember 

si move Project.moveMember 

si createsubproject Project.newSubproject 

si createsubproject Project.importSubproject 

si movesubproject Project.moveSubproject 

si drop Project.dropSubproject 

si createdevpath Project.newVariant 

si dropdevpath Project.deleteVariant 

si setprojectdescription Project.setDescription 

si dropprojectattr Project.dropProjectAttribute

Project Command Project Event Identifier 


si setprojectattr Project.setProjectAttribute 

si applycp various identifiers, depending on the required operations 

Revision Command Revision Event Identifier 

si promote --state= Revision.promoteTo 

si promote (no state specified) Revision.promoteFrom 

si demote --state= Revision.demoteTo 

si demote (no state specified) Revision.demoteFrom 

si addlabel Revision.addLabel 

si deletelabel Revision.deleteLabel 

si appendrevdesc Revision.appendToDescription 

Server Command Server Event Identifier 

si createproject Server.newProject 

si importproject Server.importProject 

si droppproject Server.dropProject 

si submitcp Server.submitChangePackage 

si acceptcp Server.acceptChangePackage 

si rejectcp Server.rejectChangePackage 

si closecp Server.closeChangePackage 

si discardcp Server.discardChangePackage 

Discard Change Package Entry Server.discardChangePackageEntry 

Move Change Package Entry Server.moveChangePackageEntry 

Transactionality of Configuration Management Event Triggers 

The operation of server-side triggers occurs in the following sequence: 

1 MKS Integrity Client initiates a command that will run on the MKS Integrity Server. 

2 Before event begins, pre-event is posted. 

3 Event occurs. 

4 MKS Integrity Server polls its registry of events to determine if the event has an 

associated script. 

379


380 

5 If script is found, the MKS Integrity Server executes the resolved script. 

6 Command executes. 

7 If command succeeds, post-event is posted. 

An event trigger is executed either prior to an event or after the event. Pre-test event triggers 

are executed before the command is executed and are most useful for preventing transactions 

if particular conditions are not met. For example, a pre-test trigger could prevent state 

changes if no label has been added to the member. 

Post-test event triggers are executed after an event is successfully committed and are most 

useful for combining actions. For example, after the successful check in of a revision, a posttest 

event trigger could apply the label with the name of the user who checked in the revision. 

Event Trigger Contexts 

Configuration management has two contexts for event triggers: global and project. 

All server-side triggers are configured on the MKS Integrity Server. Each context contains 

JavaScript elements that define the event triggers. Each type of event trigger can be created 

and maintained independent of the other. This means you can define different event triggers 

for the same events in different projects, or you can define event triggers that apply globally 

within your environment. 

Global Context 

NOTE When working with shared subprojects, MKS Integrity uses the actual name 

of the subproject in the file system rather than its relative name in the configuration 

management project hierarchy. This enhances the portability of change packages 

across different configuration management projects. Therefore, when returning 

query information resulting from a script, MKS Integrity uses the actual file system 

name of the shared subproject. 

Global event triggers are available and active for all configuration management operations. 

As administrator, you use the global context for any JavaScript elements used to define 

additional procedures for all configuration management users. 

Project Context 

Configuration management project event triggers are established within a project events file. 

The project context is generally used for project-specific configuration processes. Event 

triggers in this context generally add to, but do not override, event triggers defined in the 

global context. The project context is active when either the project or a Sandbox based on the 

project is active. 

NOTE Configuration management events not available in the project context are: 

New Project, Import Project, and Drop Project.

Subproject Event Triggers 


You can also set up event triggers to run within the context of a configuration management 

subproject. This allows you to run an event trigger only on a selected subproject, without 

requiring that the trigger also be defined for the master project. 

To configure event triggers to run on a subproject 

1 From the installdir/data/triggers directory, copy the project_template.events 

file to: 



2 In the events folder, rename the project_template.events file to represent the 

target subproject, for example, Aurora_Frame_Sub.events. 

3 In that file, set the path of the subproject in variable event.projectPath, for example, 

event.projectPath=c:/Aurora/Frame/project.pj. 

4 Define the script to run on a specific event. For example, 

Project.checkpoint.pre=samples/echo.js 

sets echo.js to run on a project checkpoint pre-event. 

5 Save the revised .events file. The subproject trigger runs for the identified subproject. 

Trigger Resolution 

MKS Integrity resolves configuration management event triggers according to the resolution 

order configured through Configuration Management > Configuration > 

Properties in the MKS Integrity Administration Client. For example, if the order is 

global,projects, the global events file is searched for scripts, followed by the projects 

event file. When MKS Integrity finds a script with a matching name, it runs the script. 

NOTE You can also leave out one or both of the global/project contexts. Leaving out 

one context means that the related events are never executed. Leaving out both 

contexts effectively disables event triggers. 

MKS Integrity is pre-configured to first resolve global event triggers followed by project 

event triggers. The property is: 

mksis.si.triggers.resolutionOrder=global;project 

The default setting can be reconfigured to suit your environment. 

381


382 

Components of Event Triggers 

Creating a configuration management event trigger requires three primary components: 

Properties (mksis.si.triggers) in the MKS Integrity Administration Client: 

Configuration Management > Configuration > Properties 

to configure MKS Integrity so that event triggers may take place. The properties define 

the directories for both the events definition files and event trigger scripts. 

Events definition files listing all events defined in MKS Integrity and mapping events to 

trigger scripts. The default directory for the events definition file is: 


Event trigger scripts developed in JavaScript and, by default, located in: 


Updating Events Definition File 

Events definition files are used to specify which scripts to run for a particular event or events. 

The events definition file essentially attaches the script to the event. The file follows the 

format of a Java properties file and includes configuration keys to indicate the context of the 

events, as well as a key for each event addressed by the specified context: 

In the global context, the required configuration key is: 

event.context=global 

where the event context is defined as global. 

In the configuration management project context, the required configuration keys are: 

event.context=project 

event.projectPath=/project.pj 

where the event context is project and the path to the specific project is also defined. 

Use forward slashes (/)when specifying a project path. 

For both global and project contexts, the event key is a comma-delimited list of scripts 

for each event addressed by the specified context. The syntax is: 

context.operation.pre/post=event.js,event.js 

where 

context is archive, member, project, revision, or server 

operation is the actual configuration management operation, for example, checkIn, 

checkOut, setAttribute, or checkpoint (for a complete list of configuration 

management events, see “The syntax for an event is:” on page 375)


pre/post indicates whether the script is run before or after the event 

An example of a completed event key is: 

Member.thaw.pre=projectEvent.js,ethawTest.js 

NOTE You cannot use configuration management events New Project, 

Import Project, and Drop Project in the project context. 

To update the global events definition template 

1 Open the default directory for the global events definition template: 

installdir/data/triggers/global_template.events 

2 Copy the global template file to: 


3 Add the script names for the event triggers you want to run. 

To update the project events definition template 

1 For each project requiring event triggers, make a copy of the project template in: 


2 Set .projectPath to the fully qualified path of the target project. 

3 Add the script names for the event triggers you want to run. 

Restarting MKS Integrity Server 

Once you have created the event triggers and updated the events definition file, you can 

restart the MKS Integrity Server to have the triggers take effect immediately. 

For more information on running the MKS Integrity Server, see the MKS Integrity Server 2009 


Overview of Configuration Management Client-Side Triggers 

As an administrator, you can configure event triggers that run on the MKS Integrity Client 

rather than on the MKS Integrity Server. Client-side triggers are run only for members and 

for project level commands that operate on members. Client-side triggers do not run on 

383


384 

commands that operate on directories, configuration management projects, Sandboxes, or 

change packages. 

IMPORTANT Client-side triggers run on the MKS Integrity Client and in the client’s 

environment; therefore, they are subject to the client’s control. For example, a user 

could adjust the PATH environment variable on the client such that when an 

external command runs it is not found. For consistent and secure results, MKS 

recommends you use server-side triggers. 

Some of the uses for client-side triggers include: 

Display Sandbox information before adding a label 

Post a reminder to add a revision description when checking in a member 

Launch a text editor when a member is checked out 

Post a reminder to notify team members of significant changes are checked in 

Confirm that each .JAVA file has a corresponding .CLASS file in a user’s Sandbox 

Client-side triggers run only on member commands, therefore only project commands 

that operate on members can be used 

Pre and Post Processing in Client Sandbox 

Client-side event triggers allow for pre- and post-processing in the client Sandbox. This 

allows clients to run external commands within the client, both before and after each member 

of a selection is processed for a given command. 

NOTE If a pre-trigger has a non-zero exit status, the operation is canceled. 

Trigger Syntax 

To configure a client-side event trigger, properties are added to the Configuration 

Management policies in the MKS Integrity Administration Client using the following syntax: 

si..pre= 

si..post= 

si.trigger..command= 

si.trigger..group= 

si.trigger..match= 

NOTE List elements can be delimited by spaces, commas, or semicolons.


The following is an example of the required properties for a pre- and post-trigger that works 

when a branch is merged: 

si.MergeBranch.pre=merge_pre 

si.trigger.merge_pre.command=sh -w -c 'echo After merging the branch, 

please update the MergedBranches.txt file with the date and reason 

for the merge.' 

si.MergeBranch.post=merge_post 

si.trigger.merge_post.command=sh -w -c 'vi c:/MergedBranches.txt' 

You can create triggers that apply only for members of a specific group. If the user running 

the command is not a member of one of the specified groups, the trigger cannot execute when 

the user runs the command. The specified group must be a valid group on your server 

system using the server realm. To specify groups, append the following property to the 

trigger properties: 

si.trigger..group= 

for example: 

si.trigger.merge_post.group=BuildTeam 

You can also create triggers for certain classes of files using matching. A list of one or more 

file name matching patterns can be set. If the member under consideration matches the 

pattern, the trigger runs. To specify glob patterns, append the following property to the 

trigger properties: 

si.trigger..match= 

for example: 

si.trigger.merge_post.match=*.c,*.java 

Target Commands 

Client-side triggers run only on commands that operate at the member level. The first table 

lists configuration management project commands that operate on members, including 

commands launched from the Configuration Management Web client. The second table lists 

the applicable member commands. 

NOTE The si echo command is available for echoing strings to the GUI. 

Configuration Management Project Commands for Members 

Project Command Command Expression 

si add AddMembers 

si dropproject DropProjectTypeElement 

si edit EditCurrentOrFormerProjectTypeElements 

si import ImportMembers 

385


386 

Configuration Management Project Commands for Members 

Project Command Command Expression 

si mergebranch MergeBranch 

si add ProjectAddMembers 

si ci ProjectCheckInMembers 

si co ProjectCheckOutMembers 

si promote PromoteMembers 

si resync ResyncCurrentOrFormerProjectTypeElements 

si revert RevertCurrentOrFormerProjectTypeElements 

si submit SubmitCurrentOrFormerProjectTypeElements 

Member Commands 

Member Command Command Expression 

si addlabel AddLabel 

si addmemberattr AddMemberAttribute 

si archiveinfo ArchiveInformationView 

si print ArchivePrintView 

si report ArchiveReportView 

si appendrevdesc AppendRevisionDescription 

si ci CheckInMembers 

si co CheckOutMembers 

si deletelabel DeleteLabel 

si deleterevision DeleteRevisionsOfMembers 

si demote DemoteMembers 

si diff DiffMembers 

si dropmemberattr DropMemberAttribute 

si freeze FreezeMember 

si viewlabels LabelsView 

si lock LockRevisionOfMember 

si makewritable MakeWritable 

si memberinfo MemberInformationView 

si viewhistory MemberView

To add client-side trigger information to the si.policy file 


1 From the MKS Integrity Administration Client, open the Configuration Management 

directory tree, and highlight Policies. The Global Policies section displays in the right 

pane. 

2 Select Policies > Edit. The Global Policies editor displays. 

3 Click the Other tab and enter the client-side trigger information in the text box. For 

example, the following shows the information entered to post a notification reminder for 

the development group. 

4 To save the changes, click OK. The client-side trigger is set on the server. 

Environment Variables 

Member Commands 

Member Command Command Expression 

si rename RenameMember 

si viewrevision RevisionContentsView 

si revisioninfo RevisionInformationView 

si thaw ThawMember 

si unlock UnlockRevisionOfMember 

si updaterevision UpdateRevisionOfMembers 

si updatearchive UpdateArchiveAttributesOfMembers 

When configuring client-side triggers, you can also use certain environment variables to 

define the object the trigger is operating on. The environment variables used for client-side 

triggers are similar to those used for user toolbar commands. 

387


388 

For client-side triggers, you can use the following environment variables to determine the 

object the trigger is operating on. 

Environment Variable Function 

MKSSI_COMMAND=si. MKSSI_COMMAND always set to command running. For 

example, for add member command environment 

variable is: 

MKSSI_COMMAND=si.AddMember 

MKSSI_WINDOW=trigger MKSSI_WINDOW=trigger always set to indicate 

operation runs from trigger. 

MKSSI_TRIGGER_TYPE=pre|post MKSSI_TRIGGER_TYPE= set to one or 

other keyword to indicate whether trigger running due to 

a pre- or post-event. For example: 

MKSSI_TRIGGER_TYPE=post 

indicates trigger running due to post event. 

MKSSI_UI=cli|gui|web MKSSI_UI set to one of keywords to indicate type of 

user interface. For example: 

MKSSI_UI=gui 

indicates GUI used. 

MKSSI_FILE=filepath-relative-to-project/ 

sandbox-of-a-member 

MKSSI_WORKINGFILE=full-path-to-workingfile-for-a-member 

MKSSI_FILE set to file path of member relative to 

configuration management project or Sandbox for 

member, for example: 

MKSSI_FILE=baseframe.c 

MKSSI_WORKINGFILE set to full path of working file for 

member whenever operation occurs in Sandbox and 

working file exists, for example: 

MKSSI_WORKINGFILE=c:\auroraSB\sh\ 

baseframe.c 

MKSSI_SANDBOX=full-path-to-sandbox MKSSI_SANDBOX set to full path of Sandbox whenever 

operation occurs in Sandbox. Sample output for 

operation running in Sandbox: 

MKSSI_SANDBOX=c:\auroraSB\sh\project.pj 

MKSSI_PROJECT=server-path-to-project MKSSI_PROJECT set to server path to configuration 

management project. Sample output for server path to 

project: 

MKSSI_PROJECT=c:/aurora/sh/project.pj 

MKSSI_VARIANT=project-variant-name MKSSI_VARIANT indicates operation runs for specific 

configuration management project variant. Sample 

output for operation running for Aurora_Variant project: 

MKSSI_VARIANT=Aurora_Variant 

MKSSI_BUILD=project-build-revision- 

number 

MKSSI_BUILD indicates operation runs for specific 

build revision number. Sample output for operation 

running for build revision number 1.5.1.1: 

MKSSI_BUILD=1.5.1.1

Environment Variable Function 

Sample Configuration Using Environment Variables 


MKSSI_PROJECT_TYPE=sandbox|project MKSSI_PROJECT_TYPE sets one or other keyword to 

indicate whether operation runs in Sandbox or 

configuration management project. Sample output for 

operation running in Sandbox: 

MKSSI_PROJECT_TYPE=sandbox 

MKSSI_PRESENTER=interface-presenter MKSSI_PRESENTER set to open presenter for 

command running, whether through the GUI or CLI. 

Value for MKSSI_PRESENTER only relevant to 

--presenter name option. 

The following example shows how you can use an environment variable with a client-side 

trigger. The example shows a trigger implemented on the Add Member command (si add). 

Each time a member is added to a configuration management project, the trigger opens the 

member working file in a vi text editor: 

si.AddMembers.post=AMpost 

si.trigger.AMpost.command=sh -c "vi $MKSSI_WORKINGFILE" 

Planning Configuration Management Triggers 

To avoid unpredictable event trigger behavior, plan your event triggers in the following way: 

1 First choose the scope of the event trigger 

a) Event triggers that you want to apply to all operations should be set in the global 

context. 

b) Event triggers that are related only to a specific configuration management project 

should be set in the project context. 

2 Decide whether your event triggers should occur as a pre-event or post-event. 

a) Pre-event triggers can return a code that indicates the operation should not proceed 

and are therefore most applicable for events that you want to prevent. 

b) Post-event triggers are more useful for logging information on a successful 

operation or for performing linked operations. The post-event trigger executes 

regardless of whether the event was successful, but the administrator has access to 

any logged information. 

NOTE Scripts provide significant flexibility in creating event triggers. You can use 

one script for more than one event. For the same event you can also point to a script 

in the global context and another script in the configuration management project 

context. 

389


390 

3 Consider the following: 

Be aware of system security. JavaScript event triggers are expressive and run on the 

server under the permissions of the administrator. Event triggers therefore have the 

potential to affect file and system security. 

Limit event triggers to only those things you believe to be beneficial to your 

environment. Event triggers affect the duration of the command from the client’s 

perspective and therefore have the potential to degrade performance. 

NOTE The MKS Integrity Server can process commands in parallel—a feature that 

allows users to initiate a second command even if the first has not completed. 

Instead of having a script for each configuration management event, you could have 

a script for a group of configuration management events. Then in that script, 

execute different code depending on which event has fired (the event that fired the 

trigger can be retrieved from a Bean). 

Script Library for Configuration Management Triggers 

MKS Integrity provides some pre-created configuration management triggers scripts that can 

be used “out-of-the-box”. 

Sample event triggers are provided in: 

installdir/data/triggers/scripts/samples 


The list of pre-created scripts provided may vary depending on the server implementation of 

an organization. Some of the pre-created scripts available include: 

breakLockNotification.js – send an e-mail to a user if their lock has been removed 

or downgraded by another user. 

enforceRevisionDescription.js – enforce revision descriptions. 

metrics.js – calculate metrics for a configuration management project. 

Referencing Configuration Management Beans in Trigger Scripts 

First, you need to reference the applicable Beans you want to use in your script. Refer to the 

Event Trigger Java Documentation off the server homepage. Beans prefaced with si are 

configuration management Beans. 

TIP You can get the name of a Bean by looking at the GetExposedName() method 

in the Event Trigger Java Documentation.


Once you know the Bean name, look up the Bean in the trigger script, for example: 

var envBean = bsf.lookupBean(“siEnvironmentBean”); 

Useful configuration management Beans include: 


Contains information about the environment in which the script is running. 

ScriptServerBean 

Contains information about the configuration management server. 

ScriptCheckInArgumentsBean 

Contains information about the member being checked in. 

ScriptMemberBean 

Contains information about a member. 

Coding Configuration Management Triggers 

Once you have referenced the necessary Beans, you can begin coding the rest of the trigger 

according to your needs. 

For example, to create a server-side script that checks for a member revision description type 

the following: 

Next, do the following: 

1 Save the trigger script to the trigger library: 


2 Update events definition file. 

3 Restart MKS Integrity Server. 

391


392 

4 MKS Integrity runs the configuration management event trigger at the next applicable 

client action. 

NOTE You should restrict JavaScript triggers to a reasonable length. Although the 

MKS Integrity Server can process commands in parallel, a long running script can 

affect the duration of that specific command from the client’s perspective. 

For example, the following client-side script—CIpre—runs a KornShell script that prompts 

the user to add a revision description for the member they are checking in. 

To configure the trigger, the following information is added to the si.policy file on the 

MKS Integrity Server: 

si.CheckInMembers.pre=CIpre 

si.trigger.CIpre.command=sh -w -c 'echo Please provide a brief 

summary of changes you made in the Revision Description field.' 

Debugging Configuration Management Client- 

Side Environment Variables 

The simplest way to check whether an environment variable is set in the client event trigger’s 

runtime execution is to run the default shell’s environment display command. 

For example, on Windows: 

si.CheckOutMembers.post=COpost 

si.trigger.COpost.command=cmd /k set 

For example, on UNIX: 

si.CheckOutMembers.post=COpost 

si.trigger.COpost.command=sh –w –c env 

where 

cmd opens a command prompt. 

/k keeps the command prompt window open. 

set displays the machine environment variables. 

Error Handling Beans and Methods 

To retrieve error messages generated during server-side command calls, use the 

ScriptErrorMessageBean. The getMessage() method returns the error message, and the 

ScriptEnvironmentBean contains a stack of any errors that may have occurred during the 

execution of server-side commands.

Debugging Configuration Management Client-Side Environment Variables 

Useful error methods for using inside of a try...catch block include: 

emptyErrorMessageStack() - empties the error message stack. 

getErrorMessage() - the error message of the given index. 

numberOfErrorMessages() - the number of error messages in the error message stack. 

popErrorMessage() - pops an error message of the stack. 

pushErrorMessage() - pushes and error message on the stack. 

abortScript() Method 

DEBUG Logging 

To stop a trigger from executing when a script error occurs, the abortScript() method is 

available from the ScriptEnvironmentBean. 

This method is usually used in a pre-event trigger to display a message to the user to prevent 

them from doing something. In addition, it can be used to display error messages when 

debugging a trigger script, or to display trigger configuration errors. 

The abortScript() method takes two parameters: 

msg - The abort message. 

veto - If true, veto the operation. If false, do not. 

abortScript() example: 

Enabling DEBUG logging indicates if triggers are being executed, including other useful 

information. More specifically, DEBUG logging shows if your trigger is being considered, 

executed, and where in the trigger order it fires. 

Errors are logged to: 

installdir/log/server.log 

393


394 

To enable DEBUG logging: 

1 Edit the logger.properties file on the server located in the 

installdir/config/properties directory. 

2 Uncomment the following line: 

mksis.logger.message.includeCategory.DEBUG=10 

3 Save the logger.properties file and restart the MKS Integrity Server. 

Sample workflow and document management logging: 

Sample configuration management logging: 

Logging Trigger Scripts 

To assist in debugging trigger scripts, you can write from a trigger script to the server.log 

file. The output data from the trigger script may indicate where the problem is. 

To print to the log file, use the following syntax: 

Packages.mks.util.Logger.message("Category", level, "Text");

where 

Category - the logging category. 

Level - the logging level. 

Text - the text to be written out to the server log file. 

for example: 

Debugging Configuration Management Client-Side Environment Variables 

Packages.mks.util.Logger.message( "DEBUG", 5, "Debug message!" ); 

Decide if you want to use the default DEBUG logging category, a custom category for each 

trigger script, or a custom category for all trigger scripts. 

To print to the server log, MKS recommends using a JavaScript function, for example: 

function print(msg, level) { 

if (level == null) level = 5; 

Packages.mks.util.Logger.message("MYTRIGGER", level, msg); 

} 

If you use a custom category, you need to update the logger.properties file with the new 

category, for example: 

Logging Commands 

mksis.logger.message.includeCategory.MYTRIGGER=10 

You can use logging commands to dynamically enable and disable server.log logging. For 

example: 

where 

si/im logging --category="Category" –on/off --level="Level" -target="Target" 

Category - name of logging category (DEBUG, or custom). 

on/off - turn logging on or off. 

Level - logging level. 

Target - server or client logging. 

TIP Disable logging after you finish debugging or server performance may be 

affected. 

395


Using the MKS API in Event Triggers 

396 

The MKS Application Programming Interface (API) offers a direct way for custom 

applications to interact with workflow and document management, and configuration 

management. The MKS API can be used in triggers in a manner similar to the CLI; however, 

the API allows direct access to input and output without parsing. 

Using the MKS API in triggers is useful for performing CLI operations that are not covered 

by a Bean (like running a report), and running configuration management CLI commands 

from workflow and document events, and workflow and document commands from 

configuration management events. 

API Beans and Methods 

API Trigger Code 

NOTE The intent of this unit is not to get into how to use the MKS API, but to give 

examples of how it can be used in event triggers to get information Beans cannot. 

For more information on the MKS API, refer to the MKS Integrity 2009 Integrations 


The following Beans interact with the API: 


The createAPISessionBean() method obtains an API session Bean. 

ScriptAPICommandRunnerBean 

Manages and executes an MKS API command. The addOption() method adds an 

option flag to the command. 

ScriptAPISessionBean 

Accesses and controls an MKS API session. The executeCmd() method executes a 

command. 

The following API trigger code performs the equivalent functionality of the 

si createcp --issueID=101 command:

Running Custom Java Code 

You can also use server-side event triggers to run custom Java code from a script. 

Running Custom Java Code 

Your custom Java code can be put into the installdir/data/java/classes directory as 

individual class files or packaged as one or more JAR files in the data/java/jars directory. 

You can use both directories at the same time if you want some classes packaged up and 

some exposed individually 

Example 

// 

// MKS Integrity sample script. 

// 

// This script runs a custom java code in com.abc.custom. 

// 

function run 

{ 

Packages.com.abc.custom.CopyFile; 

} 

var eb = bsf.lookupBean("siEnvironmentBean"); 

print("TRIGGER SCRIPT echo.js: Event Type: " + eb.getEventName() + 

", " + eb.getEventType() + ", " + eb.getEventContext()); 

IMPORTANT Custom Java code runs inside the MKS Integrity Server JVM and 

therefore can impact server performance. Code that runs computationally intensive 

activities can degrade server performance. 

397


398 

Additional information on server-side event triggers is provided in the installed Javadocs in: 

installdir/data/documentation/javadocs/triggers/index.html 

You can also link the Javadocs from the MKS Integrity Server home page. To view the 

Javadocs, click the link for Event Trigger Java Documentation displayed under 

Documentation. 

The Javadocs provide API documentation that includes overview information, packages, 

classes, class hierarchies, deprecated APIs, and index information. 


JavaScript is not Java – what works in Java may not work in JavaScript. Note the following 

differences: 

JavaScript Java 

Not object-oriented Object-oriented language 

Not compiled, runs interpretively Is compiled 

Tries to continue running on errors Exceptions raised on errors 

Variable declaration is optional Variables must be declared 

Variables can change data type Variables cannot change data type 

Functions are used Methods are used 

Little encapsulation – only function variables are 

private 

Using Java Classes 

You can access Java classes in JavaScript. The following are examples for using JAVA classes: 

var myJAVAString = new java.lang.String(“JAVA_1.4_String”); 

var tokens = new java.util.StringTokenizer(myJAVAString, “_”); 

var myList = new java.util.LinkedList(); // creates an empty list 

// Add JAVA strings to the list 

myList.add( new java.lang.String(“List Element A”) ); 

myList.add( new java.lang.String(“List Element B”) ); 

myList.add( new java.lang.String(“List Element C”) ); 

For a full list of available classes, refer to the appropriate Sun Java docs. 


Full range of encapsulation (public, protected, 

private) for methods and variables

You can use server-side event triggers to run custom Java code from a script. 

Tips and Best Practices 

Custom individual class files go in the installdir/data/java/classes directory on the 

server. 

Custom JAR files go in the installdir/data/java/jars directory on the server. 

To use custom classes in JavaScript: 

var myApp = new Packages..; 

IMPORTANT Custom Java code runs in the MKS Integrity Server JVM and code that 

runs intensive activities can degrade server performance! 

Tips and Best Practices 

Check to see if there is a trigger script in the trigger library that already does what you 

need. 

As a starting point, modify an existing trigger script that is close to what you need. 

Build and test trigger scripts starting small, gradually adding more logic. 

Log script information to the server log as frequently as possible to help debug. 

Use an editor that supports JavaScript syntax highlighting to catch simple bugs. 

Keep system security in mind. Triggers run on the server under the permissions of the 

administrator and have the potential to affect file and system security. 

Try to limit the number of triggers. Triggers affect the duration of the command from the 

client’s perspective and can degrade performance. The more triggers on an event (or 

series of events) the longer the user has to wait for the event to complete. 

Trigger scripts that take a long time to run degrade server performance. MKS 

recommends writing short trigger scripts. 

399


400

A PPENDIX A 

Troubleshooting 

Diagnosing Server and Client Issues 

A 

MKS Integrity provides tools for monitoring and diagnosing issues that may arise when 

performing operations on the MKS Integrity Client and MKS Integrity Server. When 

used with MKS Customer Care assistance, these tools improve resolution time of 

product issues. 

This appendix contains the following topics: 

“Gathering Important Information” on page 402 

“Running MKS Integrity Server as Application” on page 405 

“Differencing MKS Integrity Server Properties Files” on page 406 

“MKS Integrity Server Logs” on page 406 

“MKS Integrity Client Logs” on page 407 

“MKS Integrity Server Logging Levels” on page 407 

“Miscellaneous Logging Properties” on page 409 

“FLEXnet Logs” on page 413 

“Dr. Watson Logs” on page 413 

“Creating Integrations Log” on page 413 

“Running MKS Integrity Server Diagnostics” on page 414 

“runstacktrace” on page 422 

“mksis” on page 423 

“isutil” on page 424 

“Starting Server in Safe Mode” on page 426 

“Troubleshooting Database Repository” on page 427 

“Troubleshooting Kerberos and Kerberos Single Sign-On” on page 428 

“Troubleshooting Configuration Management Reporting” on page 430 

401

Appendix A: Troubleshooting 

Gathering Important Information 

402 

Environment Information 

When reporting an issue to MKS Customer Care, the following information is commonly 

requested: 

product serial number 

operating system, RAM, and CPU speed of the client machine 

operating system, RAM, and CPU speed of the server machine 

if using a Web interface, the Web browser version 

version of the MKS Integrity Client and MKS Integrity Server, including service packs 

installed 

database type and version 

exact error message (a screen shot is helpful) 

steps to reproduce the problem 

properties and log files (for more information, see “Collecting Properties and Log Files” 

on page 421) 

Common Support Questions 

To identify the problem category, MKS Customer Care may ask the following questions: 

Are your platforms on the supported platforms list? 

To view this list, browse to: 

http://www.mks.com/support/platforms 

Does the problem happen for all users? 

If yes, then it is likely a server problem. 

Can you reproduce the problem on a different machine with the same configuration? 

If yes, then it is likely a client problem. 

Can another user only reproduce the problem on the same machine? 

If yes, then it is likely a machine problem. 

MKS Integrity Server Serial Number 

To determine your MKS Integrity Server serial number, do one of the following: 

Browse to http://:. The serial number displays near the bottom of 

the MKS Integrity Server home page.

Look for a sticker on the top of the product box. 

Look for the mksis.SerialNumber property in: 

IntegrityServerInstallDir/config/properties/is.properties 

MKS Integrity Server Version 

To determine your MKS Integrity Server version, do one of the following: 

Gathering Important Information 

Browse to http://hostname:port. The version and build number appear at the bottom of 

the MKS Integrity Server home page. 

Right click IntegrityServerInstallDir\server\mks\bin\neuron.exe, select Properties, 

and click Version. 

MKS Integrity Client Version 

To determine your MKS Integrity Client version, do one of the following: 

From a command line, type one of the following: 

si about (for configuration management) 

im about (for workflow and document management) 

integrity about (MKS Integrity Administration Client) 

aa about (Authorization Administration) 

From the GUI or Web interfaces, select Help > About. 

MKS Integrity Client and Server Directory Listing 

If MKS Customer Care asks for a directory listing of the MKS Integrity Server and the 

MKS Integrity Client directories, change to the directory that the MKS Integrity Server is 

installed in or the directory that the MKS Integrity Client is installed in. 

On Windows, use the following command to record the directory listing to a file that can be 

sent to MKS Customer Care: 

dir /b /s > listing.txt 

On UNIX, type: 

ls –R > listing.txt 

On Windows, the default is c:\Program 

Files\MKS\IntegrityServer2009 and the default is 

c:\Program Files\MKS\IntegrityClient. 

Is MKS Integrity Server Running? 

1 On the MKS Integrity Server, open: 

IntegrityServerInstallDir\log\server.log 

403


404 

2 Look for lines of the following form: 

INFO [IntegrityServer] GENERAL(0): Listening on clear port 

portnumber 

INFO [IntegrityServer] ApplicationState(0): Integrity Server 

(Build:, Service Pack: ) started 

where portnumber is your MKS Integrity Server’s port number. 

No lines should follow those lines that indicate a shutdown occurred. 

If you are using SSL, the following line is also in the log: 

INFO [IntegrityServer] GENERAL(0): Listening on secure port 

secureportnumber 

where secureportnumber is your MKS Integrity Server’s port used for secure SSL 

connections. 

What Time Zone Are You In? 

For data integrity purposes, MKS Integrity Server records what time zone it is in. If the time 

zone of the server differs from that of the database, the server does not start. View the 

server.log (see “MKS Integrity Server Logs” on page 406) file to determine which time zone 

the server is expecting for each. 

Following is an example from the log of an error for two differing time zones: 

17:59:38,331 WARN [ServiceController] Problem starting service 

mks:name=ServerTimeZone 

17:59:38,284 ERROR [Security] Starting failed mks:name=ServerTimeZone 

java.lang.Exception: Timezones and/or daylight savings settings don't 

match. Database: America/New_York, server: America/Buenos_Aires 

Is FLEXnet Server Running? 

On Windows 

NOTE If FLEXnet is unavailable, MKS Integrity Server shuts down and displays an 

error message. 

1 To start the FLEXnet configuration utility, start: 

FLEXnetInstallDir\bin\lmtools.exe 

2 On the Service/License File tab, click Configuration using Services. 

3 If multiple services are listed, select the service associated with the MKS Integrity Server. 

By default, this is FlexNet Service 1. 

4 Click Server Status.

Running MKS Integrity Server as Application 

5 Click Perform Status Enquiry. If the FLEXnet server is running, a message notifies you 

that the server is running, and it displays the location of the license file and how many 

licenses are available. 

On UNIX 

1 From a command line, type: 

ps –ef | grep lmgrd 

This searches a complete listing of all processes running and displays the lmgrd process 

(the FLEXnet Manager daemon). 

2 To use the lmstat command line utility (in flexnet/bin) to perform a status inquiry, 

type: 

lmstat -a -c[license file] 

For more information on this utility, browse to http://www.acresso.com. 

Running MKS Integrity Server as Application 

Sometimes it is useful to run the MKS Integrity Server as an application instead of as a 

service. If the MKS Integrity Server does not start, different error messages may appear on 

the command line that can be recorded and sent to MKS Customer Care. Additionally, you 

can obtain a thread dump in instances where the MKS Integrity Server experiences 

performance issues. 

To run the MKS Integrity Server as an application 

1 Stop the MKS Integrity Server service from a command line by changing to installdir/ 

bin, and typing the following: 

mksis[.bat] stop 

2 If you are not using the default administrative user, ensure that the administrator 

belongs to the administrators group. 

3 If you are not logged in as this administrator, log out and log in as the administrator. 

4 From a command line, change to installdir/bin and type the following: 

mksis[.bat] console 

The command output is sent to the startup.log file. For more information on the 

command, see “mksis” on page 423. 

5 To display a thread dump, press CTRL+BREAK. This only displays what is happening at the 

exact moment. So you may have to press CTRL+BREAK several times to determine how 

threads change over time. 

6 Copy the thread dump information to a text file and send it to MKS Customer Care. 

405


Differencing MKS Integrity Server Properties 

Files 

Error Codes 

406 

If you change properties files containing properties not in the database and make backup 

copies, differencing changed properties files against the backup copies can be useful in 

diagnosing server problems. 

NOTE MKS recommends that you make backup copies of the properties files located 

in IntegrityServerInstallDir\config\properties. 

To difference properties files 

1 Start the MKS Visual Differencing tool. 

2 Select File > Compare. 

3 Browse for the two files that you want to compare. and click OK. The differences 

between the two files are highlighted. 

Errors displayed in the GUI, Web, CLI, API, and logs may contain an error code. The error 

code is of the form MKS000000, for example MKS004364. Use the error code to obtain more 

information on the error from the MKS Customer Community (or contact 

MKS Customer Care). Information may include the cause of the error, its resolution, or a 

workaround. If multiple errors occurred from the action, then multiple error codes are 

displayed. 

MKS Integrity Server Logs 

The following MKS Integrity Server log files can be useful in diagnosing server errors: 

IntegritySereverInstallDir\log\server.log records server errors and events. By default, 

a new log is automatically started after the previous log reaches 10 MB. Versions of 

server.log are named incrementally, for example, server.1.log and 

server.2.log. By default, no more than 50 previous server.log versions are stored. 

To configure the size of the log file and the number of logs, see the MKS Integrity Server 

2009 Installation and Configuration Guide. 

IntegrityServerInstallDir\uninstall\.com.zerog.registry.xml records all the 

activities that occurred during the installation of the MKS Integrity Server.

MKS Integrity Client Logs 

IntegrityServerInstallDir\log\dbmigration.log is created when a database is migrated, 

for example, during an MKS Integrity upgrade. The output displays database version 

information, error messages, and SQL statements run against the database as part of the 

migration process. 

IntegrityServerInstallDir\log\dbcreation.log is created when a new database is 

created during the MKS Integrity Server install. The output displays database version 

information, error messages, and SQL statements run against the database as part of the 

database creation process. 

IntegrityServerInstallDir\hs_err_pid*.err typically appears if a Java error occurs, 

causing the server to stop running. These files are generated by the Java Virtual Machine 

(JVM) and consist of a stack trace at the time the server stops running. 

TIP To receive instant updates about MKS Integrity Server errors, you can configure 

the MKS Integrity Server to e-mail MKS Integrity Server log error messages. For 

more information, see the MKS Integrity Server 2007 Installation and Configuration 


MKS Integrity Client Logs 

IntegrityClientInstallDir\bin\IntegrityClient.log is the main MKS Integrity Client 

log file. It logs information messages, warnings, and errors. 

IntegrityClientInstallDir\uninstall\.com.zerog.registry.xml records all activities 

that occurred during the MKS Integrity Client installation. 

MKS Integrity Server Logging Levels 

To assist you in diagnosing server issues, you can record server messages and exceptions to 

the server.log. 

To adjust logging properties 

1 Edit the following file: 

IntegrityServerInstallDir\config\properties\logger.properties 

2 Uncomment the category of logging messages or exceptions to record. Generic 

categories include: DEBUG, DIAGNOSTIC, WARNING, GENERAL, ERROR, and FATAL. 

NOTE All lines containing the word DEBUG are commented out. This suppresses 

logging of debugging messages, which may help to increase performance. When 

necessary, these lines can be uncommented out for debugging. 

407


408 

3 Set the level of logging information to record. Ten (10) is the highest level of logging, 

and zero (0) disables logging. 

For example, you can adjust the level of logging information for the ERROR category: 

mksis.logger.message.includeCategory.ERROR=10 

mksis.logger.exception.includeCategory.ERROR=10 

TIP You can receive e-mail notifications about specific server messages or 

exceptions that are recorded to server.log. For more information, see “MKS 

Integrity Server Configuration Properties” on page 310. 

4 Save your changes. 

5 Restart the MKS Integrity Server. 

Client Logging Levels 

To increase the level of logging on the MKS Integrity Client, uncomment the desired logging 

levels in IntegrityClientInstallDir\IntegrityClientSite.rc: 

# START # 

# Turn up logging. 

# 

IntegrityClient.log.exception.includeCategory.WARNING=10 

#IntegrityClient.log.exception.includeCategory.DEBUG=10 

IntegrityClient.log.exception.includeCategory.ERROR=10 

IntegrityClient.log.exception.includeCategory.GENERAL=10 

IntegrityClient.log.message.includeCategory.WARNING=10 

#IntegrityClient.log.message.includeCategory.DEBUG=10 

IntegrityClient.log.message.includeCategory.ERROR=10 

IntegrityClient.log.message.includeCategory.GENERAL=10 

#IntegrityClient.log.message.includeCategory.CACHE=10 

#IntegrityClient.log.exception.includeCategory.CACHE=10 

#IntegrityClient.log.message.includeCategory.EVENT=10 

#IntegrityClient.log.exception.includeCategory.EVENT=10 

# Changes Formatting 

#IntegrityClient.log.message.defaultFormat={2}({3}) {5}\: {4}\n 

#IntegrityClient.log.exception.defaultFormat={2} {4} {5}\: {6}\n

# END # 

Miscellaneous Logging Properties 

By default, client HTTP-related messages, such as socket termination messages after each 

command, do not appear in the log. For example, if a low-level HTTP protocol fails, you can 

turn on HTTP logging to assist in determining what the exact problem might be. 

To display all client HTTP-related messages that may appear when using the client Web 

interfaces, add the following lines to the IntegrityClientSite.rc file: 

IntegrityClient.log.message.includeCategory.HTTP=10 

IntegrityClient.log.exception.includeCategory.HTTP=10 

Logging output displays in the value logFileName, or in the 

\bin\IntegrityClient.log file. You can adjust 

logging between 0 and 10. After you make changes to IntegrityClientSite.rc, save it, 

and restart the MKS Integrity Client. 

To display a timestamp with each log entry, add the following lines to the 

IntegrityClientSite.rc file: 

IntegrityClient.log.message.defaultFormat={2}({3}) {5}\: {4}\n 

IntegrityClient.log.exception.defaultFormat={2} {4} {5}\: {6}\n 


To debug security realms 

1 To increase the amount of logging to server.log for the security realm, add properties 

to the /config/properties/logger.properties 

file. 

For verbose LDAP debugging, use: 

mksis.logger.message.includeCategory.LDAP=10 

Successful authentications are logged when you set: 

mksis.logger.message.includeCategory.AUTHENTICATOR=10 

2 If necessary, uncomment the line for the realm you want to debug. 



409


410 

To debug solutions 

1 To debug installed solutions, add the following properties to the 

IntegrityServerInstallDir/config/properties/logger.properties file: 

server-side category that logs trigger operations 

mksis.logger.message.includeCategory.MKSRQ=10 

client and server-side category (can be set for both) that logs solution data model 

operations and configuration information 

mksis.logger.exception.includeCategory.IM-NOTIFICATION=5 

NOTE Due to heavy logging on the server, MKS recommends setting this category 

on the client only. 

server-side category that logs output when a solution command (rq) retrieves an 

item from the server 

mksis.logger.message.includeCategory.SDMCACHE=10 



si logging 

In addition to modifying the logger.properties file, you can use the si logging 

command to increase or decrease logging levels for several different categories (as outlined in 

the table next). You can run this command from a client or server machine. You can use any 

category included in the logger.properties file. Note the following: 

The client and server do not need to be restarted after making changes. 

Logging changes last only until the MKS Integrity Server or MKS Integrity Client is 

restarted. 

You need the DebugServer permission in the mks:si ACL to run this command. 

server.log file logs information about this command when it runs. 

From a command line, type: 

where 

si logging --category=value --level=value 

--category=value specifies the category name (see the table next for category names) 

--debug is equivalent to --category=DEBUG 

--level=value specifies the log level (0 disables logging, 10 logs all messages) 

--off is equivalent to --level=-1 (no reporting in this category)

--on is equivalent to --level=10 (logs all messages in this category) 


--target=value specifies the target debugging is enabled for. Valid values are client, 

server (default), and proxy. 

Acceptable values for --category=value are: 

Category Description 

DEBUG Logs debug messages. 

Note: Command overrides settings in logger.properties, but only until MKS Integrity 

Server restarts. Additionally, option does not explicitly log debug exceptions. To log 

exceptions, open logger.properties, uncomment 

mksis.logger.exception.includeCategory.DEBUG, and set value to 10. 

SQL Logs all SQL commands to server.log. For example, if you view item, SELECT 

statement logged. When editing item, INSERT, UPDATE, and SELECT statements logged. 

--level=5 logs all SQL commands. 

--level=10 adds additional information such as Rollback time. 

CACHE Logs cache operation information. Levels 0–3 not verbose. Levels 4–15 verbose. 

SMTP Logs communication between MKS Integrity Server and SMTP server. 

IM-NOTIFICATION Logs MKS Integrity e-mail notification. 

ACL Logs permission checking to server.log. For example, add label command logs 

following: 

2009-08-16 13:45:17,140 INFO [mksis.IntegrityServer] ACL(5): 

Check user administrator for permission 

CreateProject against acl mks:si. Resolved ACL: mks:si 

Decision: GRANTED 

TRANSACTION Logs all transactions performed by specific user, for example, 

si logging --category=TRANSACTION-jdoe --on 

logs all transactions performed by jdoe. 

To log all cache transactions, type TRANSACTION-system 

SILIB Similar to TRANSACTION, option logs more information about single command performed 

by a user, for example, 

si logging --category=SILIB-jdoe --on 

SICI Provides communications between workflow and document management functionality 

and configuration management functionality, and communications between MKS Integrity 

Client and MKS Integrity Server. 

REALM Logs NT realm information. 

API Logs Integrity API information. 

HLL Logs Integrity HLL server information. 

LDAP Logs LDAP security scheme information. 

AGENT Logs RMIs from MKS Integrity Client to MKS Integrity Server. 

SOLUTIONS Logs all solution data model operations and configuration information. 

411


Category Description 

MKSALM Logs all server side solution trigger operations. 

SDMCACHE Logs information when a solution command attempts to access an item from the 


MKSALMAUDIT Logs all server-side information for document model auditing. 

FINDER Logs all information related to the operation of the Finder dialog box. 

412 

You can also use the si logging command to enable debug logging on the MKS Integrity 

Client. To enable debug logging on the client, use: 

si logging --debug --on --target=client 

Valid values for --target are client, server (default), and proxy. 

im logging 

In addition to the si logging command, you can use the im logging command to increase 

or decrease logging levels for several different categories (as outlined in the preceding table). 

You can run this command from a client or server machine. 

From a command line, type: 

where 

im logging --category=value --level=value 

--category=value specifies the category name (see the table following for category 

names) 

--debug is equivalent to --category=DEBUG 

--level=value specifies the log level (0 disables logging, 10 logs all messages) 

--off is equivalent to --level=-1 (no reporting in this category) 

--on is equivalent to --level=10 (logs all messages in this category) 

--target=value specifies the target the debugging is enabled for (valid values are 

client, server (default), and proxy. 

Acceptable values for --category=value are as outlined for the si logging command on 

page 411.

FLEXnet Logs 

FLEXnet Logs 

You can direct the output from the license server (lmgrd) into a local log. If you are running 

FLEXnet as a service on Windows and it has been set up using Configure using Services in 

LMTOOLS, the name of this log can be specified in the Path to the debug log file field on the 

Config Services tab. 

If FLEXnet is not running, you can use a command line on UNIX or Windows, and type 

lmgrd –l to display the log. For more information on this log file, browse to: 

Dr. Watson Logs 

http://www.acresso.com/support/ 

If the client or server quits on a Windows platform, useful information is typically logged to 

the machine’s Dr. Watson log. On Windows 2000, you can configure the location of the 

produced log file and dump by running C:\winnt\system32\drwtsn32.exe. 

Creating Integrations Log 

Logging can be set for IDE integrations, such as Sybase PowerBuilder. 

1 Add the following lines to the userprofile_dir\IntegrityClient.rc file: 

integrations.debugLogFile=c\:\\installdir\\log\\mksapi.log 

integrations.debugLogLevel=5 

IMPORTANT You must use double slashes to escape slashes and colons. 

The debugLogLevel property can be set to any value between 0 and 10, where 0 does 

not display any information and 10 displays the most information. To reduce the 

amount of extraneous information, MKS recommends debugLogLevel=5. 

2 Restart the client. 

Sybase PowerBuilder 8.0 

In PowerBuilder 8.0, source control logging is set up on a per-workspace basis in the 

connection profile. 

To log source control activity in PowerBuilder 8.0 

1 Right click a workspace, and choose Properties. 

413


414 

2 Click Source Control. 

3 To enable trace logging, select Log All Activity. 

NOTE The default log file name is pbscc80.log and is saved in the workspace 

directory, but you can change the name and location. 

If Overwrite Log File is selected for PowerBuilder 8.0, the log file is overwritten for each 

session. The default setting is Append To Log File. 

IBM Eclipse 2.0/Websphere Studio 5.0 

Websphere does not log version control activity specifically, but version control errors 

appear in Websphere’s general debug log located in \.metadata\.log. 

To display the debug log, system properties, and the list of plug-ins, select Help > About, and 

click Configuration Details. 

Running MKS Integrity Server Diagnostics 

To monitor and diagnose issues that may arise when performing operations on the 

MKS Integrity Client and MKS Integrity Server. The MKS Integrity Administration Client, 

and the si diag and im diag commands offer several diagnostics you can run on the 

workflow and document management, and configuration management components. 


To view the Server Diagnostics node in the MKS Integrity Administration Client, run 

server diagnostics, and create a support package, you must have the AdminServer 

permission for MKS Integrity Server; configuration management; or workflow and 

document management. If the permission is denied, the Server Diagnostics node does 

not appear. 

Server metrics and certain diagnostics may take a long time to run, impacting server 

performance. MKS recommends running these metrics and diagnostics during non-peak 

usage. 

To run server diagnostics in the GUI 

1 In the MKS Integrity Administration Client, select the Workflows and Documents or 

Configuration Management node, and then open the Server Diagnostics node.

2 Select one of the following server diagnostics: 

Diagnostic Description 


Change Logging Levels Changes logging levels for the server. 

In the available fields, choose the category and logging level. Available 

logging categories include: ACL, AGENT, API, CACHE, DEBUG, ERROR, 

GENERAL, IM-NOTIFICATION, LDAP, REALM, SD, SMTP, SQL, TM, and 

WARNING. By default, DEBUG is selected. 

To permanently save your changes, select true. By default, false is 

selected. 

For more information on logging, see the MKS Integrity Server 2009 


Change Package Servers Displays a list of configuration management servers which have change 

packages tracked by items on this MKS Integrity Server. 

Client Connections Displays list of all clients connected to the server. List includes user name, 

host name, port, and time connection established. 

Server Errors Displays the most recent 50 lines from the server log at or above the ERROR 

level. 

Server Log Displays the most recent 500 lines from the server log. 

Collect Support Package Collects client/server logs, statistics, and properties into compressed ZIP file 

(called support package). When support package assembled, you can e-mail 

to MKS Customer Care for further diagnosis. 

For more information, see “Collecting Properties and Log Files” on page 421. 

415



416 

Connected Source Servers Displays a list of configuration management servers connected to the 


Database Connections Displays list of all open database connections. 

Each open database connection shows where (via a stacktrace) the 

connection was requested from the JDBC connection pool, the name of the 

thread that requested the JDBC connection, and the timestamp when the 

connection was pulled out of the JDBC connection pool. 

JVM Memory Usage Performs garbage collection and displays memory in use, free memory, and 

total memory in bytes. 

License Usage Displays each type of license (workflow and document management, 

configuration management, seat, float) and user that has license currently 

checked out. 

Note: Users on multiple MKS Integrity Servers show license checked out for 

each server. If multiple MKS Integrity Servers connected to same license 

server, license information may not reflect actual number of licenses currently 

checked out. 

If license monitoring is enabled, this diagnostic also displays the appropriate 

stats categories. For more information on FLEXnet license monitoring, see 

the MKS Integrity Server 2009 Installation and Configuration Guide. 

Metrics Displays server metrics, such as the maximum change package entries per 

change package, and the average time entries per user. 

Running Displays a list of charts, dashboards, queries, and reports that are currently 

running. 

Stacktrace Collects server stacktrace. 

Statistics Displays server statistics. By default, the previous week’s statistics are stored 

in a support package. Each statistic is stored separately in the ZIP file as a 

separate file, with the statistics under a directory named Stats. Each file 

under the Stats directory is in the format yyyy.MM.dd-HH.mm.ss. 

Verbose Garbage 

Collection 

Enables or displays verbose garbage collection for the server JVM. 

To diagnose garbage collection issues, the server retains the 10 most recent 

garbage collection logs if verbose garbage collection is enabled. A new 

garbage collection log (gc.out) is automatically started after the server 

restarts. Versions of gc.out are named incrementally, for example, 

gc.out.1 and gc.out.2. 

Note: Verbose garbage collection slows down server performance. MKS 

recommends disabling this option as soon as you complete your analysis. 

3 To run the selected diagnostic, click Run Diagnostic at the top of the diagnostic view. The 

results display in the diagnostic view. 

4 To perform a text search on the results, click anywhere in the diagnostic view and press 

CTRL+F. A search bar displays at the bottom of the diagnostic panel. As you type in the 

Find field, the results become more specific.


5 For some diagnostics, you can save the information to a file by clicking Save Output. A 

standard save dialog box appears, allowing you to save the information as a text file on 

the server’s file system. 

To run server diagnostics in the CLI 

From the command line, type one of the following commands: 

Server diagnostics on the configuration management component: 

si diag --diag=value --target=server 

Server diagnostics on the workflow and document management component: 

im diag --diag=value --target=server 

where im diag specifies the workflow and document management component and si diag 

specifies the configuration management component, value specifies the diagnostic name, and 

server specifies the MKS Integrity Server to run the diagnostics on. Acceptable diagnostics for 

value are as follows: 


backupdatabasea Backs up Derby database to installdir/data/derby.db/backup. 

connections Displays list of all server connections. List includes user name, host name, 

port, and time connection established. 

collectsupportpackagea Collects client/server logs and properties into compressed ZIP file (called 

support package). When support package assembled, you can e-mail to MKS 

Customer Care for further diagnosis. 

For more information, see “Collecting Properties and Log Files” on page 421. 

cpservers Displays a list of configuration management servers which have change 

packages tracked by items on this MKS Integrity Server. 

dumpstacks Collects server stacktrace. 

getNextCheckpointDate Displays the timestamp of the earliest conflicting transaction. If there are no 

conflicting transactions, none is displayed. 

heap Performs garbage collection and displays memory in use, free memory, and 


isproperties Displays list of server properties not specific to workflow and document 

management, or configuration management. To configure statistics collection, 

purging, and license monitoring properties, use the setispolicy 

diagnostic. 

licenses a 

Displays each type of license (workflow and document management; 

configuration management; seat; float) and user that has license currently 

checked out. 

Note: Users on multiple MKS Integrity Servers show license checked out for 

each server. If multiple MKS Integrity Servers connected to same license 

server, license information may not reflect actual number of licenses currently 

checked out. 

417



418 

listopendbconnections Displays list of all open database connections. 

Each open database connection shows where (via a stacktrace) the 

connection was requested from the JDBC connection pool, the name of the 

thread that requested the JDBC connection, and the timestamp when the 

connection was pulled out of the JDBC connection pool. 

listOpenSITransactions Displays the current open DB backend transactions that could potentially 

conflict with a checkpoint operation; along with their stacktrace, transaction 

time, and thread name. This diag is useful for diagnosing checkpointing 

issues. 

log Displays recent server log output. 

To display the most recent 500 lines from the server log, use the appender 

MEMORY, for example, for example, --diag=log MEMORY. 

To display the most recent 50 lines from the server log at or above the ERROR 

level, use the appender MEMORYERROR, for example, --diag=log MEMORY. 

Caution: This diagnostic uses the server’s memory. 

mem Performs garbage collection and displays memory in use, free memory, and 


metrics Displays server metrics, such as the maximum change package entries per 

change package, and the average time entries per user. 

policies Displays list of all workflow and document management policies. 

policy Displays list of all modified global policy settings. User preferences, default 

settings, and project settings not displayed. 

properties Displays list of all properties on server. Includes settings in si.properties, 

is.properties, im.properties, and logger.properties. 

reloadfunctions Reloads dialect-specific JAR files into the database during server startup. 

These JAR files add functions into the database that support complex 

computations. Restart the server after using this diag. 

reclaimprojectname Reclaims project name of the project path specified in param option. Path 

case sensitive. You need to reclaim dropped project in RCS style repository to 

completely remove it from repository. Enables you to create or import project 

using same repository location. 

You must stop and restart server after reclaiming project name before you can 

re-use repository location. 

Command can also be used for reclaiming subproject namespaces. 

refreshUserGroupCache Clears framework-level caches (subject, user name, group and LDAP). This is 

useful for updating user and group caches when your external directory 

service is updated. 

Note: If you specify this option with im diag, it has the additional effect of 

rebuilding the Integrity-level caches. 

running Displays list of charts, dashboards, queries, and reports that are currently 

running.



sqllogging If SQL logging is enabled on the MKS Integrity (im/si logging command), 

you can set SQL logging levels for specific users. Setting the logging level can 

assist in isolating specific user commands and improving server performance. 

For example, if logging levels are high and server performance is impacted, 

reducing logging levels may improve performance. 

To set SQL logging levels for a user, type: 

im/si --diag=sqllogging username logginglevel 

where 

username is the user ID of the user whose commands you want to log. 

logginglevel is one of the following number or text values: high (0), medium 

(5), low (10), or off (-1). 

For example, typing: 

im diag --diag=sqllogging jriley high 

logs all workflow and document SQL commands for the user jriley to the 

category SQL-jriley. 

419



420 

setispolicy Configures the following server policies: 

Name: mksis.statisticsInterval 

Int Value: 7200 

Default: 60 

Min: 30 

Max: 10000000 

Description: Controls the number of seconds between collecting statistics. To 

diagnose intermittent server performance issues, lower this number. 

Name: mksis.statisticsPurge 

Default: weekly 

Description: Purges stored statistics weekly or monthly. After the specified 

period, only one statistic per day is stored, while others are deleted. To 

manually purge statistics, specify none and use SQL statements to purge the 

data. 

Note: To prevent overloading the MKS Integrity Server with statistics, 

especially if the interval is set low, one statistic per day is purged upon each 

server start. 

Name: mksis.serverLicenseInterval 

Int Value: 60 

Default: 60 

Min: 0 

Max: 10000000 

Description: Controls how frequently (in seconds) server license usage is 

polled and recorded in the server statistics. You can disable this policy by 

setting the value to 0. If collection is enabled, the minimum allowed value is 

60 seconds. 

Name: mksis.flexLicenseInterval 

Int Value: 0 

Default: 0 

Min: 0 

Max: 10000000 

Description: Controls how frequently (in seconds) FLEXnet license usage is 

polled and recorded in the server statistics. If multiple Integrity Servers are 

pointing at the same FLEXnet license server, MKS recommends enabling this 

policy on one Integrity Server only. You can disable this policy by setting the 

value to 0. If collection is enabled, the minimum allowed value is 300 

seconds. 

setpolicytodefault Restores the policy to the default value. 

showrepdir Displays list of projects, archives, and directories contained in database 

repository. Requires si.repositoryBrowsingEnabled property to be 

true in si.properties file. 

statistics Displays server statistics. By default, the previous week’s statistics are stored 

in a support package. Each statistic is stored separately in the ZIP file as a 

separate file, with the statistics under a directory named Stats. Each file 

under the Stats directory is in the format yyyy.MM.dd-HH.mm.ss. 

a AdminServer permission must be used. Admin permission not required.

Collecting Properties and Log Files 

Collecting Properties and Log Files 

If you are unable to diagnose a problem with the MKS Integrity Server using the server 

diagnostics, you can collect client and server logs, server statistics, and properties into a 

compressed ZIP file (called a support package). When your support package is assembled, you 

can e-mail it to MKS Customer Care for further diagnosis. 


If certain files do not exist on the MKS Integrity Client or MKS Integrity Server, within 

the ZIP file each client and server’s manifest.txt file indicates which files are missing. 

Additionally, each manifest.txt file includes the date and time the files were 

collected, the target component (client, server, or proxy), the full path to each file, and 

the date and time each file was last modified. 

If the support package exceeds 5 MB, MKS recommends removing some of the older 

server.log (or for previous server versions, weblogic.log) files from the support 

package before e-mailing it to MKS Customer Care. 

In the support package, each server statistic is stored as a separate file in the Stats 

directory. Each file is in the format yyyy.MM.dd-HH.mm.ss. 

The five most recent license.log files are captured in the support package. 

For security reasons, the following sensitive information is not included in the support 

package: 

in si.properties: 

im.user=xxxx 

im.password=xxxx 

si.anonymousUser=xxxx 

si.anonymousPassword=xxxx 

in im.properties: 

mksis.im.prodPassword=xxxx 

mksis.im.prodUser=xxxx 

in is.properties: 

mksis.proxy.*.adminPassword=xxxx 

mks.dbUser=xxxx 

mks.dbPassword=xxxx 

mksis.privatekey.password=xxxx 

421


422 

in security.properties: 

ldap.credential=xxxx 

ldap.principal=xxxx 

ldap.credential=xxxx 

ldap.principal=xxxx 

clear text passwords 

To create a support package in the GUI 

1 From the MKS Integrity Administration Client, connect to the MKS Integrity Server that 

you want to retrieve server files from. 

2 From the tree pane, select the Workflows and Documents or Configuration 

Management node, and then select Server Diagnostics > Collect Support Package. 

3 In the Target ZIP file for Support Package field, type a name for the ZIP file, for example, 

support.zip, or click Browse and locate an existing ZIP file to add the information to. 

4 Click Run Diagnostic. You are notified that the support package has been created. 

5 E-mail the support package to MKS Customer Care. For tips on what information to 

include when you contact MKS Customer Care, see “Environment Information” on 

page 402. 

To create a support package in the CLI when the MKS Integrity Server is not running 

From a command line, go to installdir/bin and type one of the following commands: 

On Windows: 

NOTE This command collects server files only. 

collectSupportPackage.exe zipFilename 

On UNIX: 

runstacktrace 

collectSupportPackage zipFilename 

where, zipFilename specifies the name of the ZIP file, for example, support.zip. 

MKS provides a stack trace monitor for generating server stack traces in cases where the 

MKS Integrity Server is unresponsive (hangs). The stack trace monitor does not rely on the 

si diag command. The command writes the stack trace and date/time information to a 

stacktrace file.

mksis 

To generate a stack trace, create a file called: 

installdir/data/runstacktrace 


Once you create the runstacktrace file, the MKS Integrity Server then automatically 

creates the installdir/bin/stacktrace file and writes all stack trace and date/time 

information to it. 

To stop generating stack traces, remove the runstacktrace file in the installdir/data 

directory. 

You can also set the interval for the stack trace monitor to poll for the runstacktrace file. To 

set the monitoring interval, set the following property in the installdir/data/ 

is.properties file: 

mksis.monitorInterval= 

IMPORTANT By default, the monitoring interval is 30 seconds. Setting a monitoring 

interval of less than 10 seconds can have adverse effects on performance. 

The mksis.bat (mksis in UNIX) file provides some administrative functionality for the 

MKS Integrity Server. The file is located in the following directory: 

installdir/bin/mksis[.bat] 

where installdir is the MKS Integrity Server installation directory. 

The following is the syntax for the command: 

mksis subcommand 

where subcommand is one of the following: 

console starts the MKS Integrity Server in console mode as an application only without 

the service as specified in: 

installdir/config/ 

install installs the MKS Integrity Server as an Windows NT service 

remove removes the MKS Integrity Server service 

restart restarts the MKS Integrity Server service 

safemode restarts the MKS Integrity Server in safemode (see “Starting Server in Safe 

Mode” on page 426) 

start starts the MKS Integrity Server service (Windows) or daemon (UNIX) 

mksis 

423


isutil 

424 

stop stops the MKS Integrity Server service (Windows) or daemon (UNIX) 

To assist with managing the database repository, the MKS Integrity Server includes a series 

of isutil commands. The isutil commands allow you to perform a variety of 

maintenance and configuration tasks related to the database repository while the 

MKS Integrity Server is not running. 

If you experience cache corruption issues or are restoring your repository from a backup, a 

cold restart of the MKS Integrity Server may be required. The isutil command allows you to 

flush and rebuild all or specific caches when you restart the server, resulting in a potentially 

lengthy downtime before users can access the server. To determine if you need to perform a 

cold restart, contact MKS support. 

The isutil utility is installed with the MKS Integrity Server in the installdir/bin directory. 

CAUTION Certain isutil commands can permanently alter the database and 

cannot be undone. MKS recommends using these commands only with guidance 

from MKS Customer Care or MKS Professional Services. 

Command usage is: 

isutil -c command [-?] [-d] [command-arguments] 

where command is one of the following: 

aclcreate creates or resets the ACL table in the MKS Integrity Server database. 

acldestroy deletes the ACL table in the MKS Integrity Server database 

aclexists tests whether the ACL table exists in the MKS Integrity Server database. 

aclmigrate migrates the ACL entries table to the latest version (database schema). No 

action is taken if the tables are already at the current schema level. 

blobperf tests the performance of BLOB access in the MKS Integrity Server database. 

cmactiveon enables the maintenance of ArchiveShared and active-project properties. 

cmalterarchivebasename changes the archive base name. 

cmalterdirname changes the directory tree name. 

CAUTION The cmalterdirname command is not intended as a general purpose 

rename gesture. Several external references are not updated by the command. 

Contact MKS Customer Care for more information. 

cmalterprojectbasename changes the project base name.

cmdbcreate creates and initializes the configuration management database repository 

tables. 

cmdbmigrate migrates the configuration management database repository tables to the 

latest version (database schema). No action is taken if the tables are already at the 

current schema level. 

CAUTION The cmdbmigrate command cannot be reversed because there is no 

reverse migration tool. Because the new database schema does not operate with 

older versions of MKS Integrity, ensure that you have a backup of your database 

before running the command. 

cmlist lists the names of the requested object type from the database. 

dbinstall sets up the database similar to the MKS Integrity Server installer. 

diag runs an MKS Integrity Server diagnostic. For a list of diagnostics, see “To run 

server diagnostics in the CLI” on page 417. 

imdbcreate creates and initializes the workflow and document database tables. 

imdbdestroy deletes the workflow and document database tables. 

imdbgetversion retrieves the current workflow and document database schema 

version. 

imdbmigrate migrates the workflow and document database tables to the current 

Schema. 

imdbrebuildtable rebuilds the specified database table. You can specify the location 

for the table to be stored, another location for its LOB data, and another location for its 

indexes (for example, isutil -c imdbrebuildtable 

[ [ []]]). 

metrics runs database metrics. For a list of metrics, see “To run server diagnostics in the 

CLI” on page 417. 

migrateserverconfig migrates your existing MKS Integrity Server configuration to a 

new MKS Integrity Server installation. 

sidbcreate creates and initializes the configuration management tables. 

An example of isutil command usage is as follows: 

C:\Program Files\MKS\IntegrityServer2009\bin\isutil -c aclcreate 

isutil 

425


Starting Server in Safe Mode 

426 

Starting the server in safe mode provides the application administrator with a way to 

perform configuration tasks while preventing all other users from accessing the system. 

While in safe mode, from either the GUI or the CLI, the administrator may configure global 

permissions and administer the MKS Domain. 

Note the following about using the MKS Integrity Server in safe mode: 

Only one user may log in. 

All ACL permission verification is disabled for the user logged in. 

The administrator does not have access to workflow and document management, and 

configuration management functions. 

To start the MKS Integrity Server in safemode from the CLI 

To start the MKS Integrity Server in safe mode, use the mksis command (see “mksis” on 

page 423). The following is the command syntax for starting the MKS Integrity Server in safe 

mode: 

where 

installdir/bin/mksis console safemode password 

installdir is the MKS Integrity Server installation directory 

password creates a new password for this safemode session 

The user name for logging into the server in safe mode is safemode, and the password is the 

password specified on server start. 

You can script the server start in safemode by modifying the following file: 

installdir/config/ 

The properties are: 

wrapper.java.additional.8=-Dmks.safemode= 

wrapper.java.additional.9=-Dmks.safemode.password=

Troubleshooting Database Repository 

Starting MKS Integrity Server 

Troubleshooting Database Repository 

To start the MKS Integrity Server, follow the procedures outlined in the MKS Integrity Server 

2009 Installation and Configuration Guide. 

NOTE If the MKS Integrity Server and database repository are on separate machines, 

and both machines are running with JVM, the machines must be set to the same 

locale or the MKS Integrity Server may not start. 

Database Connections After Routine Backups 

When performing a routine backup of your database that requires the database to be 

disconnected, you should wait until the database is fully online before attempting to run any 

commands from the MKS Integrity Server. If the database is not fully online before running a 

command, an error message is posted. 

Archives for Dropped and Added Migrated Members 

When using the database repository option for configuration management, dropping a 

migrated project member and re-adding the member of the same name does not cause the 

member archive to branch. Instead, a new archive is created without the RCS directory. If you 

want to reuse the archive, add the member using the Add From Archive command (see the 

MKS Integrity 2009 User Guide). 

Controlling Bulk Data Storage in Oracle 

Where Oracle is used for the database repository, you can control the storage of bulk data by 

controlling the storage of the VALUE column in the CMARCHBULK table. Oracle Locator Object 

(LOBs) data is now supported for the database repository. 

DB2 and Transaction Log 

If you are using a DB2 database and you encounter a “not enough storage” error message in 

the transaction log, modify the app_ctl_heap_sz parameter by typing the following from 

the DB2 Command Line Processor on the DB2 server: 

db2=> update db cfg for DBname using app_ctl_heap_sz 1024 

where DBname is the name the local DB2 Client uses to reference the database. For large 

transactions, values in the order of 4096 may be required. 

Adding Large Files on MS SQL Server Database 

Adding large files (for example, files larger than 250 MB) is not supported on the MS SQL 

Server database and can cause a connection timeout to the database. 

427


428 

MS SQL Server Database Uses Case-sensitive Collation 

If you are using MS SQL Server as the backing database for the repository, you must 

configure a case-sensitive collation when creating the database or the MKS Integrity Server 

service will not start. A collation specifies the bit patterns that represent each character and 

the rules by which characters are sorted and compared. 

NOTE Case-sensitive collation is not addressed in the case sensitivity setting for 

configuration management project names. 

IMPORTANT If the installer cannot alter an existing MKS Integrity database due to 

case mismatches, workflow and document and configuration management 

functionality will have to run in separate, named databases on separate 

MKS Integrity Servers. 

Locale Mismatch When Installing With Database Repository Option 

When installing the MKS Integrity Server with the database repository option, a mismatch 

can occur between the installer JVM and server JVM locales when setting the default case 

sensitivity for the SQL Server database. The mismatch does not occur when the case sensitive 

option is enabled for the database. 

To correct the locale mismatch problem, run the following SQL statement: 

update CMSCHEMAPROP set VALUE='en_US' where 

NAME='CMInsensitivityLocale' 

If you encounter any problems installing or using the database repository, contact 


Troubleshooting Kerberos and Kerberos Single 

Sign-On 

The following error messages may appear in log files or debugging information if the 

Kerberos or Kerberos Single Sign-On has not been set up correctly. 

NOTE To turn debugging on, add mks.security.debug=true to 

security.properties. 

ERROR(0): No valid credentials provided (Mechanism level: Server not 

found in Kerberos database (7)) 

If this error message appears in the client side log file, your 

mks.security.clientServiceName setting is not correct. Make sure it is set to be the 

name of the user the MKS Integrity Server is running as.

Troubleshooting Kerberos and Kerberos Single Sign-On 

WARNING(0): The registry key required to support Kerberos Single- 

Sign-On is missing. You may wish to add them manually. 

WARNING(0): Integrity Server does not allow registry key to be 

automatically added. Either add the key manually or consult your 

Integrity Server administrator 

WARNING(0): On Windows Server 2000 and 2003 the key 

"allowtgtsessionkey" in HKEY_LOCAL_MACHINESystem\CurrentControlSet\ 

Control\Lsa\Kerberos\Parameters with value 1 should be added (reboot 

may be required). 

If any of these error messages appear in the client side log file, the client side registry key 

is missing. 

ERROR(0): No valid credentials provided (Mechanism level: Failed to 

find any Kerberos Ticket) 

If this error appears in the client side log file, either the mks.security. 

kerberosRealmName or mks.security.kdcAddress setting is wrong, for example, the 

realm name is not entered in uppercase. 

15:52:35,661 INFO [IntegrityServer] DEBUG(10): Login exception 

encountered while attempting authentication of user kmorton via 

policy default-policy. Details of exception No valid credentials 

provided (Mechanism level: Failed to find any Kerberos Key) 

If this error message appears in the server side log file, the mks.security.SPN setting 

does not match the -princ option given in the ktpass command. 

17:37:03,208 INFO [STDOUT] error Message is Client not found in 

Kerberos database 

If this error message appears in the Kerberos debug information, there is a problem with 

the keytab file. It may contain an invalid principal name, or the mks.security.SPN 

setting may not match the -princ option given in the ktpass command. 

DEBUG(10): Login exception encountered while attempting 

authentication of user ldaprealmtest1 via policy default-policy. 

Details of exception Pre-authentication information was invalid (24) 

If this error message appears in the server log when trying to authenticate using either a 

windows_clear or windows_private security policy, the case is wrong in the 

mks.security.kerberosRealmName or mks.security.kdcAddress setting in 

security.properties. 

DEBUG(10): Login exception encountered while attempting 

authentication of user ldaprealmtest1 via policy default-policy. 

Details of exception Clock skew too great (37) 

If this error appears in the server log when trying to authenticate using either a 

windows_clear or windows_private security policy, the clock on the server is not 

synchronized with the clock on the client machines. For the Kerberos authentication 

429


430 

domain to work, the server and client clocks must be synchronized (within a reasonable 

amount of time). 

For additional troubleshooting information, visit the following Web page: 

http://java.sun.com/j2se/1.4.2/docs/guide/security/jgss/tutorials/ 

Troubleshooting.html 

Troubleshooting Configuration Management 

Reporting 

For clients to be able to run configuration management reports, you must specify Microsoft 

Access as the report application in the IntegrityClientInstallDir\IntegrityClientSite.rc 

file. This file is updated automatically if you select MS Access as the reporting application 

during the client installation. However, if MS Access is not installed at the time of the client 

installation, you will not be able to select it as your reporting application, and the client will 

not be able to run configuration management reports. 

If MS Access is installed on a client after MKS Integrity has been installed, you can manually 

set the si.databaseCommand property in the IntegrityClientSite.rc file to specify the 

path of MS Access and of the MS Access database, for example: 

si.databaseCommand="C:\\program files\\microsoft 

office\\office10\\msaccess.exe" "C:\\program 

files\\MKS\\bin\\sirept2000.mdb" /runtime /excl /cmd "{0}"

A PPENDIX B 

Glossary 

Definitions of Common Terms 

B 

This glossary provides a glossary of common terms and definitions for MKS Integrity 

Server, MKS Integrity, and MKS Integrity. 

author A value for the Reference Mode field which signifies that the user or group has 

full permissions to modify the document item. Modification of the document item will 

force a branch for all other Reuse references. Changes to the document made in Author 

reference mode do not result in a branch of the document. 

change orders Change orders are process items that control the authorization of change 

to a document or document item. 

change requests Change requests are process item that track the request to effect 

change to a document or document item. Change requests may or may not be related to 

document. When change requests are accepted, change orders are created to authorize 

the change. 

couplet A couplet is the architectural term for the node and shared item MKS Integrity 

items. Together these create a document item and facilitate sharing and reuse use cases. 

data model The combination of MKS Integrity item types, fields, relationships and 

other administration objects that define a system and its basic behaviours. 

document A document is an MKS Integrity item type class that represents a container 

for grouping and managing document items at a high level. 

document class The term used in MKS Integrity to describe different types of 

documents (segment) and content (nodes) in the document model. 

document item A generic term for describing a node/shared item or a node/document 

pairing. Also substituted for content and couplet in certain instances. 

document model The term used to describe the inter-related components that make up 

and control the behavior of documents within MKS Integrity. The document model is 

defined and modified through various types within the MKS Integrity Administration 

Client and controls how segments, nodes, and shared items, interact with each other for 

the purposes of versioning and reuse. To learn more about the individual document 

model components, see see the ALM section of the MKS Knowledge Base. 

431

Appendix B: Glossary 

432 

domains Generic term used for describing a discipline or body of work like requirements 

management or test management. Encompasses all gestures, actors, and artifacts related to 

that discipline. 

external relationships The MKS Integrity relationship fields that link artifacts within a 

domain to process items like Change Requests and Change Orders. 

meaningful A node or segment is defined as meaningful by editing the Shared Category 

FVA field. Artifacts are usefully marked as meaningful and non-meaningful for reporting 

purposes. See the field computation for details. 

node The internal MKS Integrity architectural term for content item or subdocument. 

non meaningful A node or segment is defined as nonmeaningful by editing the Shared 

Category FVA field. Artifacts are usefully marked as meaningful and non-meaningful for 

reporting purposes. See the field computation for details. 

reuse A value for the Reference Mode field which signifies that the content belongs to 

another document and is being referenced by the current document. Any user or group with 

the applicable permissions can modify the content and any modification will not affect any 

other reference to the same item. If a change is made, the system will branch the item and the 

branched item will then have a Share reference to it. 

segment The internal MKS Integrity architectural term for document. A segment is 

represented by the Document item type but is also referred to generically as document. 

Subsegments are subdocuments. Also Segment Roots. 

segment roots The internal MKS Integrity architectural term for top level document. 

Documents that are not included or referenced inside of other documents. 

share A value for the Reference Mode field which signifies that the user (or group) of a 

document is referencing a shared item. It cannot be edited directly and it will show all 

changes made by the Author to the shared item. 

shared item An MKS Integrity item type class that represents the shared or common 

content across all instances of a document item. 

significant fields The list of MKS Integrity fields within a document item that cause the 

system to version or branch that document item. 

solution template A pre-configured set of MKS Integrity item types, fields, triggers, queries, 

reports and other administrative objects used to demonstrate how the platform can be used 

to solve the challenges of a particular domain. MKS offers solution templates for Iterative, 

Waterfall, ITIL, Application Service Management, Test Management, Application Lifecycle 

Management (ALM), Re-use Enabled Requirements Management and other processes and 

disciplines. 

trace relationship The MKS Integrity relationship field(s) which link artifacts within a 

domain or between domains using the Verifies/Verified By relationship between 

requirements and tests.

A change package is a group of changes made by a single user that can be considered a 

logical unit of work. Only the creator of a change package can add entries to that change 

package. Change package entries are added when you specify a change package while 

performing member operations. 345 

A change package review is a review of changes by specified reviewers before the changes 

are committed to the server repository. 346 

A change package reviewer is a user specified by your administrator to review change 

packages containing members associated with specific projects. The reviewer may be 

individually specified or a member of a specified reviewer group. In the case of a reviewer 

group, any member of that group casts an accept or reject vote on behalf of the entire group. 

346 

A change package watcher is a user specified by your administrator who is notified when a 

reviewed change package is closed after being successfully committed to the repository. 

Change package watchers may be individually specified or a member of a specified watcher 

group. 346 

A dashboard is a static, user-definable view comprised of any combination of charts, reports, 

images, labels, and links to reports, queries and Web sites. 6 

A graphical user interface, or GUI, is a program interface that uses a number of visual 

components (such as icons, pointers, and pull-down menus) to execute commands. Working 

in a GUI allows the user to give instructions to the computer without having to learn a 

specific command language. The MKS Integrity Administration Client interface is a GUI 

designed for carrying out most administrative commands from a central location. 10 

A query is a request to select and list the items that meet specific selection criteria. The 

selection criteria are a logical expression of specific values, or ranges of values, of the 

standard and custom fields of the item type. 240 

A shared subproject is a subproject that is a member of more than one configuration 

management project. You can share a subproject between two or more projects by referencing 

the original subproject. A shared subproject allows you to access common members across 

many projects. Shared subprojects are not required to be located within the same directory 

structure or project hierarchy. 286 

A super reviewer is a user with permission to vote on change packages, but who is not 

required to be a listed reviewer for the change package. Voting as a super reviewer overrides 

all other votes. For example, casting an accept vote as a super reviewer is sufficient for 

accepting the change package. 346 

A user is anyone who needs to work with one or both of MKS Integrity components. Users 

are assigned user permissions by the administrator. Users are also assigned to groups that 

have specific MKS Integrity group permissions assigned by the administrator. 4 

A ViewSet is a collection of views in a specific configuration that persists each time the user 

opens and closes the MKS Integrity Client. As an administrator, you have the ability to 

control the configuration of ViewSets. Each ViewSet can be designed around one or more 

433


434 

tasks, often corresponding to a specific role, such as a developer or project manager. For 

example, a developer ViewSet might contain views and actions for items and queries, while a 

project manager ViewSet might contain views and actions for charts, reports, and 

dashboards. 50 

Admin provided objects are objects within the workflow and document object model that 

support solution definition and management, as well as workflow migration. 244 

Charts are graphs that present trends over time or distributions of the data in your project. 

Charts are based on the standard and custom fields of item types. You can display trend 

charts as line or bar graphs, and distribution charts as pie or bar graphs. You can also display 

data in tabular form. 240 

Importing a configuration management project registers it with the MKS Integrity Server. 

Once a project is imported, MKS Integrity commands can be performed upon it. 268 

In workflow and document management, a project contains labels that help you sort and 

organize items in a hierarchical structure. 5 

MKS Integrity allows you to create large configuration management projects composed of 

smaller component projects. These smaller projects are known as subprojects. Subprojects 

behave in the same way as projects and can be accessed with most project and Sandbox 

commands. 284 

MKS Integrity project administrators are allowed to edit and view workflow and document 

projects. Project administrators can also manage all child projects of the project they are 

approved for. Project administrators cannot edit projects assigned to another project 

administrator, and they can only create and delete subprojects—they cannot create top level 

projects unless they have been granted the CreateProject permission. 262 

Presentation templates are customizable layouts for displaying items in MKS Integrity. 



and drop functionality to help you create a custom layout for a selected item type. 191 

relevance Relevance is a set of field conditions that determine which fields are relevant to 

selected groups of users or to specified field values. Fields that do not meet the relevance 

rules are not visible to users. 134 

state In MKS Integrity, item types can each have their own set of states to advance through. 

They can also follow a state model defined by the project administrator, giving greater 

control over who has access to a specific item type at a given time, as well as who has 

responsibility for approving the advancement of the state. 77 

super administrator For MKS Integrity, the person who sets up and configures 

MKS Integrity is referred to as the super administrator. The super administrator can also 

delegate certain tasks related to projects for workflows and documents and types to a project 

administrator and type administrator. 74

The administrator installs and/or configures, workflows and documents; configuration 

management; and the MKS Integrity Server. For MKS Integrity, the administrator also 

installs the database on a network, defines and customizes item types and workflow, and 

creates additional user accounts, allowing users to access the program. 4 

The CLI is a program that allows a user to enter keywords as instructions to a computer or 

device to perform specific tasks. (The MS-DOS® command prompt is an example of a CLI.) 

Results are typically output as simple text to the user’s terminal. More specifically, the CLI 

provides the means for you to enter MKS commands through a text-based interface. The 

primary use of the CLI is for scripting. The CLI is also useful for environments where no GUI 

is available. 42 

To drop a configuration management project means that the project is no longer registered 

with the MKS Integrity Server. Dropped projects can still be accessed as read only from the 

Change Package and Locks views until the project is purged or reclaimed by your 

administrator. 272 

type administrator MKS Integrity type administrators are allowed to edit and view types. 

Type administrators are not allowed to assign themselves as administrators to any other 

types, or to edit types that are assigned to other type administrators. 95 

Workflow and document reports are summaries of the data in your project. Reports are 

based on the standard and custom fields of types. Reports can be customized to include 

images, fonts, and hyperlinks, and can be saved as HTML files for viewing on the Web. 

Configuration management reports provide an analysis of projects, members, or individual 

archives. Reports and graphs can be printed or viewed on screen. 221 

workflow Each item follows a workflow, the process established by your administrator to 

capture and track information during your software development cycle. Each item type can 

have its own set of states to advance through the development cycle. For example, a change 

request may go through states such as submitted, work started, tested, reviewed, and closed. 

Items and their current states provide change management information necessary to support 

business decisions. 153 

435


436

A PPENDIX C 

Options 

Views and Dialog Boxes 

This appendix includes detailed information about the available options in 

MKS Integrity Administration Client views and dialog boxes. 

Workflows and Documents View Options 

Available Views Options 

View Item Display history shows the item history when viewing a single item. 

Display relationships shows the relationships when viewing a single item. 

C 

Display change packages shows associated change packages when viewing a single 

item. 

Display workflow shows the item type workflow when viewing a single item. 

Display attachments shows attachments when viewing a single item. 

Display time entries shows time entries when viewing a single item. 

History Order shows item history in ascending or descending order. Available options 

are: Most recent last and Most recent first. 

Display all attachment attributes shows all attachment attributes when viewing a 

single item. 

View Queries Created By shows the name of the user who created the query. 

Image shows any image, whether default or custom, associated with a query. 

Name shows the name of the query. 

Sort Field shows the field the query is sorted by. 

Description shows any information entered for the query description. 

Admin Provided shows whether or not the query is a shared administrative object. 

Shared With shows which groups and users the query is shared to. 

Fields shows the visible fields in the query. 

Last Modified shows the date the query was last modified. 

Sort Direction shows the direction the query is sorted by. 

The Toolbar allows you to customize the toolbar displayed on the interface when 

viewing users. For general procedures on customizing toolbars, see the MKS Integrity 

2009 Getting Started Guide. 

437

Appendix C: Options 


View Reports Created By shows the name of the user who created the report. 

438 

Last Modified shows the date the report was last modified. 

Shared With shows which groups and users the report is shared to. 

Description shows any information entered for the report description. 

Name shows the name of the report. 

Admin Provided shows whether or not the report is a shared administrative object. 

Query shows the query the report is based on. 




View Charts Chart Type shows the type of chart (distribution, item fields, trend, or item fields trend). 

Graph Style shows the type of graph used to display the chart data. 

Name shows the name of the chart. 

Created By shows the name of the user who created the chart. 

Admin Provided shows whether or not the chart is a shared administrative object. 

Query shows the query the chart is based on. 

Description shows any information entered for the chart description. 

Last Modified shows the date the chart was last modified. 

Shared With shows which groups and users the chart is shared to. 




View Dashboards Created By shows the name of the user who created the dashboard. 

Last Modified shows the date the dashboard was last modified. 

Description shows any information entered for the dashboard description. 

Name shows the name of the dashboard. 

Admin Provided shows whether or not the dashboard is a shared administrative 

object. 

Shared With shows which groups and users the dashboard is shared to. 



2009 Getting Started Guide.


View Users Description provides a column to display any information entered for the user 

description. 

Image shows any image, whether default or custom, associated a user. 

Name displays the column showing the name of the user. 

Email displays e-mail address information for users. 

Is Active displays the column showing whether the user is assigned active or inactive 

status. 

Notification Rule displays notification rules for users. 

Full Name displays the column showing the full name of the user. 

Is in Realm displays whether the user exists in the realm. 




View Groups Description provides a column to display any information entered for the group 

description. 

Is Active displays the column showing whether the group is assigned active or inactive 

status. 

Email displays e-mail address information for groups. 

Name displays the column showing the name of the group. 

Image shows any image, whether default or custom, associated a group. 

Query Timeout displays the query timeout setting, if set, for groups. 


viewing groups. For general procedures on customizing toolbars, see the 

MKS Integrity 2009 Getting Started Guide. 

View Dynamic Groups Description provides a column to display any information entered for the dynamic 

group description. 

Image shows any image, whether default or custom, associated with a dynamic group. 

Name displays the column showing the name of the dynamic group. 


viewing dynamic groups. For general procedures on customizing toolbars, see the 


View Projects Backing Item displays the ID of the item backing the project. 

Is Active displays whether or not the project is displayed in filtered project lists. 

Closed Image displays the image for closed projects. 

Name displays the column showing the name of the project. 

Description provides a column to display any information entered for the project 

description. 

Open Image displays the image for open projects. 

The Toolbar button allows you to customize the toolbar displayed on the interface 

when viewing projects. For general procedures on customizing toolbars, see the 


439



View Item States Description provides a column to display any information entered for the state 

description. 

Position displays the column showing the sequence of the state relative to other 

states. 

Image shows any image, whether default or custom, associated with a state. 

Name displays the column showing the name of the item state. 


when viewing states. For general procedures on customizing toolbars, see the 


440


View Item Types Name displays the column showing the name of the item type. 

Attributes 

Show Workflow indicates whether the item type displays the workflow in items. 

Phase Field indicates the workflow phase field for the item. 

Time Tracking indicates whether the item type allows time tracking. 

Backs Project indicates whether the item type is used to back a project. 

Copy Tree indicates whether items of this type and all related items within the 

hierarchy to be copied. 

Branch indicates that items of this type can be branched by users who have 

applicable project visibility based on the branching rules set up for item types. 

Label indicates whether the items of this type can have labels applied. 

Delete Item indicates whether a type rule exists that specifies which users can 

delete items of the type. 

Image shows any image, whether default or custom, associated with an item type. 

Description provides a column to display any information entered for the type 

description. 

Change Packages indicates whether the item type can be associated with change 

packages. 

Document Model 

Document Class indicates the document class on a type: None, Segment, Node, 

Shared Item. 

Associated Type displays the associated type for segments and nodes. If the 

document class is Segment, the associated type is Node. If it is Node, the type is 

Shared Item. 

Associated State indicates the initial state to apply when a document is branched. 

Significant Edit Fields indicates whether or not to display the fields that are 

defined as significant; that is, that when they are changed, it results in an update to 

the revision. 

Group Document indicates whether items of this type are used to group test cases 

for test execution. 

Default Reference Mode applies the default reference mode to the type you are 

defining. Reference modes are Author, Share, Reference and are typically used in a 

document sharing scenario. 

Test Management displays the test role and settings for items that are part of test 

management. 

Permissions displays the groups that are allowed access to this type. 

Position displays the column showing the sequence of the item type relative to other 

types. 

Copy Fields indicates which fields are to be copied when items of this type are 

copied. 


when viewing types. For general procedures on customizing toolbars, see the 


441



View Fields Allowed Types displays the types that the relationship fields can relate to. Valid only 

for fields of type relationship. 

Allowed Types are uneditable for the following relationship fields: Contains, 

Contained By, Referenced By, Shares, and Shared By. 

442 

The only Allowed Types on the References relationship field are those of type 

Segment. 

Display Location shows the display location of the field. Can be either the fields or 

relationship tab. Relevant only for fields of type relationship. 

Forward specifies whether the relationship field allows forward relationships. If 

cleared, it specifies a backward relationship field. Relevant only for fields of type 

relationship. 

Name displays the column showing the name of the field. 

Relationship Flags displays any relationship flags associated with the field. Only 

relevant for relationship fields. 

Cycle Detection specifies whether the system prevents relationship loops. Relevant 

only for fields of type relationship. 

Display Name shows the display name of the field, if any is assigned. 

Is Multi-Valued displays the column showing whether the field allows multiple values. 

Valid for pick, user, group, and relationship fields. 

Paired Field is the related backward/forward relationship field. Relevant only for fields 

of type relationship. 

Trace specifies whether the field is defined as a trace relationship. 

Description provides a column to display any information entered for the field 

description. 

Display Style shows the display style (table or CSV) of the field. Relevant only for fields 

of type relationship. 

Last Evaluation Time allows you to view the last time the static computed field (if 

enabled as this type of field) was computed. 

Position displays the column showing the sequence of the field relative to other fields. 

Type displays the type of field (for example, integer, pick, or long text, etc.). 


when viewing fields. For general procedures on customizing toolbars, see the 


For more information on options, see “Creating Fields” on page 127.


View Server Triggers Assignments displays the column showing values assigned to specific fields when the 

trigger runs. 

Last Run Time allows you to view the last time the trigger was run. 

Position displays the column showing the sequence of the trigger relative to other 

triggers. 

Run As displays the column showing . 

Type displays the column showing the type of trigger (rule or scheduled). 

Attachment Fields: Values Tab 

Field Description 

Integer Fields: Values Tab 

Description provides a column to display any information entered for the trigger 

description. 

Name displays the column showing the name assigned to the trigger. 

Query displays the column showing the name of the query used in the trigger. 

Script displays the column showing the name of the script used in the trigger. 

Frequency displays the column showing the frequency at which the trigger runs. 

Parameters displays the column showing parameters assigned to the trigger. 

Rule Timing displays the column showing the timing of the trigger. 


when viewing triggers. For general procedures on customizing toolbars, see the 


Display Style Display the attachment field in table format or comma separated values (CSV) forma. 

Table format allows you to sort the attachments and manipulate the columns that 

display in the table. CSV format displays comma separated links to the attachments. 

Display Rows The number of rows to display for the attachment field when editing the item. 


Set Default Value Default value (maximum of 9 digits) 

Set Minimum Value Minimum value (maximum of 9 digits) 

Set Maximum Value Maximum value (maximum of 9 digits) 

Display as Progress Bar Show the field’s current value graphically as a proportion of its maximum value 

Computation Values Configure the field as a computed field. For information on configuring the 

Computation Definition, Store to History Frequency, and How to Run Computations 

fields, see “Creating Computed Fields” on page 313. 

Note: Setting the Computation Values option disables the Set Default Value, Set 

Minimum Value, and Set Maximum Value options. 

Display Pattern Select or type a pattern to assign a format to integer field values. For more information 

on, see “Display Patterns” on page 28. 

443


444 

Item Backed Picklist Fields: Values Tab 


Display As Link Displays the value selected in the IBPL as a hyperlink to the backing item. 

Allow Multiple 

Values 

Allow users to select more than one item in the IBPL field. 

Backing Type Item type containing the short text field you want to reference 

Item Identifier The field or fields in the backing item type that you want to use as pick text. 

For a single field, select the field name from the dropdown list and click Insert Field to add it to 

the Item Identifier field. 

For multiple fields, type the field names in the Item Identifier field, surrounding each with "{" and 

"}". For example: {ID}:{Project}/{Summary}. Make sure you specify actual names of 

fields not their display names. 

You cannot specify the following types of field: 

computed fields 

field value attribute 

item backed picklist fields 

relationship fields 

attachment fields 

Active States States used to populate the IBPL with backing items. Populating an IBPL with backing items in 

specific states essentially allows you to deactivate entries in an IBPL. For example, if an 

Employee item contains an Active and Inactive state, and you select Active as the Active 

States, only Employee items in a state of Active display as pick text in the IBPL field. 

Filter Filter values from the backing items based on specific criteria. The filter is defined the same way 

as a query filter. For information on how to define a filter, see the MKS Integrity 2009 User Guide. 

Note: This filter is applied in addition to the filtering provided by the Backing Type and Active 

States options. 

Field Value Attribute Fields: Values Tab 


Relationship The field containing the backing item for the FVA field. This field can be any of the 

following: 

a relationship field (must be single-valued) 

an item backed pick list field 

the project field (if backing projects are enabled for the item type) 

Field The field in the backing item type that contains the value to display in the FVA field. 

The field must be visible in the backing item. 

Note: Do not select a relationship field. Use of relationship fields for FVA fields is not 

supported.

Pick Fields: Values Tab 


Allow Multiple Values Allow users to select more than one value from the picklist. For example, if three 

company offices are defined in MKS Integrity, users could select one, two, or all three 

offices when submitting an item or creating a query. 

Set Default Value Type the default value for the pick field. The default value can be any text string. 

Add Add picklist values. See “Add Pick Dialog Options” on page 445. 

Edit Edit the selected picklist value. 

Move Up 

Move Down 

Add Pick Dialog Options 

Change the order of the selected picklist value in the list. 

Sort Alphabetically Sort the picklist values by alphabetical label. 

Remove Remove selected picklist value(s) from the list that have not yet been saved. 


Label Text string for the picklist value. 

Value Number for the picklist value. 

Active Make picklist value active. By default, picklist values are active. To deactivate the 

picklist value, clear the Active check box. For more information on deactivating picklist 

values, see “Deactivating Picklist Values” on page 141. 

Use Custom Image Browse for the image file. If you choose to use your own custom icon image, the image 

must be in GIF or JPEG format, and no larger than 24 (width) by 16 (height) pixels. 

No Image No image associated with the value. 

Floating Point Fields: Values Tab 


Set Default Value 

Set Minimum Value 

Set Maximum Value 

Set the default, minimum, or maximum value. You can enter a negative exponent using 

the E number notation, for example, -123.1E-3. 

Specify a maximum of 15 digits. When edited in the Web interface only 12 digits are 

simultaneously visible. 

Computation Values Configure as a computed field. For information on configuring the Computation 

Definition, Store to History Frequency, and How to Run Computations fields, see 

“Creating Computed Fields” on page 313. 

Note: Setting the Computation Values option disables the Set Default Value, Set 

Minimum Value, and Set Maximum Value options. 

Display Pattern Select or type a display pattern to assign a format to floating point field values. For 

more information on, see “Display Patterns” on page 28. 

445


446 

Logical Data Fields: Values Tab 


Set Default Value true or false 




Note: Setting the Computation Values option disables the Set Default Value options. 

Date Fields: Values Tab 


Include time Include the time with the date. Time is specified from 00:00:00 to 23:59:59 

inclusive in 24 hour format; however, MKS Integrity displays the time in 12 hour format. 

For example, specifying 13:56:45 displays the time as 1:56:45 PM. 

Important: 

Once you include the time and save the date field, you cannot change the date field 

to display the date only. 

Displayed date fields do not change based on the time zone that a user is operating 

in; however, displayed date/time fields vary based on the time zone that a user is 

operating in. 

Set Default Value 

Set MInimum Value 

Set Maximum Value 

Specify default, minimum, and maximum values, by selecting one or more of these 

options and clicking Change 




Note: Selecting the Computation Values option disables the Set Default Value, Set 

Minimum Value, and Set Maximum Value options.

Short Text Fields: Values Tab 


Set Default Value Type a default value 

Maximum Length Maximum length for the field. Note the following: 

Decreasing the value does not truncate existing data nor affect how data is 

displayed in the Items view. 

When editing an item with a field containing legacy data that exceeds the new 

maximum value, submitting the item is unaffected if the affected field contents are 

unaltered by the user. 

When editing legacy field data that exceeds the new maximum value, the user is 

bound by the new maximum value and must reduce the data in order to submit the 

item. 

If logging is enabled for the field prior to reducing the maximum value, the logging 

field effectively becomes read-only. 

Caution: Increasing the maximum number of characters for a field contributes to the 

portion of the maximum row width used in the database table. Ensure that the changes 

you make are sustainable for future table data in your database. For more information, 

consult the documentation provided by the vendor for the database used. 

This value is used for both the MKS Integrity Client and Web interface. However, 

when the user edits a field in the Web interface, only 70 characters are 

simultaneously visible in the editable box. 

Suggestions Suggestions are text that appear in the short text field and can be overwritten by the 

user. Use the buttons on the right side of the field to work with suggestions. 

Substitute Parameters If a user specifies a parameter in this field using the following format {{}}, then this parameter name is replaced with a parameter value when you view 

the item through a view or report that supports parameter substitution. 




Note: Selecting the Computation Values option disables the Set Default Value option. 

Create a Text Search Index Queries against the field are treated as word searches. The field is searched by the 

All Fields text search query. 

447


448 

Long Text Fields: Values Tab 

When viewing a parameter or parameter value field, all the fields on the Values tab are 

hidden except for Maximum Length, Display Rows and Create a Text Search Index. 


Set Default Value Type a default value. 

Note: If you enable the Rich Content option, a toolbar displays, allowing you to apply 

rich content. For more information on applying rich content, see the MKS Integrity 

2007 User Guide. 

Maximum Length Enter a maximum length for the field. Note the following: 

Decreasing the value does not truncate existing data nor affect how data is 

displayed in the Items view. 

When editing an item with a field containing legacy data that exceeds the new 

maximum value, submitting the item is unaffected if the affected field contents are 

unaltered by the user. 

When editing legacy field data that exceeds the new maximum value, the user is 

bound by the new maximum value and must reduce the data in order to submit the 

item. 

If logging is enabled for the field prior to reducing the maximum value, the logging 

field effectively becomes read-only. 

When you set the maximum field length for long text fields that are configured for 

rich text, keep in mind that some symbols, especially those used outside the USA, 

may require multiple characters worth of storage for their representation. Use the 

maximum field length as a general guideline rather than as an absolute number. 

Caution: Increasing the maximum number of characters for a field contributes to the 

portion of the maximum row width used in the database table. Ensure that the changes 

you make are sustainable for future table data in your database. For more information, 

consult the documentation provided by the vendor for the database used. 

Display Rows Number of rows to display in the Item Details. The maximum is 80 rows. 

Logging Specify if the field logs user entries. Logging text fields limit the user to making new 

entries in the field and, therefore, do not permit the user to edit data that was entered 

previous to the last time the item was saved. 

Each time the user saves an item after making an entry in a logging text field, the user 

ID, entry date, and entry time are logged and then displayed as a stamp above the 

entry. The stamp uses approximately 30 characters per entry and must be taken into 

account when setting the maximum field length. 

The following are the available options : 

None specifies that the field is not a logging field. 

Most Recent First specifies that the order of the data in the log is always 

ascending with the user’s editable area located above the log. 

Most Recent Last specifies that the order of the data in the log is always 

descending with the user’s editable area located below the log.


Rich Content Configure field as a rich content field. Rich content enhances the display of text in long 

text fields by adding formatted text, tables, background colors, images, and hyperlinks. 

This option is enabled by default and does not support logging text fields. 

User Fields: Values Tab 

Caution: You can convert rich content fields back to long text fields; however, any 

existing rich content is displayed as HTML tags and attributes. 

Because rich content is expressed using a limited set of HTML elements and 

attributes, you can define screen and printer Cascading Style Sheets (CSS) that 

ensure a consistent look when viewing and printing rich content field data in different 

Web browsers. For more information, see “Customizing Rich Content Fields” on 

page 216. 

Default Attachment Field The field that images are retrieved from in the item when images are inserted into a 

rich content field using an attachment field. The default is the default Attachment field. 

Substitute Parameters If a user specifies a parameter in this field using the following format {{}}, then this parameter name is replaced with a parameter value when you view 

the item through a view or report that supports parameter substitution. 

Create a Text Seach Index Queries against the field will be treated as word searches. The field will be searched 

by the All Fields text search query. 


Allow Multiple Values Allow multiple users to be selected in the user list. Allowing multiple values for a user 

field facilitates group development. For example, if you allowed multiple values for the 

Assigned User field, you could assign multiple users to an item, enabling them to work 

in parallel on the same item. 

Set Default Value Click the list, and select a default user from the selection panel that displays. If the field 

allows multiple values, you can select multiple default values. For information on 

selecting users, see “Filtering Data” on page 18. 

Note: If you change a multi-valued field to a single-valued field and multiple default 

values are selected, all selections are cleared except the first selection in the list. 

Note: The symbolic -me- is not available for custom user fields. 

449


450 

Group Fields: Values Tab 


Allow Multiple Values Allow multiple groups to be selected in the group list. Allowing multiple values for a 

group field facilitates group development. For example, if you allowed multiple values 

for the Assigned Group field, you could assign multiple groups to an item, enabling 

them to work in parallel on the same item. 

Set Default Value Click the list, and select a group from the selection panel that displays. If the field 

allows multiple values, you can select multiple default values. For information on 

selecting users, see “Filtering Data” on page 18. 

Note: If you change a multi-valued field to a single-valued field and multiple default 

values are selected, all selections are cleared except the first selection in the list. 

Note: The symbolic -me- is not available for custom user fields. 

Relationship Fields: Values Tab 


Types Item type that is to use the relationship field 

Allowed Types Item types that can be linked to using the relationship field. 

For example, to allow the field to be used to create relationships between 

documentation items and bugs, select Docs under Available Types and add Bugs to 

the Allowed Types. Then select Bugs under AvailableTypes, and add Docs to the 

Allowed Types. 

Allowed Types are uneditable for the following fields: Contains, Contained By, 

Referenced By, Shares, and Shared By. 

Repeat the selection process for additional item types. 

Note: You can create heterogeneous and homogenous segments using allowed types. 

To learn how to create homogeneous subsegments, see “Setting Up Documents” on 

page 97. 

To learn how to create heterogeneous subsegments, see the ALM Knowledge Base. 

Cycle Detection To prevent relationship loops from occurring. A relationship loop occurs when an item 

has both a forward and a backward relationship with another item within the same 

relationship hierarchy. For more information, see the MKS Integrity 2009 User Guide. 

Trace Sets the field as a trace relationship.Trace relationships are defined via field pairs are 

and presented to the user in domain-specific language, for example, Test and 

Requirements. To learn more about trace relationships, see the MKS Integrity 2009 


Forward and Backward 

tabs 

The fields used for forward and backward relationships. 

For example, if you are defining a relationship field to track defects related to an item, 

the forward relationship field could be named Defects and the backward relationship 

field could be named Defects Of. 

Name Name of the relationship field. The name you enter is also used for the backward 

relationship field and prefixed with the word Backward. You can edit this name. 

Note: Once the field is created, changes to the name of the forward relationship field 

are not carried over to the backward relationship field name.


Multi Valued Allow links to multiple items. For example, a field used to track defects on an item 

would need to allow multiple linked items; a field used to identify the documentation 

item used for documenting the changes made by a change order item would only need 

to allow a single linked item. 

Note: If you want a single-valued relationship field to be able to be changed using 

drag-and-drop in the Relationships view, you must make it visible on the appropriate 

item types. For example, if you have Documented By and Documentation For as a set 

of relationship fields, and the Documented By field is single-valued, if you want users 

to be able to change the related documentation item for a change order item using 

drag-and-drop, the Documented By field must be visible on the change order item 

type. 

Set Default Browse Query Sets a default query to use when browsing for items to add to the relationship field. 

Use the data filter to select an Admin query as the default browse query. If there are no 

Admin queries, this option is unavailable. For more information on creating Admin 

queries, see “Admin Provided Objects” on page 242. 

Display Style Display the relationship field in table format or in a comma separated values (CSV) 

format. The table format allows you to sort the linked items and manipulate the 

columns that display in the table. The CSV format only displays the IDs and 

relationship flags of the linked items. 

Display Rows Number of rows to display for the relationship field when editing the item. 

Show Variable Height 

Rows 

Variable height rows allow you to view rows expanded to the height of the data 

contained in them. 

Relationship Flags Relationship flags are used to indicate when a related item has changed. To add 

relationship flags for the field click Add. For more information, see “Add Relationship 

Flag Dialog Box Options” on page 451. 

Notes: 

A user must be licensed for configuration management to be able to use relationship 

flags in an item. 

Relationship flags defined for relationship fields can be set automatically through a 

field rule. For more information on defining rules for fields, see “Setting Field Rules” 

on page 137. 

Add Relationship Flag Dialog Box Options 


Name Name of the relationship flag 

Character Single character to display when the flag is set on a relationship field using the CSV 

display style or when the relationship is viewed through the CLI. You cannot use 

numbers as relationship flag characters. 

Select Locate the image you want to use for this type of relationship flag in a relationship field 

using a table format. The image must be in a JPEG or GIF format and no larger than 

24 by 16 pixels. 

451



Suspect Allows you to define a suspect flag for items at the field level. When a there is a 

significant edit to a document item with a field pointing to it that is flagged as suspect, 

all related items using that field will be flagged as suspect. 

Enabled You are using this relationship flag 

452 

Phase Fields: Values Tab 


Add Add a phase to the Phases list. See “Add Phase Dialog Box Options” on page 452. 

Edit Edit the phase selected in the Phases list. 

Move Up 

Move Down 

Remove 

Remove All 

Note: You cannot edit the Out of Phase phase. This phase identifies the states that 

are not included in any user defined phase. 

Change the order of a selected phase in the list 

Remove one or more selected phases from the list, or remove all phases 

Add Phase Dialog Box Options 


Label Assign a text string to the phase 

Available States Select the states that are included in the phase, and add them to the Phase States. 

Note: No two phases can use the same state. 

Use Custom Image Assign an icon image to the phase. Browse for the image file. The image must be in 

GIF or JPEG format, and no larger than 24 (width) by 16 (height) pixels. 

No Image No image associated with the phase 

Query Backed Relationship Fields: Values Tab 


Query Select a query that determines what items are displayed in the field. Only administrator 

queries appear in the list. 

Field Correlation Correlate a field contained in the item with a field in the items returned by the query. 

This allows you to return even more specific query results. 

For example, if you create a query backed relationship field called Defects for the 

Feature type, and select Project as the Source Field and Project as the Target 

Field, the Defects field displays all Defect items that have the same project as the one 

specified in the Feature type’s Project field. 

This option is not mandatory; however, if it is not specified, the list of relationships 

returned does not change with different items.


Display Style Display the items in table format or in a comma separated values (CSV) format. The 

table format allows you to sort the items and manipulate the columns that display in the 

table. The CSV format only displays the IDs of the items. 

Display Rows The number of rows to display for the query backed relationship field when editing the 

item. You can specify from five to 80 rows. 

Show Variable Height 

Rows 

Range Fields: Values Tab 


Display variable height rows for the query backed relationship field when editing the 

item. 

Associated Field A numeric field to associate with the range field. 

You can associate a numeric field with any number of range fields. 

Add Add a range to the Ranges list. See “Add Range Dialog Box Options” on page 453. 

Move Up 

Move Down 

Remove 

Remove All 

Change the order of a selected range in the list. 

Remove one or more selected ranges from the list, or remove all ranges. 

Add Range Dialog Box Options 


Label Text string for the range category. Range labels can be up to 100 characters. 

Value Use the From and To lists to specify values for the lower and upper range limits. 

If a lower limit is not set, -Infinity is automatically entered in the From field. If an 

upper limit is not set, Infinity is automatically entered in the To field. 

A numeric value must be contained in one defined range; range intersections are 

invalid. For example, the following ranges are invalid: 0–5 and 4–8, or 0–5 and 5–10. 

For an integer field, an acceptable range would be 0–5 and 6–10. For a floating 

point field, an acceptable range would be 0–5 and 5.01–10. 

If a value is entered in the associated numeric field that is beyond the set range 

values, the range field displays Out of Range in the item. If no value is entered in 

the associated numeric field, the range field is empty. 

Use Custom Image Assign an icon image to the range. Browse for the image file. The image must be in 

GIF or JPEG format, and no larger than 24 (width) by 16 (height) pixels. 

No Image No image associated with the range 

453


454

Index 

A 

access keys 

MKS Integrity Administration Client 17 

admin migration 

copying database 168 

e-mail notification 167 

managing admin locks 169 

staging server startup 168 

testing configuration 169 

using admin locks 171 

wizard 161–177 

using 171 

admin provided object 

converting to 243 

admin provided objects, described 242 


application window 13 

command line interface 42 

connecting to an Integrity Server 29 

disconnecting from an Integrity Server 31 

opening the interface 10 

preferences 

setting 38 

shutting down the interface 12 

workflows and documents 

Change Package Types view 325 

Fields view 125 

Projects view 249 

States view 77 

Types view 83 

administrator 

assigning 74–77 

described 4 


project 74, 260 

super 74 

type 94 

project 

assigning 262 

super 4 

role 6 

super, described 74 

type 

assigning 96 

aggregated function 

described 297 

aggregation expression 

described 293 

alert messages 32 

allow 

branching 89 

labels 90 

project backing 89 

time entries 88 

arithmetic function 

described 297 

arithmetic operators 

computed expression 293 

assessing process 70 

attachment data type 

described 127 

attachment size 

configuring in MKS Integrity 237 

Authorization Administration 

preferences, setting 41 

B 

boolean operators 


branching 

enabling 89 

building block 


deleting 179 

C 

calculate 

computed field 

dynamic 314 

static 315 

state metrics 319 

capabilities, state-based 79, 119 

455

Index 

categories 

defining 101 

cell properties, default 195 

change package 

allowing 79, 80, 85, 119 

described 324, 343 

review process 

how it works 345 

type 324 

customizing 327 

viewing 330 

Change Package Types view 


Administration Client 325 

changing 

configuration management event trigger 

resolution order 381 

order of states 81 

character sets 

controlling 181 

chart 

described 238 

historical trends using computed fields 

316 

checkmark, tab 210 

choose 

groups 22 

principals 22 

users 22 

workflow and document projects 22 

client 

Administration 10 

Administration window 13 

logging 

HTTP messages 409 

client-side 

event triggers, configuration management 

383 

environment variables 387 

closing 

client 11 

collecting 

properties and log files 421 

command 

im logging 412 

si createproject 266 

si dropproject 271 

si import 270 

si importproject 268 

si logging 410 

command line interface 


456 

described 42 

common project 

potential problems 290 

components 

configuration management event trigger 

382 

subproject 282 

computed expression 

described 291 

function classes 296 

group fields 296 

rules 293 

types 292 

user fields 296 

computed field 

charting historical trends 316 

computation times 

scheduling 318 

creating 313 

performance 321 

scalability 321 

security 321 

state metrics 

calculating 319 

static 

calculating 315 

conditions 

defining 43 

configuration management 265 

change package 

allowing 79, 80, 85, 119 

client-side triggers 

environment variables 387 

event 375 

event trigger 350–399 

client-side 383 

member event 375 

planning 389, 390 

post-test 380 

pre-test 380 

project context 380 

project event 376 

properties file 382 

revision event 376 

sequence of operations 379 

server event 376, 377 


type 380 

writing 383 

events definition file 382 

global event trigger 380 

project 265–271

eporting 

troubleshooting 430 


configuring 

attachment size 237 

preferences 34 

query limit 

group timeout 239 

maximum item count 239 

query limit, workflows and documents 

238 


text searching, workflows and documents 

240 

connecting 

to an Integrity Server 29 

content 

customizing in a document 101 

meaningful and non-meaningful 101 

context based text search 

workflows and documents 240 

converting 

user objects to admin provided 243 

copy 

item tree 89 

copying 

event triggers 


item presentation template 214 

type 92 

create 

computed field 313 

state metrics 319 

creating 

a support package 421 

event triggers 


field 127 

field relationships 146 


project 252 

using CLI 266 

state 78 

type 84 

workflow 155 

custom reports 


images 221 

report tags 222 

template files 221 

customize 

rich content fields 216 

customizing item presentation 188 

cells 205 

designer 189 

grids 204 

images 212 

labels 206 

logos 212 

previewing 197 

properties 191 

default cell 195 

default grid 195 

default text style 194 

general 192 

text style 193 

setting template 201 

D 

dashboard 

described 6 

data 

filtering 18 

searching 18 

data conversion 


data type 

attachment 

described 127 

date 

described 127 

field value attribute 

described 127 

floating point 

described 127 

group 

described 127 

integer 

described 127 

item backed picklist 

described 127 

logical 

described 127 

long text 

described 127 

phase 

described 128 

pick 

described 127 

query backed relationship 

described 128 

range 

Index 

457

Index 

described 128 

short text 

described 127 

SI project 

described 131 

user 

described 127 

database 

copying for admin migration 168 

date data type 

described 127 

date operations 


day/time function 

described 297 

deactivating 

pick list values 141 

project 259 

test verdicts 237 

default cell properties 195 

default grid properties 195 

default text style properties 194 

defining logical conditions 43 

deleting 

building block 179 

field 142 


item 179 


project 257 

state 81 

type 94 

designing 

custom presentation template 188 

project 289–290 


diagnostics 

client logging level 408 

differencing files 406 

environment information 402 

FLEXnet logs 413 

IDE log 413 

log files 406 


running 414 

running server as application 405 

dialog box 

option prompts 35 

directory tree 263 

hierarchical structures 264 

disconnecting 

from an Integrity Server 31 

458 

from server 11 

display 

type workflow 88 

display pane 

graphical user interface 16 

display pattern 28 

document domain 

create all three types 104 

creating 97 

document model 

high-level set up 103 

documents 

checklist for setting up 103 

content 101 

create domain 103 

creating pre-condition rules 46 

field relationships 

edit references field 110 

function classes 297 

print 

define report 111 

print format 111 

relationships 

relationships 

in document model 100 

set up tasks 103 

setting up 97 

terms and concepts 98 

triggers 

location for use cases 365 

understanding structure 98 

domain 

documents 

create 103 

Dr. Watson logs 413 

drop project, described 270 

E 

editing 

field 140 



project 256 

state 80 

type 91 

electronic signatures 241 

customizing triggers 241 

e-mail 

controlling character sets 181 

notification 5

permission 181 

notification of admin lock break 167 

empty fields 


enable 

branching 89 

labels for items 90 

project backing 89 

time entries 88 

encrypted archives 267 

environment information, for diagnostics 402 

environment variables 

configuration management triggers 387 

event 


event trigger 


configuration management 350–399 

changing resolution order 381 


components 382 

event definition files 382 

event trigger scripts 382 

global context 380 

planning 389, 390 

post-test 380 

pre-test 380 

project context 380 

project event 376 

properties file 382 

revision event 376 

scripts 382 

sequence of operations 379 

server event 376, 377 


type 380 

updating global events definition 

template 383 

writing 383 

described 349 

member event 375 


post-event 350 

pre-event 350 

workflows and document 

copying 371 


assigning field values 367 

creating 363 

creating rule based change trigger 

363 

creating scheduled trigger 367 

creating time entry trigger 370 

defining rule based change trigger 

365 

deleting 373 

disable scheduled 369 

editing 372 

how to use 356 

managing 362 

planning 358 

pre-created scripts 359 

resolution order 373 

rule based event 356 

running a scheduled trigger 371 

schedule event 356 

schedule frequency 369 

schedule query 369 

schedule running using CLI 369 

schedule running using GUI 372 

script library 358 

selecting scripts 366 

time entry event 356 

viewing 372 

external information function 

described 297 

F 

favorites 

selecting 27 

field 

computed 

creating 313 

creating 127 

deleting 142 

editing 140 

managing 121 

moving 143 

pick, multiple values 445 

rich content 


setting field relevance 133 

shared category 

edit pick list 110 

viewing 141 

visibility 120 

field relationships 

creating 146 

default columns 133 

deleting 152 

editing 151 

managing 143 

Index 

459

Index 

field value attribute data type 

described 127 

Fields view 



file 

importing 268 

importing using CLI 269, 270 

filter 

data 18 

groups 22 

principals 22 

users 22 


finding 

properties and log files 421 

FLEXlm 

log files 413 

floating point data type 

described 127 

format 

numeric values 28 

function 

aggregate 

described 297 

arithmetic 

described 297 

day/time 

described 297 

external information 

described 297 

text 

described 297 

function classes 


FVA field 

described 127 

G 

general 

template properties 192 

graphical user interface 

described 10 

display pane 16 

menu bar 13 

shortcut menu 14 

status bar 16 

title bar 13 

toolbars 14 

tooltips 17 

460 

tree pane 14 

workspace 17 

grid properties, default 195 

group 

deleting 179 

project permission 250 

selecting 22 

group data type 

described 127 

group fields 


H 

hide 

data 18 

I 

IBPL field 

described 127 

im diag 

command 417 

im logging command 412 

im recomputehistory command 316 

image, saving workflow 161 

images for reports 221 

importing 

files 268 

project 

using CLI 268 

viewset 50 

integer data type 

described 127 

Integrity Client 

logging level 408 

logs 407 

preferences 

setting 35 

version number 403 

Integrity Server 

connecting to 29 

disconnecting from 31 

logging levels 407 

version number 403 

intra-item expression 

described 292, 293 

is.properties file 

controlling character sets 181 

isutil 

command 424

item 

copying tree 89 

copying tree hierarchy 89 

deleting 179 

linking with a project 257 

item backed picklist data type 

described 127 

item presentation template 188, 189 

cells 205 

copying 214 

creating 198 

deleting 215 

editing 203 

grids 204 

images 212 

labels 206 

logos 212 



default cell 195 


default text style 194 

general 192 


setting 201 

tabs 209 

viewing 214 

K 

kerberos 

troubleshooting 428 

L 

labels 

enabling 90 

launching 

the Administration Client 10 

limit 

query 



lock 

managing admin 169 

using admin 171 

log files 

collecting 421 

Dr. Watson 413 

FLEXnet server 413 

for diagnostics 406 

integrations 413 

Integrity Client 407 

logging 


HTTP messages 409 

levels 


Integrity Server 407 


logging on 


logical conditions 

defining 43 

logical data type 

described 127 

logo 

adding to custom template 212 

long text data type 

described 127 

long text fields 


M 

managing 

field 121 

creating 127 

editing 140 

moving 143 

viewing 141 


pick list values 

deactivating 141 

project 248 

creating 252 


deleting 257 

editing 256 

moving 257 

reparenting 257 

viewing 256 

project metadata 257 

state 77–81 

creating 78 

deleting 81 

editing 80 

metrics 82 

moving 81 

viewing 80 

type 82 

copying 92 

Index 

461

Index 

creating 84 

deleting 94 

editing 91 

moving 94 

repositioning 94 

viewing 93 

maximum item count, query timeout 239 

meaningful 

marking content as 110 

meaningful content 

non-meaningful content 101 

member 

event 


importing 268 

importing using CLI 270 

importing using GUI 269 

menu bar 


messages 

HTTP-related 409 

server 32 

metrics 

state 82 

creating 319 

tracking for projects 280 

migrate 

shared field 177 

state override 177 



event trigger 

described 349 

post-event 350 

pre-event 350 

printing views 31 

project administrator 74, 260 

setting up 4–8 

super administrator 74 

understanding 4–8 

using 4–8 

workflow 5 


access keys 17 

ACLs 41 

shortcut keys 17 


diagnostics 

running 414 

serial number 402 

mksis 

command 423 

462 

monitor 

MKS Integrity Server 414 

moving 

field 143 

project 257 

state 81 

type 94 

multiple servers 

configuring 37 

multiple value 

pick field 445 

N 

node 

type 

create 106 

non-meaningful 

marking content as 110 

notification 

e-mail 5 


numeric values 

formatting 28 

O 

opening the Administration Client 10 

logging on 10 

organizing projects 263 

P 

performance 

computed fields 321 

permission 


phase data type 

described 128 

pick data type 

described 127 

pick field 

allowing multiple values 445 

pick list values 


planning configuration management event 

trigger 

performance 390 

pre- or post-event 389 

post-test configuration management event 

trigger 380

pre-conditions 

document 

use case location 149 

preferences 


setting 38 

Authorization Administration 

setting 41 

Integrity Client 

setting 35 

server 

setting 37 

setting 34 

toolbar 

setting 39 

presentation template 188 

cells 205 

copying 214 

creating 198, 203, 214, 215 

described 189 

designer 189 

grids 204 

images 212 

labels 206 

logos 212 




general 192, 194, 195 


setting 201 

tabs 209 

presentation templates 

reports 219 

pre-test configuration management event 

trigger 380 

principal 

selecting 22 

printing 

MKS Integrity views 31 

workflow 160 

process 

assessing 70 

production server 

installing and starting 166 

project 265–271, 280 

administrator 

assigning 262 

administrator, described 260 

administrator, MKS Integrity 260 

browsing configuration management 

projects 26 

common 289 

creating 252 


deleting 179, 257 

designing 289 

directory 263 

editing 256 

event 


linking with an item 257 

managing 248 

member 

sharing 287 

metadata 

managing 257 

moving 257 

organization 263 


reparenting 257 

restoring 

in CLI 273 

restoring to a previous checkpoint 271 

selecting configuration management 

projects 26 

selecting workflow and document 22 

sharing archive 287 

sharing member 287 

single directory 263 

viewing 256 

visibility 250 

project backing 

enabling 89 

Projects view 



prompts 

dialog boxes 35 

properties 

collecting 421 

proxy server 

preferences 

setting 37 

Q 

quantify 

numeric values 28 

query 

described 238 

limit 


Index 

463

Index 



query backed relationship data type 

described 128 

quick access keys 


access keys 17 

shortcut keys 17 

R 

range data type 

described 128 

RCS 

directory 264 

references field 

document types 110 

references, viewing 244 

relationship data type 

default columns 133 

relevance 133 

described 133 

reparenting 

project 257 

reports 219 

described 219 

document print format 111 

images 221 

tags 222 


repositioning 

type 94 

restoring project 

in CLI 273 

restoring project to a previous checkpoint 271 

result 

customizing test result 234 

review 

process 

change packages, how it works 345 

revision 

event 


rich content fields 


role 

super administrator 6 

rule selection 47 

rules 

computed expressions 293 

documents 

464 

S 

creating preconditions 46 

selecting 47 

saving workflow, as image 161 

scalability 


schedule 

computed field computations times 318 

script library 358, 359 

search 

data 18 

groups 22 

principals 22 

users 22 


searching 

context based 240 

secure sockets layer 7 

security 


realm 

debugging 409 

segment 

print format 111 

type 

create 108 

segments and nodes 

exposing to users 

FVA 

from shared item to nodes 100 

select 

favorites 27 

group 22 

user 22 


selecting 

rules 47 

serial number 

locating 402 

server 

disconnecting 11 

event 

configuration management 376, 377 

preferences, setting 37 

session 

closing client 11 

shutting down client 12 

setting 

administrators 74–77

preferences 34 

setting up 

MKS Integrity 4–8 

shared category field 

defining categories on 101 

shared field 

migrating 177 

shared item 

type 

create 105 

shared subproject 

adding 284 

sharing 

archive 

with other project 287 

member 287 

file ownership 288 

solution 289 

update/compatibility concerns 288 

short text data type 

described 127 

shortcut 

keys 


17 

menu 


show 

data 18 

shutting down 



si command 

createproject 266 

dropproject 271 

import 270 

importproject 268 

logging 410 

si diag 

command 417 

SI project data type 

described 131 

signatures 

electronic 241 

customizing triggers 241 

significant fields 

explained 102 

SSL 

See secure sockets layer 

staging server 

installing and starting 166 

starting 168 

starting 

the Administration Client 10 

the Integrity Server 

in Safemode 426 

using mksis 423 

state 

capabilities 79, 119 

creating 78 

deleting 81 

described 


edit workflow 160 

editing 80 

managing 77–81 

metrics 82 

moving 81 

transitions 

workflow 159 

viewing 80 

state metrics 

creating 319 

state override 

migrating 177 

States view 



status bar 



adding 283 

adding shared 284 

components 283 

configuring 286 

creating 283 

defined 282 

designing 289 

event triggers 381 

super administrator, described 74 

support package 

creating 421 

syntax 


system provided object 

references 244 

T 

tab 

checkmark 210 


tags, for reports 222 

Index 

465

Index 

template 

designer 

cells 205 

grids 204 

images 212 

images, logo 212 

labels 206 

files, for reports 221 

item presentation 

copying 214 

creating 198 

deleting 215 

designer 189 

editing 203 



tabs 209 

viewing 214 

test management 

types 

setting role for 112 

test result 


test verdict 

creating 235 


editing 236 

view 234 

test verdicts 


text fields 


text function 

described 297 

text searching 


text style properties 193 

time entry 

allowing 80, 119 

enabling 88 

timeout 

query 

group 239 


timestamps 


title bar 


toolbar 


preferences 

setting 39 

466 

tooltips 


tracking metrics for 280 

tree pane 


troubleshooting 

client logging level 408 

configuration management 

reporting 430 

differencing files 406 

environment information 402 

FLEXnet logs 413 

IDE log 413 

kerberos 428 

log files 406 

running server as application 405 

type 

administrator 

assigning 96 

described 94 

administrator, MKS Integrity 94 

branching 

enabling for type 89 

change package 324 


viewing 330 

copying 92 

creating 84 

deleting 94, 179 

editing 91 

field visibility 120 

labelling for items 90 

managing 82 

moving 94 

project backing 

enabling 89 

repositioning 94 

time entries 

enabling 88 

viewing 93 

workflow 

displaying 88 

type properties 

MKS Solution global type 103 

types 

document 

create 104 

edit field relationships 110 

node 

create 106 

segment 

create 108

shared item 

create 105 

test management 

setting role 112 

Types view 



U 

understanding MKS Integrity 4–8 

updating configuration management global 

events 

definition template 383 

user 

deleting 179 

described 4 

group 

project permission 250 

selecting 22 

user data type 

described 127 

user fields 


user objects 

converting to admin provided 243 

using MKS Integrity 4–8 

V 

variables 

environment 

client-side triggers 387 

verdict 

creating 235 

customizing test verdict 234 


editing 236 

version number 


Integrity Server 403 

view 

test verdict view 234 

viewing 

change package types 330 

field 141 


project 256 

state 80 

system provided object references 244 

type 93 

workflow 157 

views 

printing 31 

test verdict view 234 

viewset 

importing 50 

managing 50 

visibility 120, 250 

fields 120 

project 250 

W 

workflow 5, 153 

creating 155 

described 152 

edit 

state 160 

managing (editing) 158 

printing 161 

save as image 161 

state transitions 159 

type 

displaying 88 

view 153 

described 152 

viewing 157 

workflow migration 161–177 

coping database 168 


installing 

production server 166 

staging server 166 

managing admin locks 169 

shared fields 177 

staging server startup 168 

state overrides 177 

summary steps 164, 165 

testing configuration 169 

using admin locks 171 

using wizard 171 


admin provided objects 242 

attachment size 237 

custom reports 219 

images 221 

report tags 222 


event trigger 

assigning field values 367 

Index 

467

Index 

468 

creating rule based change trigger 

363 

creating scheduled trigger 367 

creating time entry trigger 370 

defining rule based change trigger 

365 

deleting 373 

disable scheduled 369 

editing 372 

how to use 356 

managing 362 

planning 358 

pre-created scripts 359 

resolution 373 

rule based event 356 

running a scheduled trigger 371 

schedule event 356 

schedule frequency 369 

schedule query 369 

schedule running using CLI 369 

schedule running using GUI 372 

script library 358 

selecting scripts 366 

time entry event 356 

viewing 372 

query limit 238 



states 

described 77 

time entry 

allowing 80, 119 

type administrator 94 

workflow migration 


summary steps 164, 165 

workspace 


writing configuration management event 

triggers 383

Product Notices 

Copyright © 2001–2009 MKS Software Inc.; in Canada copyright owned by MKS Inc. All rights reserved. 

U.S. Government Rights. The software and documentation (the 

“Software and Documentation”) are “commercial items” 

developed exclusively at private expense, consisting of 

“commercial computer software” and “commercial computer 

software documentation” as such terms are defined or used in the 

applicable U.S. acquisition regulations. If you are the U.S. 

Government or any agency or department thereof the Software 

and Documentation are licensed hereunder (i) only as a 

commercial item and (ii) with only those rights as are granted to 

all other end users pursuant to the terms and conditions of the 

Software License Agreement (“Agreement”) accompanying the 

Software. The Software or Documentation shall not be used, 

duplicated, or disclosed in any way not specifically permitted by 

the terms of the Agreement. Nothing in the Agreement requires 

MKS to produce or furnish technical data for or to the U.S. 

Government or any agency or department thereof. 

This product contains Qooxdoo version 0.7.4. This library is free 

software; you can redistribute it and/or modify it under the 

terms of the GNU Lesser General Public License as published by 

the Free Software Foundation; either version 2.1 of the License, or 

(at your option) any later version. Copyright © 1991, 1999 Free 

Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 

MA 02110-1301 USA. This library is distributed in the hope that it 

will be useful, but WITHOUT ANY WARRANTY; without even 

the implied warranty of MERCHANTABILITY or FITNESS FOR 

A PARTICULAR PURPOSE. See the GNU Lesser General Public 

License for more details. You should have received a copy of the 

GNU Lesser General Public License along with this library; if not, 

write to the Free Software Foundation, Inc., 51 Franklin Street, 

Fifth Floor, Boston, MA 02110-1301 USA. 

This product contains JSON-RPC JavaScript client software v. 1.0. 

Copyright (c) 2003-2004 Jan-Klaas Kollhof. Copyright (c) 2005 

Michael Clark, Metaparadigm Pte. Ltd. This code is based on Jan- 

Klaas’ JavaScript lait library (jsolait). Licensed under the Apache 

License, Version 2.0 (the “License”); you may not use this file 

except in compliance with the License. You may obtain a copy of 

the License at http://www.apache.org/licenses/LICENSE-2.0. 

Unless required by applicable law or agreed to in writing, 

software distributed under the License is distributed on an “AS 

IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF 

ANY KIND, either express or implied. See the License for the 

specific language governing permissions and limitations under 

the License. 

This product contains JIDE stock icons. Copyright (c) 2002-2008 

JIDE Software, Inc. All rights reserved. 

This product contains Apache Derby v. 10.3.3 software developed 

by The Apache Software Foundation (http://www.apache.org/). 

Copyright 2004-2008 The Apache Software Foundation. Licensed 

under the Apache License, Version 2.0 (the “License”); you may 

not use this file except in compliance with the License. You may 

obtain a copy of the License at http://www.apache.org/licenses/ 

LICENSE-2.0. Unless required by applicable law or agreed to in 

writing, software distributed under the License is distributed on 

an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS 

OF ANY KIND, either express or implied. See the License for the 


the License. 

Portions of Derby were originally developed by International 

Business Machines Corporation and are licensed to the Apache 

Software Foundation under the “Software Grant and Corporate 

Contribution License Agreement",informally known as the 

“Derby CLA”. The following copyright notice(s) were affixed to 

portions of the code with which this file is now or was at one time 

distributed and are placed here unaltered. (C) Copyright 

1997,2004 International Business Machines Corporation. All 

rights reserved. (C) Copyright IBM Corp. 2003. The portion of the 

functionTests under ‘nist’ was originally developed by the 

National Institute of Standards and Technology (NIST), an 

agency of the United States Department of Commerce, and 

adapted byInternational Business Machines Corporation in 

accordance with the NIST Software Acknowledgment and 

Redistribution document at http://www.itl.nist.gov/div897/ 

ctg/sql_form.htm. 

This product contains TreeTableModel.java, 

AbstractTreeTableModel.java, TreeTableModelAdapter.java, 

AbstractCellEditor.java and JTreeTable.java. Copyright 1997, 

1998 Sun Microsystems, Inc. All Rights Reserved. Redistribution 

and use in source and binary forms, with or without 

modification, are permitted provided that the following 

conditions are met: Redistributions of source code must retain the 

above copyright notice, this list of conditions and the following 

disclaimer. Redistribution in binary form must reproduce the 


disclaimer in the documentation and/or other materials provided 

with the distribution. Neither the name of Sun Microsystems, Inc. 

or the names of contributors may be used to endorse or promote 

products derived from this software without specific prior 

written permission. This software is provided “AS IS,” without a 

warranty of any kind. ALL EXPRESS OR IMPLIED 

CONDITIONS, REPRESENTATIONS AND WARRANTIES, 

INCLUDING ANY IMPLIED WARRANTY OF 

MERCHANTABILITY, FITNESS FOR A PARTICULAR 

PURPOSE OR NON-INFRINGEMENT, ARE HEREBY 

EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE 

LIABLE FOR ANY DAMAGES OR LIABILITIES SUFFERED BY 

LICENSEE AS A RESULT OF OR RELATING TO USE, 

MODIFICATION OR DISTRIBUTION OF THIS SOFTWARE OR 

ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS 

LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT 

OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, 

CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, 

HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF 

LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO 

USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF 

THE POSSIBILITY OF SUCH DAMAGES.You acknowledge that 

this software is not designed, licensed or intended for use in the 

design, construction, operation or maintenance of any nuclear 

facility. 

This product contains Xinha which is licensed under the 

htmlArea License (based on BSD license). Copyright (c) 2002- 

2004, interactivetools.com, inc. Copyright (c) 2003-2004 

dynarch.com. All rights reserved. Redistribution and use in 

source and binary forms, with or without modification, are 

permitted provided that the following conditions are met: 1) 

Redistributions of source code must retain the above copyright 

notice, this list of conditions and the following disclaimer. 2) 

Redistributions in binary form must reproduce the above 

copyright notice, this list of conditions and the following 


with the distribution. 3) Neither the name of interactivetools.com, 

inc. nor the names of its contributors may be used to endorse or 

promote products derived from this software without specific 

prior written permission. THIS SOFTWARE IS PROVIDED BY 

THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” 

AND ANY EXPRESS OR IMPLIED WARRANTIES, 

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 

PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 

SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 

LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 

SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 

(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 

SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 

PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 

IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT


OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 

POSSIBILITY OF SUCH DAMAGE. 

This product contains JGo software. Copyright (c) 1999-2004 

Northwoods Software Corporation. All rights reserved. 

This product contains NLog 1.0. Copyright (c) 2004-2006 Jaroslaw 

Kowalski (jaak@jkowalski.net). All rights reserved. 

Redistribution and use in source and binary forms, with or 

without modification, are permitted provided that the following 



disclaimer. Redistributions in binary form must reproduce the 



with the distribution. Neither the name of Jaroslaw Kowalski nor 

the names of its contributors may be used to endorse or promote 

products derived from this software without specific prior 

written permission. THIS SOFTWARE IS PROVIDED BY THE 

COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND 

ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT 

NOT LIMITED TO, THE IMPLIED WARRANTIES OF 

MERCHANTABILITY AND FITNESS FOR A PARTICULAR 

PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 

COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 

ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 

EXEMPLARY, OR CONSEQUENTIAL DAMAGES 






NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 



This product contains Runtime Modules of IBM(R) 32-bit (or 64bit) 

SDK for AIX(TM), Java(TM) Technology Edition, Version 6 

(c) Copyright Sun Microsystems Inc, 1992, 2008 

(c) Copyright IBM Corporation, 1998 - 2008 

(c) Copyright The Apache Software Foundation, 1999-2007 

All Rights Reserved. 

This product contains Apache Jakarta Commons HttpClient 

software developed by The Apache Software Foundation (http:// 

www.apache.org/). Licensed under the Apache License, Version 

2.0 (the “License”); you may not use this file except in compliance 

with the License. You may obtain a copy of the License at http:// 

www.apache.org/licenses/LICENSE-2.0. Unless required by 

applicable law or agreed to in writing, software distributed under 

the License is distributed on an “AS IS” BASIS, WITHOUT 

WARRANTIES OR CONDITIONS OF ANY KIND, either express 

or implied. See the License for the specific language governing 

permissions and limitations under the License. 

This product contains Apache Tomcat v. 5.5.17 software 

developed by The Apache Software Foundation (http:// 

www.apache.org/). Licensed under the Apache License, Version 

2.0 (the “License”); you may not use this file except in compliance 

with the License. You may obtain a copy of the License at http:// 







This product includes the Extreme! Computing XPP3-1.1.3.2. 

software developed by the Indiana University Extreme! Lab 

(http://www.extreme.indiana.edu/). Copyright (c) 2002 

Extreme! Lab, Indiana University. All rights reserved. 



conditions are met: 1. Redistributions of source code must retain 

the above copyright notice, this list of conditions and the 

following disclaimer. 2. Redistributions in binary form must 

reproduce the above copyright notice, this list of conditions and 

the following disclaimer in the documentation and/or other 

materials provided with the distribution. 3. The end-user 

documentation included with the redistribution, if any, must 

include the following acknowledgment: “This product includes 

software developed by the Indiana University Extreme! Lab 

(http://www.extreme.indiana.edu/).”; Alternately, this 

acknowledgment may appear in the software itself, if and 

wherever such third-party acknowledgments normally appear. 4. 

The names “Indiana University” and “Indiana University 

Extreme! Lab” must not be used to endorse or promote products 

derived from this software without prior written permission. For 

written permission, please contact http:// 

www.extreme.indiana.edu/. 5. Products derived from this 

software may not use “Indiana Univeristy” name nor may 

“Indiana University” appear in their name, without prior written 

permission of the Indiana University. THIS SOFTWARE IS 

PROVIDED “AS IS” AND ANY EXPRESSED OR IMPLIED 

WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 

IMPLIED WARRANTIES OF MERCHANTABILITY AND 

FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 

IN NO EVENT SHALL THE AUTHORS, COPYRIGHT 

HOLDERS OR ITS CONTRIBUTORS BE LIABLE FOR ANY 

DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 

OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 

LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 

INTERRUPTION) HOWEVER CAUSED AND ON ANY 

THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 

LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 

OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 

THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 

SUCH DAMAGE. 

This product contains Glazed Lists software developed by 

publicobject.com and O’Dell Engineering. Copyright © 2003-2006, 

publicobject.com, O'Dell Engineering Ltd. This library is free 

software; you can redistribute it and/or modify it under the 




Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 

MA 02110-1301 USA.This library is distributed in the hope that it 








This product contains Bean Scripting Framework software 

version 2.2 developed by The Apache Software Foundation 

(http://www.apache.org/). Licensed under the Apache License, 

Version 2.0 (the “License”); you may not use this file except in 

compliance with the License. You may obtain a copy of the 

License at http://www.apache.org/licenses/LICENSE-2.0. 

Unless required by applicable law or agreed to in writing, 

software distributed under the License is distributed on an “AS 

IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF 



the License. 

This product contains IBM Toolbox for Java – JT Open software. 

Copyright © up to and including 2009, International Business 

Machines Corporation (“IBM”) and others. All Rights Reserved. 

Licensed under the IBM Public License Version 1.0 (the 

“License”); you may not use this file except in compliance with 

the License. See the License at http://www-128.ibm.com/ 

developerworks/library/os-ipl.html for the specific language 

governing permissions and limitations under the License. THE 

SOFTWARE IS PROVIDED “AS IS", WITHOUT WARRANTY OF 

ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 

LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 

FITNESS FOR A PARTICULAR PURPOSE AND NON- 

INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 

COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,

DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 

OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR 

THE USE OR OTHER DEALINGS IN THE SOFTWARE. IN NO 

EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY 










SUCH DAMAGE. 

This product contains ICU v. 1.8.1. Copyright © 1995-2008 

International Business Machines Corporation and others. All 

rights reserved. Permission is hereby granted, free of charge, to 

any person obtaining a copy of this software and associated 

documentation files (the “Software”), to deal in the Software 

without restriction, including without limitation the rights to use, 

copy, modify, merge, publish, distribute, and/or sell copies of the 

Software, and to permit persons to whom the Software is 

furnished to do so, provided that the above copyright notice(s) 

and this permission notice appear in all copies of the Software 

and that both the above copyright notice(s) and this permission 

notice appear in supporting documentation. THE SOFTWARE IS 

PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, 

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 

THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 

PARTICULAR PURPOSE AND NONINFRINGEMENT OF 

THIRD PARTY RIGHTS. IN NO EVENT SHALL THE 

COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS 

NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL 

INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 

DATA OR PROFITS, WHETHER IN AN ACTION OF 

CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 

ARISING OUT OF OR IN CONNECTION WITH THE USE OR 

PERFORMANCE OF THIS SOFTWARE. Except as contained in 

this notice, the name of a copyright holder shall not be used in 

advertising or otherwise to promote the sale, use or other 

dealings in this Software without prior written authorization of 

the copyright holder. 

This product contains Java BEEP Core Version 0.9.08 developed 

by The Apache Software Foundation (http://www.apache.org/) 

licensed under the Apache License, Version 1.1. Copyright (c) 

1999-2001 The Apache Software Foundation. All rights reserved. 








materials provided with the distribution. 3. The end-user 



software developed by the Apache Software Foundation (http:// 

www.apache.org/).” Alternately, this acknowlegement may 

appear in the software itself, if and wherever such third-party 

acknowlegements normally appear 4. The names “The Jakarta 

Project”, “Commons” and “Apache Software Foundation” must 

not be used to endorse or promote products derived from this 

software without prior written permission. For written 

permission, please contact apache@apache.org. 5. Products 

derived from this software may not be called “Apache”, nor may 

“Apache” appear in their name, without prior written permission 

of the Apache Software Foundation. THIS SOFTWARE IS 

PROVIDED “AS IS” AND ANY EXPRESSED OR IMPLIED 





IN NO EVENT SHALL THE APACHE SOFTWARE 

FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY 










SUCH DAMAGE. 

This product contains Java BEEP Core Version 0.9.08. Blocks 

Public License Copyright © 2000-2001, Invisible Worlds, Inc. All 

Rights Reserved. Redistribution and use in source and binary 

forms, with or without modification, are permitted provided that 

the following conditions are met: Redistributions of source code 

must retain the above copyright notice, this list of conditions and 

the following disclaimer. Redistributions in binary form must 



materials provided with the distribution. Neither the name, 

trademarks, or trade names of Invisible Worlds, Inc., nor the 

names, trademarks, or trade names of its contributors may be 

used to endorse or promote products derived from this software 

without specific prior written permission. THIS SOFTWARE IS 

PROVIDED BY THE COPYRIGHT HOLDERS AND 

CONTRIBUTORS “AS IS” AND ANY EXPRESSED OR IMPLIED 




IN NO EVENT SHALL INVISIBLE WORLDS OR ITS 

CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 

INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 

DAMAGES (INCLUDING, BUT NOT LIMITED TO, 

PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 

LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 






SUCH DAMAGE. 

Cryptix General License Copyright © 1995, 1997, 1998, 2000. The 

Cryptix Foundation Limited. All rights reserved. Redistribution 

and use in source and binary forms, with or without 

modification, are permitted provided that the following 

conditions are met: Redistribution of source code must retain the 





with the distribution. THIS SOFTWARE IS PROVIDED BY THE 

CRYPTIX FOUNDATION LIMITED AND CONTRIBUTORS “AS 

IS” AND ANY EXPRESSED OR IMPLIED WARRANTIES, 

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 

PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 

SHALL THE CRYPTIX FOUNDATION LIMITED OR ITS 











SUCH DAMAGE. 

This package is a SSLv3/TLS implementation written by Eric 

Rescorla (ekr\@rtfm.com) and licensed by Claymore Systems, 

Inc. Redistribution and use in source and binary forms, with or








with the distribution. All advertising materials mentioning 

features or use of this software must display the following 

acknowledgement: This product includes software developed by 

Claymore Systems, Inc. Neither the name or Claymore Systems, 

Inc. nor the name of Eric Rescorla may be used to endorse or 

promote products derived from this software without specific 

prior written permission. THIS SOFTWARE IS PROVIDED BY 

THE REGENTS AND CONTRIBUTORS “AS IS” AND ANY 

EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 




REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 

INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 

CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 








SUCH DAMAGE. 

This product contains Java Service Wrapper v.3.2.3 developed by 

Tanuki Software. Copyright © 1999, 2006 Tanuki Software Inc. 

Permission is hereby granted, free of charge, to any person 

obtaining a copy of the Java Service Wrapper and associated 

documentation files (the “Software”), to deal in the Software 

without restriction, including without limitation the rights to 

use, copy, modify, merge, publish, distribute, sub-license, and/or 

sell copies of the Software, and to permit persons to whom the 

Software is furnished to do so, subject to the following conditions: 

The above copyright notice and this permission notice shall be 

included in all copies or substantial portions of the Software. THE 

SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF 



FITNESS FOR A PARTICULAR PURPOSE AND NON- 

INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 

COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 

DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 

OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT 

OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE 

OR OTHER DEALINGS IN THE SOFTWARE. Portions of Java 

Service Wrapper have been derived from source code developed 

by Silver Egg Technology under the following license: Copyright 

© 2001 Silver Egg Technology. Permission is hereby granted, free 

of charge, to any person obtaining a copy of this software and 

associated documentation files (the “Software”), to deal in the 

Software without restriction, including without limitation the 

rights to use, copy, modify, merge, publish, distribute, sublicense, 

and/or sell copies of the Software, and to permit persons to 

whom the Software is furnished to do so, subject to the following 

conditions: The above copyright notice and this permission 

notice shall be included in all copies or substantial portions of the 

Software. 

This product contains JavaScript for Java which is subject to the 

Netscape Public License Version 1.1 (the “License”); you may not 

use this file except in compliance with the License. You may 

obtain a copy of the License at http://www.mozilla.org/NPL/. 

Software distributed under the License is distributed on an “AS 

IS” basis, WITHOUT WARRANTY OF ANY KIND, either express 


rights and limitations under the License. The Original Code is 

Rhino code, released May 6, 1999. The Initial Developer of the 

Original Code is Netscape Communications Corporation. 

Portions created by Netscape are Copyright (C) 1997-1999 

Netscape Communications Corporation. All Rights Reserved. 

Contributor(s): Norris Boyd 

This product contains JBoss Application Server version 4.2.0., 

JBoss AOP version 1.5.5.GA and JBoss Web version 2.0.0.GA. 

Copyright © 2006, Red Hat Middleware LLC, and individual 

contributors as indicated by the @author tags. See the 

copyright.txt file in the distribution for a full listing of individual 

contributors This library is free software; you can redistribute it 

and/or modify it under the terms of the GNU Lesser General 

Public License as published by the Free Software Foundation; 

either version 2.1 of the License, or (at your option) any later 

version. Copyright © 1991, 1999 Free Software Foundation, Inc., 

51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. This 

library is distributed in the hope that it will be useful, but 

WITHOUT ANY WARRANTY; without even the implied 

warranty of MERCHANTABILITY or FITNESS FOR A 

PARTICULAR PURPOSE. See the GNU Lesser General Public 





This product contains JFree Chart version 1.0.1. Copyright 2000- 

2006, by Object Refinery Limited and Contributors. This library is 

free software; you can redistribute it and/or modify it under the 




Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 

MA 02111-1307 USA. This library is distributed in the hope that it 








This product contains jTDS Drivers version 1.2.2 for MS SQL 

Server. This library is free software; you can redistribute it and/ 

or modify it under the terms of the GNU Lesser General Public 

License as published by the Free Software Foundation; either 

version 2.1 of the License, or (at your option) any later version. 

Copyright © 1991, 1999 Free Software Foundation, Inc., 59 

Temple Place, Suite 330, Boston, MA 02111-1307 USA. This 

library is distributed in the hope that it will be useful, but 

WITHOUT ANY WARRANTY; without even the implied 

warranty of MERCHANTABILITY or FITNESS FOR A 

PARTICULAR PURPOSE. See the GNU Lesser General Public 





This product contains software developed by JXML, Inc. and its 

contributors:http://www.jxml.com/mdsax/contributors.html 

Copyright (c) 1998, 1999, JXML, Inc. All rights reserved. 








with the distribution. All product materials mentioning features 

or use of this software must display the following 

acknowledgement: This product includes software developed by 

JXML, Inc. and its contributors: http://www.jxml.com/mdsax/ 

contributors.html. Neither name of JXML nor the names of its 

contributors may be used to endorse or promote products 

derived from this software without specific prior written 

permission. THIS SOFTWARE IS PROVIDED BY JXML, INC. 

AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR 

IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 

THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 

FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

IN NO EVENT SHALL JXML OR CONTRIBUTORS BE LIABLE 

FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 

EXEMPLARY, OR CONSEQUENTIAL DAMAGES 









This product contains Log4J software v. 1.2.15 developed by The 

Apache Software Foundation (http://www.apache.org/). 

Licensed under the Apache License, Version 2.0 (the “License”); 

you may not use this file except in compliance with the License. 

You may obtain a copy of the License at http:// 







This product contains NSPR Library software. The contents of 

this file are subject to the Mozilla Public License Version 1.1 (the 

“License”); you may not use this file except in compliance with 

the License. You may obtain a copy of the License at http:// 

www.mozilla.org/MPL/. Software distributed under the License 

is distributed on an “AS IS” basis, WITHOUT WARRANTY OF 


specific language governing rights and limitations under the 

License. The Original Code is the Netscape Portable Runtime 

(NSPR). The Initial Developer of the Original Code is Netscape 

Communications Corporation. Portions created by Netscape are 

Copyright (C) 1998-2000 Netscape Communications Corporation. 

All Rights Reserved. 

This product contains OpenSSL software and is licensed under 

the terms of the OpenSSL License and the SSLeay License. 

Copyright © 1998-2008 The OpenSSL Project. All rights reserved. 








materials provided with the distribution. 3. All advertising 

materials mentioning features or use of this software must 

display the following acknowledgment: “This product includes 

software developed by the OpenSSL Project for use in the 

OpenSSL Toolkit. (http://www.openssl.org/)” 4. The names 

“OpenSSL Toolkit” and “OpenSSL Project” must not be used to 

endorse or promote products derived from this software without 

prior written permission. For written permission, please contact 

openssl-core@openssl.org. 5. Products derived from this software 

may not be called “OpenSSL” nor may “OpenSSL” appear in 

their names without prior written permission of the OpenSSL 

Project. 6. Redistributions of any form whatsoever must retain the 

following acknowledgment: “This product includes software 

developed by the OpenSSL Project for use in the OpenSSL Toolkit 

(http://www.openssl.org/)” THIS SOFTWARE IS PROVIDED 

BY THE OpenSSL PROJECT “AS IS” AND ANY EXPRESSED OR 

IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 

THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 


IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS 












SUCH DAMAGE. This product includes cryptographic software 

written by Eric Young (eay@cryptsoft.com). This product 

includes software written by Tim Hudson (tjh@cryptsoft.com). 

Copyright © 1995-1998 Eric Young (eay@cryptsoft.com). All 

rights reserved. Original SSLeay License. Copyright © 1995-1998 

Eric Young (eay@cryptsoft.com). All rights reserved. This 

package is an SSL implementation written by Eric Young 

(eay@cryptsoft.com). Redistribution and use in source and binary 

forms, with or without modification, are permitted provided that 

the following conditions are met: 1. Redistributions of source 

code must retain the copyright notice, this list of conditions and 

the following disclaimer. 2. Redistributions in binary form must 



materials provided with the distribution. 3. All advertising 

materials mentioning features or use of this software must 

display the following acknowledgement: “This product includes 

cryptographic software written by Eric Young 

(eay@cryptsoft.com)” The word 'cryptographic' can be left out if 

the routines from the library being used are not cryptographic 

related. 4. If you include any Windows specific code (or a 

derivative thereof) from the apps directory (application code) you 

must include an acknowledgement: “This product includes 

software written by Tim Hudson (tjh@cryptsoft.com)” THIS 

SOFTWARE IS PROVIDED BY ERIC YOUNG “AS IS” AND ANY 

EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 

LIMITED TO, THE IMPLIED WARRANTIES OF 



AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 

INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 

CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 








SUCH DAMAGE. 

This product includes Sapia Ubik software developed by Sapia 

Open Source Software. Copyright © 2002, 2003 Sapia Open 

Source Software (http://www.sapia-oss.org/). All rights 

reserved. Redistribution and use in source and binary forms, with 

or without modification, are permitted provided that the 

following conditions are met: Redistributions of source code must 

retain the above copyright notice, this list of conditions and the 

following disclaimer. Redistributions in binary form must 



materials provided with the distribution. The end-user 



software developed by Sapia Open Source Software Organization 

(http://www.sapia-oss.org/).” Alternately, this 

acknowledgment may appear in the software itself, if and 

wherever such third-party acknowledgments normally appear. 

The names “Sapia", “Sapia Open Source Software” and “Sapia 

OSS” must not be used to endorse or promote products derived 

from this software without prior written permission. For written 

permission, please contact info@sapia-oss.org. Products derived 

from this software may not be called “Sapia”, nor may “Sapia” 

appear in their name, without prior written permission of Sapia 

OSS. THIS SOFTWARE IS PROVIDED “AS IS” AND ANY 

EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 




SAPIA OSS ORGANIZATION OR ITS CONTRIBUTORS BE 

LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 

SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 

(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF









This product contains software code that is Copyright 2007, 

Microsoft Corporation. All rights reserved. 

This product contains XML Parsing Library for C version 2.6.32. 

Copyright (C) 1998-2003 Daniel Veillard. All Rights Reserved. 

Permission is hereby granted, free of charge, to any person 

obtaining a copy of this software and associated documentation 

files (the “Software”), to deal in the Software without restriction, 

including without limitation the rights to use, copy, modify, 

merge, publish, distribute, sublicense, and/or sell copies of the 

Software, and to permit persons to whom the Software is 

furnished to do so, subject to the following conditions: The above 

copyright notice and this permission notice shall be included in 

all copies or substantial portions of the Software. THE 

SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF 



FITNESS FOR A PARTICULAR PURPOSE AND 

NONINFRINGEMENT. IN NO EVENT SHALL THE DANIEL 

VEILLARD BE LIABLE FOR ANY CLAIM, DAMAGES OR 

OTHER LIABILITY, WHETHER IN AN ACTION OF 

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF 

OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 

OTHER DEALINGS IN THE SOFTWARE.

MKS Integrity Server 2009 Administration Guide

Create successful ePaper yourself

Delete template?

Save as template?