MKS Integrity Server Administration Guide

® 

Integrity 

MKS Integrity Server 

2007 

Administration Guide

MKS Integrity Server 2007 

Administration Guide 

Copyright © 2001–2007 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, MKS Source Integrity, MKS Integrity Manager, Implementer, MKS Toolkit, Sandbox, NuTCRACKER, MKS Integrity Solution, 

AlertCentre, MKS Integrity Suite, and MKS Federated Server are trademarks or registered trademarks of MKS Inc. All other trademarks 

or registered 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 

Ebisu Garden Place Tower 18F 

Ebisu 4-20-3 

Shibuya-ku, Tokyo, Japan 

150-6018 

tel: 03-5789-5862 

fax: 03-5789-5757

Table of Contents 

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

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

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

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

MKS Integrity Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

MKS Source Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

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

Quick Access Keys (GUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

Common Dual List Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

Filtering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Working With Favorites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 

Display Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

Server Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Print Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

Collecting Properties and Log Files . . . . . . . . . . . . . . . . . . . . . . . 30 

Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 

MKS Integrity Client Preferences . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Server Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

MKS Integrity Administration Client Preferences . . . . . . . . . . . 37 

Setting MKS Integrity View Preferences . . . . . . . . . . . . . . . . . . . 39 

Authorization Administration Preferences . . . . . . . . . . . . . . . . . 39 

MKS Deploy Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 

Administration Command Line Interface . . . . . . . . . . . . . . . . . . . . . . 41 

Defining Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

Rule Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 

Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 

Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 

Selecting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

Viewing Administration History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

i


ii 

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

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

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

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

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

Creating ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

Editing ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

Copying ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

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

Making ViewSets Available to Users . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

Process Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 

Publish New ViewSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 

Publish Personal ViewSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 

Converting Personal ViewSet to Unpublished ViewSet . . . . . . 59 

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

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

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

Administering Published ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

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

Viewing ViewSet Properties. . . . . . . . . . . . . . . . . . . . . . . . . . 63 

Editing ViewSet Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

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

Updating Published ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 

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

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

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

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

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

Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

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

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

Working in Types View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82


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

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

Editing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

Copying Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 

Viewing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 

Deleting Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 

Moving Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

Assigning Type Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

Setting Item Editability for Types . . . . . . . . . . . . . . . . . . . . . . . . . 95 

Setting Type Visibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 

Setting Type Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

Overrides for Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

Overrides for States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 

Setting Field Visibility for Types . . . . . . . . . . . . . . . . . . . . . . . . . 101 

Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 

Working in Fields View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 

Available Menu Commands for Fields. . . . . . . . . . . . . . . . 105 

Using Display Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 

Creating Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Setting Possible Values for Fields . . . . . . . . . . . . . . . . . . . . 107 

Specifying Default Columns . . . . . . . . . . . . . . . . . . . . . . . . 124 

Setting Field Relevance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 

Setting Field Editability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

Setting Field Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 

Setting Field Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 

Editing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 

Viewing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

Deactivating Picklist Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

Deleting Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 

Moving Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 

Managing Field Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 

Creating Field Relationships . . . . . . . . . . . . . . . . . . . . . . . . 134 

Editing Field Relationships . . . . . . . . . . . . . . . . . . . . . . . . . 137 

Deleting Field Relationships . . . . . . . . . . . . . . . . . . . . . . . . 137 

Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 

Workflow View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 

Creating Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 

Configuring Self Transitions . . . . . . . . . . . . . . . . . . . . . . . . 142 

Viewing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 

Managing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

Printing Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 

Saving Workflow as Image. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 

Testing Workflow With Admin Migration Wizard . . . . . . . . . 147 

Installing and Starting Production Server . . . . . . . . . . . . . 150 

Installing and Configuring Staging Server . . . . . . . . . . . . 150 

iii


iv 

Copying MKS Integrity Database . . . . . . . . . . . . . . . . . . . . 152 

Starting Staging Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 

Testing MKS Integrity Configuration . . . . . . . . . . . . . . . . . 153 

Managing Administrative Locks . . . . . . . . . . . . . . . . . . . . . 154 

Using Admin Migration Wizard . . . . . . . . . . . . . . . . . . . . . 156 

Considerations When Modifying Visibility, Editability, and Types 160 

Deleting Admin Objects and Items . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 

Deleting Admin Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 

Deleting Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 

Setting Up E-mail Notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 

Permissions for E-mail Notification . . . . . . . . . . . . . . . . . . 163 

Troubleshooting E-mail Notification . . . . . . . . . . . . . . . . . 166 

5 Customizing Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 

Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 

Customizing Item Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 

Understanding Template Designer. . . . . . . . . . . . . . . . . . . . . . . 171 

Available Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 

Modifying Template Properties. . . . . . . . . . . . . . . . . . . . . . 174 

Tips for Working With Template Designer . . . . . . . . . . . . 178 

Templates for Viewing, Submitting, and Printing Items . 179 

Previewing Presentation Template . . . . . . . . . . . . . . . . . . . 179 

Creating New Presentation Template. . . . . . . . . . . . . . . . . . . . . 181 

Editing Presentation Template . . . . . . . . . . . . . . . . . . . . . . . . . . 185 

Working With Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 

Working With Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 

Working With Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 

Working With Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 

Filtering Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 

Adding Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 

Working With Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 

Copying Presentation Template . . . . . . . . . . . . . . . . . . . . . . . . . 196 

Viewing Presentation Templates. . . . . . . . . . . . . . . . . . . . . . . . . 197 

Deleting Presentation Template . . . . . . . . . . . . . . . . . . . . . . . . . 198 

Customizing Rich Content Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 

Customizing Report Presentation Templates . . . . . . . . . . . . . . . . . . 201 

Report Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 

Report Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 

Configuring Attachment Size Limits . . . . . . . . . . . . . . . . . . . . . . . . . 214 

Configuring Limits for Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 

System Query Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 

Query Timeouts for Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 

Maximum Query Item Count . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 

Configuring Context Based Text Searching . . . . . . . . . . . . . . . . . . . . 217


Setting Up Electronic Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 

Customizing Electronic Signature Trigger. . . . . . . . . . . . . 218 

Admin Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 

Converting User Objects to Admin Objects. . . . . . . . . . . . . . . . 219 

Viewing Admin Object References . . . . . . . . . . . . . . . . . . . . . . . 220 

Charts View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 

Dashboards View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 

Queries View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 

Reports View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 

Using Type Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 

Operations for Type Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 225 

6 Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 


MKS Integrity Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

Projects View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

Setting Project Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 

Creating Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 

Editing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 

Viewing Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 

Deleting Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 

Managing Project Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 

Deactivating Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 

Assigning MKS Integrity Project Administrator. . . . . . . . . . . . 240 

MKS Source Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 

MKS Source Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 

Organizing Your Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 

Single-tree Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 

Working With Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 

Creating Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 

Importing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 

Importing Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 

Dropping Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 

Restoring Project to Previous Checkpoint . . . . . . . . . . . . . 250 

Restoring Deleted Projects . . . . . . . . . . . . . . . . . . . . . . . . . . 257 

Using Project Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 

Working With Subprojects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 

Creating Subprojects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 

Adding Subprojects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

Adding Shared Subprojects . . . . . . . . . . . . . . . . . . . . . . . . . 262 

Configuring Subprojects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 

Sharing Archives With Other Projects . . . . . . . . . . . . . . . . . . . . 265 

Shared Subprojects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 

Common Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 

Potential Problems With Common Projects. . . . . . . . . . . . 267 

v


vi 

7 Computed Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 269 


Computed Expression Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 

Computed Expression Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 

Empty Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 

Dates, Times, and Time Zones. . . . . . . . . . . . . . . . . . . . . . . . . . . 272 

Timestamp Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 

Date Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 

User and Group Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 

Data Conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 

Function Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 

Creating Computed Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 

Calculating Static Computed Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 287 

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

Scheduling Computation Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 

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

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 

Performance and Scalability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 

8 Change Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 

Where to Go From Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 

MKS Integrity Change Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 

Viewing Change Package Types . . . . . . . . . . . . . . . . . . . . . 297 

Changing Change Package Type Order . . . . . . . . . . . . . . . 298 

Editing Change Package Types . . . . . . . . . . . . . . . . . . . . . . 299 

Viewing Change Package Types . . . . . . . . . . . . . . . . . . . . . 303 

Creating Change Package Types . . . . . . . . . . . . . . . . . . . . . 304 

Deleting Change Package Types . . . . . . . . . . . . . . . . . . . . . 305 

Modifying Change Package Attributes . . . . . . . . . . . . . . . . . . . 305 

Viewing Change Package Attributes . . . . . . . . . . . . . . . . . 306 

Viewing Change Package Attribute Details. . . . . . . . . . . . 306 

Creating Change Package Attributes . . . . . . . . . . . . . . . . . 307 

Editing Change Package Attributes . . . . . . . . . . . . . . . . . . 308 

Deleting Change Package Attributes . . . . . . . . . . . . . . . . . 308 

Modifying Change Package Entry Attributes . . . . . . . . . . . . . . 309 

Viewing Change Package Entry Attributes . . . . . . . . . . . . 309 

Viewing Change Package Entry Attribute Details . . . . . . 310 

Creating Change Package Entry Attributes. . . . . . . . . . . . 310 

Editing Change Package Entry Attributes . . . . . . . . . . . . . 311 

Deleting Change Package Entry Attributes . . . . . . . . . . . . 312 

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

Creating Change Packages . . . . . . . . . . . . . . . . . . . . . . . . . . 313


Editing Change Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 

Deleting Change Packages . . . . . . . . . . . . . . . . . . . . . . . . . . 313 

Modifying CP Entries for Created CP Types. . . . . . . . . . . . . . . 314 

Creating Change Package Entries . . . . . . . . . . . . . . . . . . . . 314 

Editing Change Package Entries . . . . . . . . . . . . . . . . . . . . . 314 

Deleting Change Package Entries . . . . . . . . . . . . . . . . . . . . 315 

MKS Source Change Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 

Using Change Package Reviews . . . . . . . . . . . . . . . . . . . . . . . . . 316 

How Change Package Review Works . . . . . . . . . . . . . . . . 317 

Review Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 

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

9 Event Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 


MKS Integrity Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 

Event Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 

How to Use MKS Integrity Event Triggers . . . . . . . . . . . . 323 

Transactionality of Event Triggers . . . . . . . . . . . . . . . . . . . 324 

Planning Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 

Using Event Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 

Managing Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 

Creating Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 

Running Scheduled Triggers . . . . . . . . . . . . . . . . . . . . . . . . 335 

Viewing Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 

Editing Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 

Deleting Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 

Resolving Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 

MKS Integrity Script Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 

Available Pre-created Scripts . . . . . . . . . . . . . . . . . . . . . . . . 337 

Adding Scripts to Library. . . . . . . . . . . . . . . . . . . . . . . . . . . 338 

Server-side MKS Source Event Triggers. . . . . . . . . . . . . . . . . . . . . . . 340 

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 

MKS Source Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 

Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 

Event Trigger Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Subproject Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Components of Event Triggers . . . . . . . . . . . . . . . . . . . . . . 347 

Creating Server-side Event Triggers. . . . . . . . . . . . . . . . . . . . . . 347 

Configuring Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . 348 

Planning Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 

Writing Event Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 

Updating Events Definition File . . . . . . . . . . . . . . . . . . . . . 351 

Event Trigger Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 

Sample Server-side Event Triggers . . . . . . . . . . . . . . . . . . . . . . . 353 

Sample Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 

vii


vii 

Running Custom Java Code. . . . . . . . . . . . . . . . . . . . . . . . . 355 

Additional Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 

Configuring Client-side Event Triggers . . . . . . . . . . . . . . . . . . . 355 

Trigger Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 

Target Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 

Sample Client-side Triggers . . . . . . . . . . . . . . . . . . . . . . . . . 358 

Modifying MKS Integrity Item Fields. . . . . . . . . . . . . . . . . . . . . 364 

Appendixes A Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 

Gathering Important Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 

Running MKS Integrity Server as Application . . . . . . . . . . . . . . . . . 377 

Differencing MKS Integrity Server Properties Files . . . . . . . . . . . . . 378 

MKS Integrity Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 

MKS Integrity Client Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 

MKS Integrity Server Logging Levels. . . . . . . . . . . . . . . . . . . . . . . . . 380 

Miscellaneous Logging Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 

FLEXnet Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 

Dr. Watson Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 

Creating Integrations Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 

si diag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 

im diag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 

runstacktrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 

mksis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 

isutil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 

Starting Server in Safe Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 

Troubleshooting Database Repository . . . . . . . . . . . . . . . . . . . . . . . . 391 

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

Troubleshooting MKS Source Reporting . . . . . . . . . . . . . . . . . . . . . . 394 

B Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 

Product Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

C HAPTER ONE 

Introduction 

Understanding This Guide 

1 

The MKS Integrity Server 2007 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 MKS Integrity, MKS Source, and the associated product 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 2007 

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 

MKS Integrity projects 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 Client 2007 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 and MKS Source 

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, 

and MKS Integrity and MKS Source 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 169 

Advanced information on customizing workflows used in your organization. 

Chapter 6: “Projects” on page 227 

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

Assumptions 

Chapter 7: “Computed Expressions” on page 269 

Provides information on arithmetic operations between fields and their uses. 

Chapter 8: “Change Packages” on page 295 

Assumptions 

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

use them effectively. 

Chapter 9: “Event Triggers” on page 321 

Describes how to use event triggers with global and project applications. 

Appendix A: “Troubleshooting” on page 373 

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

from MKS Customer Care. 

Appendix B: “Glossary” on page 395 

Defines many of the common terms used when talking about the MKS Integrity Server, 

MKSIntegrity, and MKSSource. 

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

following assumptions of your knowledge and experience: 

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

templates for MKS Integrity or making changes to the MKS Integrity Server home page. 

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

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 

3


4 

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

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

Configuration Guide. 

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

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

If you are implementing MKS Integrity or MKS Source event triggers, you have 

experience with JavaScript. 

If you are implementing MKS Integrity event triggers, you understand logical rules. 

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

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 the MKS Integrity Server, MKS Integrity, and 

MKS Source. 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 


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. 

MKS Integrity Setup 

Additional tasks required of a super administrator for the MKS Integrity 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 MKS Integrity 

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

scope of their user privileges. 

MKS Integrity ships with only a few standard fields and values. Therefore, the super 

administrator needs to define other MKS Integrity 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 MKS Integrity, 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. 

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 MKS Integrity event triggers, “Event Triggers” on page 321. 

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. 

5


6 

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 MKS Integrity standard fields. The standard fields are 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 in MKS Integrity. Graphical 

charts show users a summary of the data in MKS Integrity. 

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. 

MKS Source Setup 

Before using MKS Source to manage the 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 Source, 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 2007 Installation and Configuration Guide. 

The overall security environment for MKS Integrity 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 

MKS Source, 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 

MKS Source environment by creating projects and subprojects. For more information on 

setting up projects, see “MKS Source Projects” on page 242. 

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

to customize your MKS Source environment further and to control the way users may 

operate in that environment. For more information on event triggers, see “Server-side 

MKS Source Event Triggers” on page 340. 

7


Where to Go Next 

8 

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 admin objects. 

Create MKS Integrity and MKS Source projects 

to manage tasks and members. 

Create MKS Integrity and MKS Source change 

packages 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 169 

“Projects” on page 227 

“Change Packages” on page 295

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), set up MKS Integrity, and configure MKS Source policies through a GUI. The 

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

administration tasks. 

For this guide, all procedures are documented using menu-based commands; however, 



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 32 

“Administration Command Line Interface” on page 41 

“Defining Rules” on page 41 

“Viewing Administration History” on page 46 

9

Chapter 2: MKS Integrity Administration Client 

Introduction 

Opening Interface 

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 this guide, all procedures are documented using menu-based commands; however, 



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

perform maintenance on each server. 

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 2007 Installation and 


To open the MKS Integrity Administration Client from the GUI 

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 using the GUI 

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

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 in the GUI 

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

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 from the GUI 

Application Window 

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. 

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

explained in this section.

Title Bar 

Menu Bar 

Toolbars 

Application 

Window 

Tree Pane 

Status Bar 

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. 

Introduction 

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 

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

example, working with permissions or MKS Source policies). 

13


14 

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 MKS Integrity is not installed on the server, the MKS Integrity node is not 

displayed 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 MKS Source policies under the 

MKS Source section. For more information, see the MKS Integrity Server 2007 Installation and 


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 2007 Installation and 


Permissions See the MKS Integrity Server 2007 Installation and 

Configuration Guide.

View Node Location 

MKS Integrity Users See the MKS Integrity Server 2007 Installation and 


Display Pane 

Groups See the MKS Integrity Server 2007 Installation and 


Dynamic Groups See the MKS Integrity Server 2007 Installation and 


Projects See “Projects View” on page 229. 

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

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

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

Triggers See “Managing Event Triggers” on page 326. 

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

Charts See “Charts View” on page 221. 

Dashboards See “Dashboards View” on page 222. 

Queries See “Queries View” on page 223. 

Reports See “Reports View” on page 223. 



MKS Source Policies See the MKS Integrity Server 2007 Installation and 




MKS Deploy See the MKS Deploy 2007 Administration Guide. 

Introduction 

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: a blank check box ( ) means the option is not enabled, a 

check mark ( ) means the option is enabled, and a question mark ( ) denotes to be 

prompted to confirm or specify the option. 

15


16 

Status Bar 

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 

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 MKS Integrity 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:

Filtering Data 

Introduction 

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 

( ) buttons. 

^ 

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 

Text Filter Attribute Filters 

A typical data filter 

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: 

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. 

17


18 

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

are looking for, for example: 

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.

Filtering Data in List 

Data filter when setting a default field value 

Introduction 

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. 

19


20 

Filtering Data in View 

Data filter for the Default Selected Projects list 

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 

MKS Integrity 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 nonfavorites 

using the my favorites or not my favorites filters. For more information, see 

“Working With Favorites” on page 26. 

Active and Inactive Values 

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

values are users, groups, MKS Integrity projects, and pick list items that 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. 

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

realm. 

21


22 

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. 

MKS Integrity Projects 

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

MKS Source Projects 

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

subprojects. 

E-mail Notification Rules 

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, MKS Integrity projects, or pick list 

values. 

inactive Displays inactive users, groups, MKS Integrity 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. 

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. 

To filter data 

Introduction 

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. 

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. 

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. 

23


24 

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

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.

Introduction 

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 an MKS Source 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. 

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

25


26 

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 MKS Integrity 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 17). 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 an Admin 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. 

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 

Introduction 

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 

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. 

27


Server Connections 

28 

Symbol Description 

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

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

The MKS Integrity Administration Client permits connections to multiple MKS Integrity 

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

To connect to an MKS Integrity Server 

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.

Introduction 

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, MKS Integrity, and MKS Source 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. 

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. 

To disconnect from an MKS Integrity Server 

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

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. 

29


Print Functions 

30 

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. 

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. 

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. 

Collecting Properties and Log Files 

If you are unable to diagnose a problem with the MKS Integrity Client or MKS Integrity 

Server, you can use the MKS Integrity Administration Client to collect client and server logs 

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

more information, see “Troubleshooting” on page 373.

Note the following: 

Introduction 

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. 

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 

in security.properties: 

ldap.credential=xxxx 

ldap.principal=xxxx 

ldap.credential=xxxx 

ldap.principal=xxxx 

clear text passwords 

To create a support package, you must have AdminServer and AdminProxy permissions for 

MKS Source and MKS Integrity. 

To create a support package from the MKS Integrity Administration Client GUI 

1 From the MKS Integrity Administration Client, connect to the MKS Integrity Server that 

you want to retrieve server files from. 

31


32 

2 From the tree pane, right click the MKS Integrity or MKS Source node, and select Collect 

Support Package. A standard save dialog box displays. 

3 Type a name for the ZIP file, for example, support.zip. 

4 Click Save. 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 374. 

To create a support package from the CLI when the MKS Integrity Server is not running 

From a command line, go to /bin and type one of the 

following commands: 

On Windows: 

NOTE This command collects server files only. 

collectSupportPackage.exe zipFilename 

On UNIX: 

where 

Preferences 

collectSupportPackage zipFilename 

zipFilename specifies the name of the ZIP file, for example, support.zip. 

The MKS Integrity Client contains a common Preferences Configuration window that 

displays in MKS Integrity Administration Client, MKS Integrity, MKS Source, and 

Authorization Administration. The Preferences Configuration window allows you to 

configure preferences for each component installed on your local machine.

Preferences 

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

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

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

Administration Client Preferences” on page 37. 

To configure MKS Source preferences, refer to the MKS Source 2007 User Guide. 

To configure MKS Integrity preferences, refer to the MKS Integrity 2007 User Guide. 

To configure Authorization Administration preferences, see “Authorization 

Administration Preferences” on page 39. 

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 

The confirmation dialog box that appears when you shut down the MKS Integrity 

Client 

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 

33


34 

To set MKS Integrity Client preferences from the GUI 

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. 

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 

Server Preferences 


Preferences 

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—MKS Source, MKS Integrity, MKS Integrity Administration Client, 

and Authorization Administration—close and shut down. 


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

Server architecture (FSA) serves MKS Source 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. 

Optionally, you can specify a network proxy to connect to by configuring the SOCKS node. 

For a detailed discussion about using a proxy, see the MKS Integrity Server 2007 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 Source 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 Source prompts you only 

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

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

35


36 

b) Select Always confirm proxy username and password if you want MKS Source 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: 

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

4 To save your preferences, click OK.

To set SOCKS preferences from the GUI 


Preferences 

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

node. The SOCKS pane displays. 

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

4 In the Port field, type the port number. 


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 


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

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 GUI. When you restart the MKS Integrity 

Administration Client GUI, 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 . The Configure toolbar for: Desktop View dialog box displays. 

37


38 

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

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.


Preferences 

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 2007 Installation and Configuration 

Guide. 


Setting MKS Integrity View Preferences 

You can also modify MKS Integrity views by setting preferences through the MKS Integrity 

GUI. 

To set view preferences in the MKS Integrity GUI 

1 Open the MKS Integrity client, and select Tools > Preferences. The Preferences 

Configuration panel displays. 

2 Expand the Views directory, and choose the view you want to configure. 

3 Configure the options as required. For detailed information on options, see the online 

help. 


Authorization Administration Preferences 

For Authorization Administration, you can configure the default settings for connecting to 

the MKS Integrity Server. 

39


40 

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. 

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 2007 Installation and Configuration 



MKS Deploy Preferences 

To use features set in the MKS Deploy preferences, you must be licensed for MKS Deploy. 

For more information, see the MKS Deploy 2007 Administration Guide.

Administration Command Line Interface 

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 

2007 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 

A rule is a statement that sets a specified outcome when certain conditions are met. For 

example, you could create a rule to send e-mail notification to all users in the QA group when 

an item has been fixed and incorporated into a build. 

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 following example shows an e-mail notification rule that asks MKS Integrity to notify the 

user (admin@xyzBusiness.com) each time a feature request is submitted or whenever a bug 

is assigned to them. With the or node, the notification occurs whenever either of the events 

occurs. 

41


42 

Nodes 

The logical and indicates that all of the specified conditions must be true to meet the 

requirements of the rule. 

The logical or 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. 

To create a node 

1 Select the and or or node where you want to insert the new node. 


To insert an or, click Or. 

To insert an and, click And. 

To toggle a node between or and and, select the node, and click Swap. 

3 Under Condition: 

Select the condition. 

Specify the values you want to add (for information on using the data filter, see 

“Filtering Data” on page 17). 

Click Add. 

4 Repeat steps 1 to 3 as required to build your rule. 

5 To accept the completed rule, click OK. 

Conditions 

NOTE To delete a node, select the node, and click Remove. A confirmation dialog 

box displays. To confirm the deletion, click Yes. 

Conditions are a statement of the requirements that must be satisfied. They can involve either 

user values, field values, or properties associated with an item type.

To create a condition involving user groups 

1 Select the and or or node where you want to insert the new condition. 


2 Under Condition, select Check the group membership of the user performing 

the action. 

3 Select is or is not from the list. 

4 Select a group name from the a member of list. For detailed information on using the 

data filter, see “Filtering Data” on page 17. 

5 When you are finished constructing the condition, click Add. The condition displays 

under the selected node. 

To create a condition involving field values 


2 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 

3 Select the Boolean operator from the list (see “Operators” on page 44). 

4 Specify fields and field values for the condition. For detailed information on using the 

data filter, see “Filtering Data” on page 17. 

NOTE You cannot specify MKS Source project and attachment fields. 

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. 

c) To save the specified value, click OK. 

5 For each field, specify an Existing Value or a New Value. 

43


44 



To replace an existing rule statement with a new one 

1 Select the existing statement. 

2 Construct the condition as described earlier. 

3 Click Replace. A confirmation dialog box displays. 

4 To confirm the replacement, click Yes. 

To check a property associated with an item type 

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. 


2 Under Condition, select Check a property associated with the item's type. 

3 Select a type property name from the filtered list. For information on using the data 

filter, see “Filtering Data” on page 17. 

4 Select the operator from the list (see “Operators” on page 44). 

5 Enter a value for the property in the subsequent field. 



Operators 

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) 

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)

Selecting Rules 

Operator Description 

< Less than (single valued fields) 

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 

Contains at least one element less than (multi-valued fields) 


Viewing Administration History 

46 

Setting up MKS Integrity involves modifying a number of administrative objects to 

customize the configuration to suit your work environment. MKS Integrity administrative 

objects are users, groups, dynamic groups, projects, states, types, fields, triggers, change 

package types, and change package attributes. Whenever changes are made 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 2007 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. 

For example, the following diagram shows the record of administrative changes for the 

MKS Integrity project QA Scripts. In this example, changes were made to the project 

administrators responsible for the QA Scripts project.

Viewing Administration History 

47


48

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 2007 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 57 

“Administering Published ViewSets” on page 63 

“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 57 

“Administering Published ViewSets” on page 63 

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

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. 

51


52 

To open the ViewSets view from the MKS Integrity Administration Client, select the ViewSet 

Distribution > ViewSets node. The ViewSets view displays. 

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 55 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 63). 

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. 

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: 

IT Executive 

ViewSet for monitoring all activities within an organization at a high-level. This ViewSet 

includes views and actions for dashboards. 

Business Analyst 

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

ViewSet for for creating and managing requirements. This ViewSet includes views and 

actions for items, queries, charts, and reports. It also includes custom actions that launch 

Microsoft Word, Microsoft Excel, and Microsoft PowerPoint, if installed in the default 

directories on your client. 

53


54 

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. 

Integrity Administrator 

ViewSet for managing queries, charts, reports, and dashboards. This ViewSet includes 

views and actions for items, queries, charts, reports, dashboards, and column sets. 

Project Manager 

ViewSet for tracking project status and activities. This ViewSet includes views and 

actions for change packages, items, queries, charts, reports, dashboards, and column 

sets. 

Developer 

ViewSet for software developers. This ViewSet includes views and actions for projects, 

Sandboxes, members, change packages, items, queries, and time entries. 

Integrity User 

ViewSet for creating, updating, and monitoring items. This ViewSet includes views and 

actions for change packages, items, queries, charts, reports, dashboards, and column 

sets. 

iSeries Developer 

ViewSet for reviewing iSeries 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 MKS Source, see the MKS Implementer 

2007 User Guide. 

Basic ViewSet Operations 

This section covers basic operations that you can perform on ViewSets: 

“Creating ViewSets” on page 55 

“Editing ViewSets” on page 55

Creating ViewSets 

Editing ViewSets 

“Copying ViewSets” on page 56 

“Deleting ViewSets” on page 56 

Basic ViewSet Operations 

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. 

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 55). The Edit ViewSet GUI is automatically 

launched so you can customize the ViewSet (see “Editing ViewSets” on page 55). 

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 

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 interface 

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 

55


Copying ViewSets 

Deleting ViewSets 

56 

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 2007 Getting Started Guide. 

IMPORTANT The customizing ViewSet documentation in the MKS Integrity Client 

2007 Getting Started Guide specifies which functionality is only available through the 

MKS Integrity Administration Client. 

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 interface 

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. 

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

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.

Making ViewSets Available to Users 

To delete a ViewSet using the MKS Integrity Administration Client interface 

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. 


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

57


Process Overview 

58 

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. 

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 

The following is the general process for publishing a new ViewSet. 

1 From ViewSets view, create an unpublished ViewSet (see “Creating ViewSets” on 

page 55). 

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

Publish Personal ViewSet 

Create Unpublished Publish 

Published 

ViewSet 

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

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

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 56). 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 59. 

To publish a ViewSet using the MKS Integrity Administration Client GUI 


want to publish. 

59


60 

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

To advance to the next step, click Next. 

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.

Testing ViewSets 


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. 

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 2007 

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. 

61


62 

Mandatory ViewSets bypass the user acceptance process for downloading new (or updated) 

ViewSets from the MKS Integrity Server (see the MKS Integrity Client 2007 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 

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 interface 


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

63


64 

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. 

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 client, and save it as an unpublished ViewSet (see 

“ViewSet Types and Locations” on page 52). Editing a ViewSet (see “Editing ViewSets” on 

page 55) 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 interface 

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 Sever ViewSet. 

Edit Server 

ViewSet 

Need to modify a 

Server ViewSet 

Creates 

Unpublished ViewSet 

Copy 

Publish ViewSet 

Server ViewSet 

Updated 

1 Identify a need to modify a published ViewSet. 

Fetch Server 

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 55) or by fetching the ViewSet (see “Fetching Published 


ViewSets can then be modified by editing or by making changes through the 

Publish ViewSet wizard. 

65


66 

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. 

ViewSet Permissions 

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

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 2007 


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: 

ViewSets FAQ 

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. 

For information on filtering data (in this case users and groups) see “Filtering Data” on 

page 17. 

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

67


68 

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 


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 55 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. MKS Integrity 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 102 

“Workflows” on page 138 

“Considerations When Modifying Visibility, Editability, and Types” on page 160 

“Deleting Admin Objects and Items” on page 161 

“Setting Up E-mail Notification” on page 162 

69

Chapter 4: Workflow Management 


70 

The following table summarizes the steps you should follow to set up an MKS Integrity 

workflow. 


Manage states, including creating and editing 

states. 

Manage types, including creating and editing 

types. 

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 MKS Integrity workflow 

using the Admin Migration Wizard. 

Assessing Your Current Product Development 

Process 

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 MKS Integrity project 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 




“Managing Field Relationships” on page 132 


“Considerations When Modifying Visibility, 

Editability, and Types” on page 160 

“Testing Workflow With Admin Migration Wizard” 

on page 147

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 MKS Integrity? 

2 Can you predict requiring different privileges for users in these groups? 

everyone is required to administer the MKS Integrity project 

one administrator, with the rest of the team having a subset of the administrator’s 

privileges 

What MKS Integrity privileges do you grant to your users? 

3 What are the user groups you can identify? 

MKS Integrity 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 objects in MKS Integrity: 

The MKS Integrity Administration Client does not lock admin 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. 

73


74 

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 

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 


As the super administrator responsible for setting up MKS Integrity, you have access to all 

admin 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 MKS Integrity 

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 240. For more information on type 

administrators, see “Assigning Type Administrator” on page 93. 

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: 

MKS Integrity 

Object 

Super Administrator Project Administrator Type Administrator 

Users Create 

Edit 

View 

Delete 

Import 

View View 

Groups Create 

Edit 

View 

Delete 

Import 

View View


Object 

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 subprojectsa View 

View 

No access Create 

Edit b 

View 

Deleteb Type Overridesc No access Edit 

View 

Create/edit 

presentation 

templates 

No access Create 

Edit b 

View 

Type Overrides c 

No access No access 


75


MKS Integrity Administration Permissions 

76 


Object 

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 MKS Integrity admin 

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 MKS Integrity 

project 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 2007 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 2007 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 MKS Integrity states from 

one convenient location. Managing states is carried out through the States view. 

77


78 

To open the States view from the MKS Integrity Administration Client, expand the 

MKS Integrity 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 17. 

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 

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 

MKS Integrity. 

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 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 2007 User Guide. 

In MKS Source, 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 Source 


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 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 Source, 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. 

79


Editing States 

Viewing States 

80 

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. 

7 When you are finished setting the properties, click OK. 

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 

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

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 “Viewing Admin Object References” on page 220. 

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 

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

TIP You can double click a state in the States view to view it.

Deleting States 

Moving States 

State Metrics 

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 overridden for that type. 

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 

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 

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. 

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 

81


Types 

82 

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

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. 

Working in Types View 

Using the MKS Integrity Administration Client, you can manage MKS Integrity types from 

one convenient location. Managing types is carried out through the Types view. 

To open the Types view from the MKS Integrity Administration Client, expand the 

MKS Integrity 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 17. 

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 132 and “Workflows” on page 138. 

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 for use in MKS Integrity 

copy a type 

reposition, or change the order of presentation for, a type in MKS Integrity 

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 

Access to workflow functionality occurs in the Workflow view, which is contained in the Edit 

Type dialog box. 

83


Creating Types 

84 

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 

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

Attributes 

See “Configuring Type Attributes” on page 87. 

Properties 

See “Using Type Properties” on page 224.

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. 

Item Editability 

See “Setting Item Editability for Types” on page 95. 

Field Relationships 

See “Managing Field Relationships” on page 132. 

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 

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. 

NOTE 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 97. 

Overrides for Fields and Overrides for States 

See “Setting Type Overrides” on page 97. 

85


86 

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 

MKS Integrity uses. Use the Move Up or Move Down buttons to change the position 

of the new type. 

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. 

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 101. If there are no fields defined for your installation, see “Creating 

Fields” on page 106. 

Workflow 

Design the workflow for the type. For more information, see “Workflows” on 

page 138. 

Presentations 

Customize the item presentation using the presentation template designer. For more 

information, see “Customizing Item Presentation” on page 170. 

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:

Types 

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, Query, Column Set. 

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 

From the Create Type or Edit Type dialog box (see “Creating Types” on page 84 or “Editing 

Types” on page 90), in the tree pane, select Attributes. The Attributes view displays. 

87


88 

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 “To set possible values for a phase data type” on 

page 120. 

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. 

Items of this type 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 Project Metadata” on 

page 237. 

NOTE 

To make this option available, the Project field must be selected as a visible field 

for this type. 

If you enable the Items of this type 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 96.

Types 

Items of this type 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 Copy Tree Rule 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 95. 

To learn more about rules, see “Defining Rules” on page 41. 

Items of this type 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 interface after an item is branched, see the MKS Integrity 2007 User Guide. 

Branching is disabled by default and is available primarily for the use of MKS solution 

templates. 

When this option is selected, the Branch Rule button is enabled. Selecting this button 

displays the Edit Branch Rule dialog box, which closely resembles the Item Editability 

dialog box. This rule allows you to define the rules for the branching specific item types 

for users and user groups. 



Items of this type 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 interface after an 

item is labelled, see MKS Integrity 2007 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 Add Label Rule and Delete Label Rule 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. 



89


Editing Types 

90 

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. 

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 

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

Attributes, see “To create a type in the GUI” on page 84. 

Properties, see “Using Type Properties” on page 224. 

Change Packages, see “To create a type in the GUI” on page 84. 

Item Editability, see “Setting Item Editability for Types” on page 95. 

Field Relationships, see “Managing Field Relationships” on page 132. 

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

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

Presentations, see “Customizing Item Presentation” on page 170. 

References, see “To create a type in the GUI” on page 84. 

History, see “Viewing Administration History” on page 46 

4 To save your changes, click OK.

Copying Types 

Viewing Types 

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 

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: 















References, “To create a type in the GUI” on page 84 

History, see “Viewing Administration History” on page 46. 


You can view the details of an item type, but you can only view the details for one type at a 

time. 

Types 

91


Deleting Types 

92 

To view a type in the GUI 

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: 















References, “To create a type in the GUI” on page 84 

History, see “Viewing Administration History” on page 46. 

4 When you are finished viewing the information, click Close. 

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 

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.

Moving Types 


NOTE You can delete a type only if it has not appeared in your history, that is, if no 

one has created an item of that type. 

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 

Types 

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. 

3 Click Move Up or Move Down as required. 

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

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 

overridden for that type. 

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 2007 Installation and Configuration Guide. 

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 2007 


93


94 

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 and view custom presentation templates. 

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 and delete custom presentation 

templates. 

Example 

Edit field or states that reference type assigned 

to another administrator. 

Delete states that reference type assigned to 

another administrator, 

Delete a type. 

Note: Fields cannot be deleted. 

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: 

Type Fields Referenced 

Feature Date 

Description 

ReleaseID 

Defect Date 

Description 

Priority 

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.

Types 

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 

1 From the Types view, select the type you want to create a type administrator for. 

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

3 Click the Administrators node. 

To assign a specified user or group as a type administrator, see “Filtering Data” on 

page 17. You can assign more than one user or group as a type administrator. 

4 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 Item Editability for Types 

You can define the conditions that give users permission to edit items of a specific type. 

95


96 

To define item editability for a type in the GUI 

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 91, or “Editing Types” on page 90.) 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 41. For information on using the data filter, see “Filtering Data” on page 17. 

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 MKS Integrity items and e-mail notification are subject to 

type visibility rules. 

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.

Types 

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 2007 

Administration CLI Reference Guide. 

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 

Ranges 

Phases 

Display Pattern 

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

97


98 

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

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

To set a type override for fields 



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. 

You can set the following overrides: 

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. 

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

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 “To set possible values for a 

range data type” on page 122.

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 “To set possible values for a phase data type” on 

page 120. 

Types 

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

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

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

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. 

4 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 MKS Source change packages; 

however, you could set an override that allowed open MKS Source change packages in the 

Build state only when referenced by the Web Development type. 

99


100 

For more information on state attributes, see “Creating States” on page 78. 

To set a type override for states 



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. 

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 by 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 2007 User Guide. 

In MKS Source, 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 Source 


Types 

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 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 Source, 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. 

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 

101


Fields 

102 

use queries to search on fields that are not visible to them 

IMPORTANT In the Create Query and Column Sets dialog boxes, users are able to see 

the field name. In the Create Query dialog box, users are able to see all possible 

values within a given field, if that field is a picklist. 

Standard fields (Type, ID, Created By, Created Date, Modified By, Modified Date) are not 

subject to field visibility rules and always visible to users. 

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

MKS Integrity comes with a set of standard 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 105. 

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

NOTE Certain standard fields are always visible and cannot be edited. For these 

standard fields, only the Description and Position panels display. The standard 

fields are: Type, ID, Modified By, Created By, Modified Date, Created Date, Signed 

By, and Signature Comment. You can provide a description for each standard field.

Some fields can be edited by users, while others can only be set by MKS Integrity. Default 

MKS Integrity fields that you can include in your workflow are as follows: 

Field Name Editable? Description 

Type No Item type that pertains to particular workflow. 

ID No Unique ID assigned to each item upon creation. 

Created By No User who created item. 

Created Date No Date item was created. 

Modified By No User who last modified item. 

Modified Date No Date item was last changed. 

Summary Yes Brief summary of item, up to 250 alphanumeric 

characters. 

State Yes Step or stage of workflow process. 

Assigned User Yes User responsible for item. 

Assigned Group Yes Group responsible for item. 

Project Yes Project item belongs to. Projects are groupings of related 

items. 

Forward Relationships Yes Related child items. For more information on item 

relationships, see the MKS Integrity 2007 User Guide. 

Backward Relationships Yes Related parent items. For more information on item 

relationships, see the MKS Integrity 2007 User Guide. 

Signed By No User who provided electronic signature when item was 

changed. For more information, see “Setting Up 

Electronic Signatures” on page 218. 

Signature Comment No Any comments entered as part of electronic signature. For 

more information, see “Setting Up Electronic Signatures” 

on page 218. 

Attachment Yes Attachment(s) included with the item. For more 

information about creating attachments in items, see your 

MKS Integrity 2007 User Guide. 


Fields 

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

When naming a field, MKS Integrity allows you to use a secondary name—the display 

name—that appears on the GUI. 

103


Working in Fields View 

104 

Using the MKS Integrity Administration Client, you can manage MKS Integrity fields from 

one convenient location. Managing fields is carried out through the Fields view. 

To open the Fields view from the MKS Integrity Administration Client, expand the 

MKS Integrity 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: 


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

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

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. 

Available Menu Commands for Fields 

Through the Fields view, you can: 

edit the details for an existing field 

view the details for an existing field 

create a new field for use in MKS Integrity 

reposition, or change the order of presentation for, a field in MKS Integrity 

delete an existing field 

Fields 

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. 

105


Creating Fields 

106 

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

TIP To view the column for display names from the GUI, right click the column 

header, and select Display Names from the shortcut menu. 

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. 

To create a field in the GUI 

1 From the Fields view (see “Fields” on page 102), select Field > Create. The Create Field 


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

3 On the Values panel, from the Data Type list select a data type for the field. For details of 

the data type options, see “Setting Possible Values for Fields” on page 107. 

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. 

When you select a data type, the values the field can accept display below. For more 

information, see “Setting Possible Values for Fields” on page 107. 

MKS Integrity can also perform calculations between specific field types, storing the 

result as a read-only value in a computed field. To create a computed field, see “Creating 

Computed Fields” on page 284.

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

To set field relevance, click the Relevance tab. For more information, see “Setting 

Field Relevance” on page 124. 

To set field editability, click the Editability tab. For more information, see “Setting 

Field Editability” on page 127. 

To set field rules, click the Rules tab. For more information, see “Setting Field Rules” 

on page 128. 

5 When you are finished setting the field’s properties, click OK. 

Setting Possible Values for Fields 

The settings in the Values panel vary according to the data type you have selected. 

NOTE The Values panel is unavailable for standard fields, such as Type, ID, Created 

Date, Created By, Modified Date, and Modified By. 

To set possible values for an attachment data type 

Use the attachment data type for including attachments, such as design documents. 

NOTE Attachment fields cannot be specified in any type of rule. 

1 From the Create Field dialog box, select Attachment from the Data Type list. The 

attachment data type settings display. 

2 In the Display Style field, specify whether to display the attachment field in table format 

or comma separated values (CSV) format. The table format allows you to sort the 

attachments and manipulate the columns that display in the table. The CSV format 

displays comma separated links to the attachments. 

3 From the Display Rows field, specify the number of rows to display for the attachment 

field when editing the item. 


107


108 

To set possible values for an integer data type 

Use the integer data type for simple, countable items, such as call tracking numbers. 

1 From the Create Field dialog box, select Integer from the Data Type list. The integer 

data type settings display. 

2 If you want to specify default, minimum, and maximum values, select one or more of the 

Set Default Value, Set Minimum Value, and Set Maximum Value options, and type a 

number in the appropriate field. 

NOTE You can specify a maximum of nine digits. 

3 To show the field’s current value graphically as a proportion of its maximum value, 

select the Display as Progress Bar option. 

4 To configure the field as a computed field, select the Computation Values option, and 

configure the Computation Definition, Store to History Frequency, and How to Run 

Computations fields. For information on configuring these fields, see “Creating 

Computed Fields” on page 284. 

NOTE Selecting the Computation Values option disables the Set Default Value, Set 

Minimum Value, and Set Maximum Value options. 

5 To assign a format to integer field values, select or type a Display Pattern. For more 

information on, see “Display Patterns” on page 27. 


To set possible values for an item backed picklist data type 

Use the item backed picklist (IBPL) data type to share information in one or more items with 

other items. By creating an item type that acts as a table of information (known as the backing 

item type), then creating items of that type with a short text field containing the information 

you want to share, an IBPL field in another item type can display the values of the short text 

field as pick text. Whenever a short text field is updated in a backing item, all items with IBPL 

fields that reference the short text field value update to reflect the new value. 

For example, if you create a Department item type with a Manager field, then create several 

Department items to record the different departments and managers in your organization, 

Manager field values in all Department items appear as pick text in the Department Manager 

IBPL field in the Defect item type. If a Department item’s Manager field has a value of Fred 

and it changes to Ted, all Defect items with a value of Fred in the Department Manager field 

automatically update to display Ted.

NOTE 

The name of the IBPL field cannot be the same as the referenced field in the 

backing item type. 

Non-computed short text fields and computed short text fields can be referenced 

in an IBPL field. 

1 From the Create Field dialog box, select Item Backed Picklist from the Data Type 

list. The IBPL data type settings display. 

2 From the Backing Type list, select the item type containing the short text field you want 

to reference. 

3 From the Field Containing Pick Text list, select the short text field in the backing item 

type that you want to use as pick text. For example, if you select the Manager field and 

James Riley, Sherry Robertson, and Dan Evans are field values in some of the 

backing items, those names display as pick text in the IBPL field. 

Fields 

To populate the IBPL with backing items in specific states, select one or more states from 

the Active States list. Populating an IBPLwith 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 pick text entries in the IBPL. 

4 To allow multiple values in the IBPL, enable Allow Multiple Values. 


To set possible values for a field value attribute data type 

Building upon the concept of an item backed picklist field (IBPL), a field value attribute 

(FVA) data type allows you to share field information in an IBPL field’s backing item with 

other items, displaying the field information in the FVA field (for more information on IBPLs, 

see “To set possible values for an item backed picklist data type” on page 108). An FVA data 

type is useful for maintaining field information in one item and sharing the field information 

with other items. 

For example, if a Defect item has an IBPL field named Department Manager and a value of 

Jim, the FVA field named Extension to Call displays x626 because the backing Department 

item displays Jim in the Manager field and x626 in the Phone Extension field (the backing 

field for the FVA field). If the Extension to Call field value changes, the Phone Extension field 

value updates to reflect the new field value. 


You cannot create an FVA field backed by a range field that is based on a numerical field 

value attribute field. 

You cannot create an FVA field backed by a relationship field. 

Users cannot edit an FVA field if it has no backing relationship. 

109


110 

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 

non-FVA attachment fields. If you create a type with visible FVA and non-FVA rich 

content and attachment fields, MKS Integrity only displays visible attachment fields 

visible to the user in the GUI or Web interface. Fom the CLI, the user must know which 

attachment fields to use with rich content fields. 

1 From the Create Field dialog box, select Field Value Attribute from the Data Type 

list. The FVA data type settings display. 

2 From the Field list, select the field in the backing item type whose value you want to 

display in the FVA field. The field must be visible in the IBPL field’s backing item type. 


To set possible values for a pick data type 

The pick data type 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. 

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

To allow users to select multiple picklist values at one time, choose the Allow 

Multiple Values option. 

1 From the Create Field dialog box, select Pick from the Data Type list. The settings for the 

picklist data type display. 

2 To allow the option for multiple values in a given pick field, select the Allow Multiple 

Values option. Choosing multiple values allows users to select more than one item from 

the pick field. 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. 

To set a default value for the pick field, select the Set Default Value option, and type the 

default value in the text box. The default value can be any text string. 

To add items to the picklist, click Add. The Add Pick dialog box displays. 

Use the Label and Value fields to assign a text string and a number to the picklist item. 

Using the Active option, specify whether a picklist value is considered active or inactive 

in MKS Integrity. By default, the picklist value is active. To deactivate the picklist value, 

clear the Active check box. For more information on deactivating picklist values, see 

“Deactivating Picklist Values” on page 130. 

To assign an icon image to the item, 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 (width) by 16 (height) pixels. 

3 Click OK to close the Add Pick dialog box. The new item displays in the Picks list. By 

default, picklist items are sorted by picklist order. 

Fields 

To edit an item, select it from the Picks list, and click Edit. Change the item’s properties, 

and click OK. 

To change the order of an item in the list, select it, and click Move Up or Move Down. To 

sort the items in the list by alphabetical label, click Sort Alphabetically. To remove one or 

more items from the list that have not been saved yet, select them, and click Remove. 

4 Once you have added all of the desired items to the picklist, you can decide whether to 

set a default value. To do this, select the Set Default Value option and an item from the 

list. 


To set possible values for a floating point data type 

Use the floating point data type for numbers with decimals, such as performance data. 

1 From the Create Field dialog box, select Floating Point from the Data Type list. The 

floating point data type settings display. 

2 If you want to specify default, minimum, and maximum values, select one or more of the 

Set Default Value, Set Minimum Value, and Set Maximum Value options and type a 

number in the appropriate field. 

NOTE 

When editing a floating point field to set the default, minimum, or maximum 

value, you can enter a negative exponent using the E number notation, for 

example, -123.1E-3. 

You can specify a maximum of 15 digits, though when edited in the Web 

interface only 12 digits are simultaneously visible. 

3 To configure the field as a computed field, select the Computation Values option, and 






4 To assign a format to floating point field values, select or type a Display Pattern. For 

more information, see “Display Patterns” on page 27. 


111


112 

To set possible values for a logical data type 

Use the logical data type for Boolean items (ones that are either true or false), such as whether 

an item has been tested. 

1 From the Create Field dialog box, select Logical from the Data Type list. The logical data 

type settings display. 

2 If you want to specify a default value, select the Set Default Value option, and set it to 

either true or false. 

3 To configure the field as a computed field, select the Computation Values option and 




NOTE Selecting the Computation Values option disables the Set Default Value 

option. 


To set possible values for a date data type 

Use the date data type for dates, such as when a defect was fixed. Optionally, you can include 

the time. 

1 From the Create Field dialog box, select Date from the Data Type list. The date data type 

settings display. 

2 To include the time, select the Include time option. 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. 

3 To specify default, minimum, and maximum values, select one or more of the Set Default 

Value, Set Minimum Value, and Set Maximum Value options, and click Change. The 

Specify Date or Time dialog box displays. 



4 Select one of the following:

A date from the calendar. If the Show Time option is enabled, include a time from 

the calendar. 

today displays the current date and a time of 00:00:00 (midnight) when the item is 

submitted. This option displays only if the Include Time option is disabled. 

now displays the current date and time when the item is submitted. This option 

displays only if the Include Time option is enabled. 

none specifies an empty value for the date field. 

5 Click OK. The date data type settings display. 






To set possible values for a short text data type 

Fields 

Use the short text data type for any miscellaneous information, such as a comment field. This 

data type allows you to define suggestions. 

1 From the Create Field dialog box, select Short Text from the Data Type list. The short 

text data type settings display. 

2 To set a default value for the field, select the Set Default Value option, and type a default 

value. 

3 In the Maximum Length field, enter a maximum length for the field. 

When editing the maximum number of characters for a short text field, the following 

applies: 

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. 

113


114 

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 GUI and Web interface. However, 

when the user edits a field in the Web interface, only 70 characters are 

simultaneously visible in the editable box. 

4 To add a suggestion, click Add. The Add Suggestion dialog box displays. 

The short text data type allows you to define suggested values for the user. 

5 Type the suggestion text, and click OK. The new suggestion displays in the Suggestions 

list. 

6 To edit a suggestion, select it in the Suggestions list, and click Edit. 

7 To change the order of a suggestion in the list, select it, and click Move Up or Move Down. 

8 To remove one or more items from the list, select them, and click Remove. To remove all 

items, click Remove All. 





NOTE Selecting the Computation Values option disables the Set Default Value 

option. 


To set possible values for a long text data type 

Use the long text data type for any miscellaneous information. This data type includes an 

option for displaying rows. 

1 From the Create Field dialog box, select Long Text from the Data Type list. The long text 

data type settings display. 

2 To set a default value for the field, select the Set Default Value option, and type a default 

value. This can be any text string. 

NOTE If you enable the Rich Content option in step 6, a toolbar displays, allowing 

you to apply rich content. For more information on applying rich content, see the 

MKS Integrity 2007 User Guide.

Fields 

3 In the Maximum Length field, enter the maximum number of characters for the field. The 

maximum character length depends on your database type and setup. 

When editing the maximum number of characters for a long text field, the following 

applies: 

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. 

4 In the Display Rows field, specify how many rows should display in the Item Details. 

The maximum is 80 rows. 

5 Setting an option in the Logging field allows you to 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 for the Logging field: 

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. 

You may change the Logging field option when editing. 

115


116 

6 Long text fields support rich content. Rich content enhances the display of text in long 

text fields by adding formatted text, tables, background colors, images, and hyperlinks. 

To configure a long text field as a rich content field, select Rich Content. This option is 

enabled by default and does not support logging text fields. 

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

7 Images inserted into a rich content field using an attachment field are retrieved from a 

specified attachment field in the item. Select the Default Attachment Field that images are 

retrieved from. The default is the default Attachment field. 


To set possible values for a user data type 

The user data type specifies users that display in a drop-down list, such as users in a specific 

group. 

1 From the Create Field dialog box, select User from the Data Type list. The user data type 

settings display. 

2 To allow multiple users to be selected in the user list, enable Allow Multiple Values. 

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. 

3 To set a default value for the user list, enable Set Default Value. Then click the list, and 

select a 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 17. 

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.

To set possible values for a group data type 

Fields 

The group data type specifies groups that should display in a drop-down list, such as groups 

assigned to a specific project. 

1 From the Create Field dialog box, select Group from the Data Type list. The group data 


2 To allow multiple groups to be selected in the user list, enable Allow Multiple Values. 

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. 

3 To set a default value for the group list, enable Set Default Value. Then 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 17. 

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. 


To set possible values for a relationship data type 

1 From the Create Field dialog box, select Relationship from the Data Type list. The 

relationship data type settings display. 

117


118 

2 Under Types, select an item type that is to use the relationship field. The Available Types 

list is populated. 

From the Available Types list, select the item types that can be linked to using the 

relationship field, and add them to the Allowed Types. For example, to allow the field to 

be used to create relationships between documentation items and bugs, select Docs 

under Types and add Bugs to the Allowed Types. Then select Bugs under Types, and add 

Docs to the Allowed Types. 

Repeat the selection process for additional item types. 

If you want the system to prevent relationship loops from occurring, enable Cycle 

Detection. For more information, see the MKS Integrity 2007 User Guide. 

3 On the Forward and Backward tabs, define the fields used for forward and backward 

relationships. Forward relationships are relationships where the related item is a child of 

the original item. Backward relationships are relationship where the related item is a 

parent of the original item. 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. You can create a 

relationship from either the child or the parent, and the corresponding field in the 

related item is updated automatically.

4 Specify the following information: 

Fields 

In the Name field, type the 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. 

If you want the relationship field to contain links to multiple items, enable Multi 

Valued. For example, a field used to track defects on an item would need to allow 

multiple linked items; a field used to identify the feature being documented for a 

documentation item would only need to allow a single linked item. 

In the Display Style field, specify if to 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. 

In the Display Rows field, specify the number of rows to display for the relationship 

field when editing the item. 

In the Display Location field, specify whether the relationship field is displayed on 

the Fields tab or the Relationships tab of the Item Details view. 

5 Relationship flags are used to indicate when a related item has changed. To add 

relationship flags for the field: 

a) Click Add. The Add Relationship Flag dialog box displays. 

NOTE 

A user must be licensed for MKS Source 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 128. 

b) In the Name field, type the name for the relationship flag. 

c) In the Character field, type a 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. 

d) Specify the following: 

Click Select to 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. 

In the Enabled field, specify whether you are using this relationship flag. 

119


120 

To finish adding the relationship flag, click OK on the Add Relationship Flag dialog 

box. 

6 To save your changes, click OK on the Create Field dialog box. 

To set possible values for a phase data type 

The phase data type allows you to 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. 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, ...) 

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

1 From the Create Field dialog box, select Phase from the Data Type list. The phase data 


2 To add a phase to the Phases list, click Add. The Add Phase dialog box displays. 

3 Use the Label field to assign a text string to the phase. 

4 Under Available States, select the states that are included in the phase, and add them to 

the Phase States. 

IMPORTANT No two phases can use the same state. 

5 To assign an icon image to the phase, select Use Custom Image and browse for the image 

file. To have no image associated with the phase, 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 (width) by 16 (height) pixels. 

6 Click OK to close the Add Phase dialog box. The new phase displays in the Phases list. 

7 To edit a phase, select it from the Phases list, and click Edit.

8 Change the phase’s properties, and click OK. 

NOTE You cannot edit the Out of Phase phase. This phase identifies the states 

that are not included in any user defined phase. 

9 To change the order of a phase in the list, select it, and click Move Up or Move Down. To 

remove one or more phases from the list, select them, and click Remove. To remove all 

phases, click Remove All. 


To set possible values for a query backed relationship data type 

Fields 

The query backed relationship data type allows you to specify a named query that displays 

items meeting the query criteria as a read-only relationships field. This field extends the 

concept of the relationship field by displaying a large number of related items. For example, 

the Features field in a Project item would display all the Feature items that are returned by 

the Release_5_Features query. 

1 From the Create Field dialog box, select Query Backed Relationship from the Data 

Type list. The query backed relationship data type settings display. 

2 From the Query list, select a query. Only administrator queries appear in the list. 

3 The Field Correlation table allows you to return even more specific query results by 

correlating a field contained in the type containing the query backed relationship field 

and a field in the items returned by the query. 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 

121


122 

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. 

4 In the Display Style field, specify whether the query backed relationship field displays 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. 

5 In the Display Rows field, specify the number of rows to display for the query backed 

relationship field when editing the item. You can specify from five to 80 rows. 


To set possible values for a range data type 

The range data type allows you to categorize numeric value ranges in an associated numeric 

field (integer or floating point). 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

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 value limits can be overridden on a per type basis; however, you cannot 

override range category names and icons. 

1 From the Create Field dialog box, select Range from the Data Type list. The range data 


2 From the Associated Field list, select a numeric field to associate with the range field. A 

numeric field must be associated with the range field you create. 

NOTE You can associate a numeric field with any number of range fields. 

3 To add a range to the Ranges list, click Add. The Add Range dialog box displays. 

Fields 

4 Use the Label field to assign a text string to the range category. Range labels can be up to 

100 characters. 

5 In the Value field, 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. 

6 To assign an icon image to the item, 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 (width) by 16 (height) pixels. 

7 Click OK to close the Add Range dialog box. The new item displays in the Ranges list. 

8 To edit an item, select it from the Ranges list, and click Edit. 

9 Change the item’s properties, and click OK. 

10 To change the order of an item in the list, select it, and click Move Up or Move Down. To 

remove one or more items from the list, select them, and click Remove. To remove all 

items, click Remove All. 

123


124 


To set possible values for an SI project data type 

The SI project data type allows users to specify a related MKS Source project, optionally 

including a checkpoint revision or development path. By creating an MKS Source 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 MKS Source project metrics, see “Using Project 

Metrics” on page 257. For more information on external information functions and computed 

fields, see “Computed Expressions” on page 269. 

IMPORTANT 

Metrics are only maintained against project checkpoints; therefore, to generate 

metrics users must specify a checkpoint when they specify the MKS Source 

project. 

SI project fields cannot be specified in any type of rule. 

To allow users to specify a related MKS Source project when creating or editing 

an item, you must enable and properly configure the MKS Integrity and 

MKS Source integration. For more information, refer to the MKS Integrity Server 

2007 Installation and Configuration Guide. You must restart the server for this 

change to take effect. 

1 From the Create Field dialog box, select SI Project from the Data Type list. The SI 

project data type settings display. 


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

Fields 

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 

control user access to information. For more information on visibility rules, see “Setting 

Project Visibility” on page 230, “Setting Type Visibility” on page 96, and “Setting Field 

Visibility for Types” on page 101. 

NOTE Relevance rules are evaluated on the MKS Integrity Client’s time zone. 

To define field relevance in the GUI 

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 106 or “Editing Fields” on 

page 129. The Relevance panel displays. 

125


126 

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 and use them in column sets. 

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

4 Under Copy, copy relevance rules from another field. Do one of the following: 

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 

Fields 

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. 

NOTE Editability rules are evaluated on the MKS Integrity Client’s time zone. 

To define field editability in the GUI 

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

1 From the Create Field or Edit Field dialog box, click the Editability tab. For more 


page 129. The Editability panel displays. 

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 

127


128 

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, 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 41. 

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 

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 106 or “Editing Fields” on page 129. 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.

Editing Fields 

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 

Fields 

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 129. The Description panel displays. 

2 Type a text description of the specified field. 


You can edit field details, including editability, relevance, description, and position. 

To edit a field in the GUI 

1 From the Fields view (see “Fields” on page 102), 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 106. 

129


Viewing Fields 

130 

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. 

To determine all objects that reference the field, click the References tab. For 

information on the contents of the tab, see “Viewing Admin Object References” on 

page 220. 


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 

1 From the Fields view (see “Fields” on page 102), 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 106, and “To edit a field in the GUI” on page 129. 

NOTE You cannot change information that displays in a view mode. 

3 When you are finished viewing, click Close. 

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. 

By deactivating picklist values, the picklist is filtered to display only those picklist values that 

are currently active in MKS Integrity.

Deleting Fields 


Fields 

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. 

To deactivate a picklist value in the GUI 

1 From the Fields view (see “Working in Fields View” on page 104), 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 130). For a list of objects that can reference a field, see “Viewing Admin Object 

References” on page 220. 

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. 

131


Moving Fields 

132 

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

To delete a field in the GUI 

1 From the Fields view (see “Working in Fields View” on page 104), select the field you 


2 View the field (see “Viewing Fields” on page 130), and examine the References tab to 

ensure that there are no references to the field. 

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 104), 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 

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. They 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 that apply:

Fields 

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 101 and “Setting Project Visibility” on page 230. 

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. 

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. 

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 

Assigned Group Assigned User and 

State 

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. 

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. 

133


134 

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. 

In this view, you can customize the column set and sort to organize the field relationships to 

suit your needs. For more information on modifying column sets, see the MKS Integrity Client 

2007 Getting Started Guide. 

To open the Field Relationships view in the GUI 

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

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. 

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

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

Fields 

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

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: 

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

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

135


136 

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 from the active list. 

This selection populates the Assigned User or custom user field with all members 

in the specified Assigned Group or custom group in the item. 

Select Member Of, and the pane is populated with all the valid groups. Select a 

group from the active list. This selection populates the Assigned User or custom 

user field with all members in the specified group. 

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. 

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

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

4 Click OK. The field relationship displays in the Field Relationships view. 

5 To save the field relationship, click OK on the Edit Type dialog box. 

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

2 Click Delete. The Delete Field Relationship dialog box confirms the operation. 

Fields 

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. 

137


Workflows 

Workflow View 

138 

Each MKS Integrity 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 will use the 

new workflow. For more information on the Types view, see “Types” on page 82. 

2 Edit the selected type. For information on editing types, see “Editing Types” on page 90. 

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 

Menu Bar 

Tree Pane 

Title Bar 

Workflows 

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: 

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 

139


140 

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

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 

Creating Workflow 

window size and location 

Before using the Workflow view to create a workflow, you must first set up the following 

items: 

users (see the MKS Integrity Server 2007 Installation and Configuration Guide) 

groups (see the MKS Integrity Server 2007 Installation and Configuration Guide)

projects (see “Creating Projects” on page 232) 

states (see “Creating States” on page 78) 

types (see “Creating Types” on page 84) 

fields (see “Creating Fields” on page 106) 

To create a workflow in the GUI 

Workflows 

1 Open the Workflow view (see “To open the Workflow view in the GUI” on page 138). 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 142). 

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. 

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

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. 

141


142 

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 138 and “Viewing Workflow” on page 142). 

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

To save the workflow as an image file, click Save Diagram, then follow the prompts 

(see “Saving Workflow as Image” on page 146). 

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 138), 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. 

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 

Managing Workflow 

Workflows 

1 From the Workflow view (see “To open the Workflow view in the GUI” on page 138), 

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. 

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

2 To add additional states and state transitions, see “Creating Workflow” on page 140. 

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. 

143


144 

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 

1 Select the states from the workflow. For more information, see “Workflow View” on 

page 138. 

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

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.

Workflows 

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. 

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

2 In the Mandatory fields box, fields that are mandatory for some but not for all of the 

selected states display a gray checkmark. 

145


Printing Workflow 

146 

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. 

You can print out the workflow in a variety of sizes, depending on the zoom factor (for more 

information, see “Viewing Workflow” on page 142). 

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

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 

Workflows 

As part of the procedure for setting up MKS Integrity, you can use the MKS Integrity Admin 

Migration Wizard (migration wizard) to test your MKS Integrity configuration on a separate 

server before ultimately migrating a final configuration to your production MKS Integrity 

Server. 

For the purpose of migrating MKS Integrity admin 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. 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. The process helps you to work with the required admin objects to create an 

MKS Integrity workflow that functions for your environment. 

Staging 

Server 

Holds Lock on 

Production 

Admin Migration Server Configuration 

IMPORTANT Production and staging servers must be installed on separate machines. 

Both servers must be from the current release. 

By default, the MKS Integrity Server is always installed as a production server. 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 

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. Lock binding means that while you are testing your changes on the 

staging server, no changes can be made to MKS Integrity admin objects on the production 

server. At any time, you may also lock the staging server to prevent changes from being 

made in your test environment. 

1 

Copy Database 

Migrate Objects 

2 

Production 


Locked by Staging 

147


148 

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 objects migrated from the 

staging server function in the same way on the production server. You can migrate admin 

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 in 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, ViewSets, and item presentation templates. 

Admin objects that are migrated include the following: 

administrative charts 

administrative dashboards 

administrative queries 

administrative reports 

administrative report resources 

item presentation templates (including image files) 

trigger scripts 

ViewSets 

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

2 On a separate machine (the staging server), install the MKS Integrity Server you intend 

to use for testing and migrating your MKS Integrity admin objects. For more 

information, see “Installing and Configuring Staging Server” on page 150. 

3 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 152. 

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

Development 


Workflows 

4 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 


5 Configure MKS Integrity admin objects on the staging server and test your 

configuration. For more information, see “Testing MKS Integrity Configuration” on 

page 153. 

6 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 154. 

7 Migrate your configuration from the staging server to the production server. For more 

information, see “Using Admin Migration Wizard” on page 156. 

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. 

2 

Copy Database 

Test 


Holds Lock 

Holds Lock on 

on Test Server Migrate Objects Production 

Migrate Objects 

Locked by Test 

3 4 

Two Stage Server Configuration 

The basic steps for completing two stage 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 


2 On a separate machine (a staging server), install the MKS Integrity Server you intend to 

use for development of your MKS Integrity admin objects. For more information, see 

“Installing and Configuring Staging Server” on page 150. 

3 On a separate machine (a staging server), install the MKS Integrity Server you intend to 

use for testing of your MKS Integrity admin objects. For more information, see 

“Installing and Configuring Staging Server” on page 150. 

4 Copy databases and create administrative locks as follows: 

1 

Copy Database 

Production 


Locked by Test 

149


150 

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

b) Copy the database from the test staging server to the staging server you want to use 

for development. For more information, see “Copying MKS Integrity Database” on 

page 152. 

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

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

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

5 Configure MKS Integrity admin 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 MKS Integrity Configuration” on page 153. 

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

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 2007 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 create another MKS Integrity Server installation on a separate machine. For more 

information on installing an MKS Integrity Server, see the MKS Integrity Server 2007 


After installing the second MKS Integrity Server, configure additional properties to have it 

operate as a staging server. To create the staging server, set the property:

mksis.adminStagingServer=true 

Workflows 

in the /config/properties/is.properties file, where is 

the path to the directory where you installed the MKS Integrity Server. 

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 / 

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 MKS Integrity on production server. 

mksis.im.prodUser= Logon ID of administrator who is configuring admin objects on 

production server. 

mksis.im.prodPassword= Password of administrator who is configuring admin objects on 

production server. 

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. 

To specify a server to be a staging server, configure the following properties in the 

/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 MKS Integrity 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. 

E-mail Notification Upon Lock Break 

As administrator, you can also set certain parameters to ensure that you are notified 

whenever an administrative lock is broken. Set the parameters using the im diag command 

as follows: 

151


152 

where 

im diag --diag setStrPolicy --param=notificationsOnAdminLockBreak 

--param=xxx@company.com,yyy@company.com,zzz@company.com 

--param=notificationsOnAdminLockBreak specifies that an e-mail notification will 

be sent whenever an administrative lock is released. 

--param=xxx@company.com,yyy@company.com,zzz@company.com 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, you must manually edit the 

following property in the \config\properties\im.properties file: 

mksis.im.smtpserver=hostname 

where hostname is the host name or TCP/IP address of the SMTP server to send e-mail 

notifications through. 

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 “mksis” on page 388, and the 


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 the 

the production server, right clicking the MKS Integrity 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 154. 

IMPORTANT When starting the staging server for the first time, it will not start if 

differences are detected between it and the production server.

Workflows 

When the staging server starts, it first tests to see if its database is a restoration of the 

production server database. If the two databases are identical, the startup process completes 

successfully and the staging server database is marked as a test database. The server also tests 

to see if the Integrity Presentation Templates (IPTs) and trigger scripts 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 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 

/log/server.log file on the staging server. 

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 MKS Integrity admin objects on the staging server. 

Testing MKS Integrity Configuration 

Once the staging server is started and creates a lock binding to the production server, you can 

work with the required admin objects to create an MKS Integrity workflow that functions for 

your environment. Admin objects cannot be modified when the production server is locked. 

For detailed information on working with the various admin objects in MKS Integrity, see the 

following sections: 

For Managing Users, Groups, and Dynamic Groups, see the MKS Integrity Server 2007 


“MKS Integrity Projects” on page 229 




“Managing Field Relationships” on page 132 


“ViewSets” on page 49 

153


154 

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 other changes can occur to the 

production server while the migration wizard is performing its update. 

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 

MKS Integrity 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. 

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

Workflows 

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

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

2 Right click the MKS Integrity 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. 

155


156 

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. 

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

You launch the migration wizard from the MKS Integrity Administration Client by right 

clicking the MKS Integrity node and selecting Launch Admin Migration Wizard from the 

shortcut menu. The Launch Admin Migration Wizard menu item appears only 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 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. 

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

Migrating admin 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.

To migrate MKS Integrity admin objects to the production server 

NOTE Settings chosen from a previous migration session are not retained. 

1 Open the MKS Integrity Administration Client on the staging server. 

Workflows 

2 Launch the Admin Migration Wizard by right clicking the MKS Integrity node on the tree 

pane. The wizard displays. 

To continue, click Next. 

3 If the wizard detects admin objects with identical names on both the test and production 

servers, the objects are listed in the Identical Objects panel of the wizard. 

If this occurs, the migration wizard asks you to confirm that the two admin 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 objects, the Identical Objects panel does not 

display. Instead, advance to the next step. 

4 If the wizard detects changes to the production server (or test server depending on your 

configuration), the import panel displays the new admin objects (or users and groups) 

that must be imported into the staging server database. To import the admin objects, 

click Next. You cannot advance through the wizard without first importing the admin 

objects. 

NOTE Differences between servers for LDAP realm users appear on this panel. 

If there are no new admin objects on the production server, the import panel does not 

display. Instead, advance to the next step. 

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. 

157


158 

Selectable candidates for migration appear in the Candidates For Migration table. When 

you select an object in the Candidates For Migration table, its metadata displays in the 

lower 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 2007 


If there are objects that are referred by the selected object, those reference objects are 

highlighted in blue. If there are mandatory objects for the selected object, they are 

highlighted in pink. 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 migration. 

The following details are provided for admin objects in each table: 

Position indicates the order objects will be migrated in. 

Type indicates the type of admin object affected by the change, for example, State. 

Name indicates the name of specific admin 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). 

Workflows 

To include an object for migration, select it and then click > to move it to the Admin 

Objects to Migrate table. To select and move all objects for migration, click >>. Similarly, 

use < or


160 

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

You can also view a record of the staging server operations for the migration in the file 

/log/server.log. 

Considerations When Modifying Visibility, 

Editability, and Types 

MKS Integrity and MKS Source 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 MKS Source 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 MKS Source standalone change 

packages) 

For more information, see the following: 

“Setting Project Visibility” on page 230 

“Setting Field Visibility for Types” on page 101 

“Editing Types” on page 90

Deleting Admin Objects and Items 

Deleting Admin 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 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 objects that have references to other admin objects as long as the admin 

object you are deleting does not violate the restrictions mentioned earlier in this section. 

When deleting the admin 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 object. For 

information on identifying object references, see “Viewing Admin Object References” on 

page 220. 

IMPORTANT Contrary to other Admin Objects, you cannot delete a field if it has 

references to other admin objects, even if that field has not made a change to the 

database. You must remove the references before deleting the field. 

Only a user with administrative privileges can delete an item. Deleting an item removes its 

history, links, and attachments from the database. 

NOTE If you are using both MKS Integrity and MKS Source, do not confuse change 

package members with project or Sandbox members. 

161


162 

If you delete an item, change package members associated with that item are also deleted 

from the database, unless the change package member is referenced by another item. For 

example, if a change package is closed against one item and open against another item, then 

the change package member is not deleted. 

CAUTION The ID of a deleted item is never reused. Deleting an item is irreversible. 

To delete an Item in the GUI 

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 

Project Visibility” on page 230, “Setting Type Visibility” on page 96, and “Setting 

Field Visibility for Types” on page 101. 

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: 

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

For more information on setting permissions, see the MKS Integrity Server 2007 Installation and 


To set e-mail notification in the GUI 

1 In MKS Integrity, 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. 

163


164 

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. 

Remove deletes the selected 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 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 41. 

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. 

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 Select Session > Notifications. The Set Email Notifications dialog box displays. 

If you created a notification rule in the GUI that is too complex to view or edit in the Web 

interface, the Confirm Delete Complex Notification Rule dialog box displays. If not, 

proceed to Step 3. 

2 Select an option: 

If you want to keep the existing rule, click No. 

If you want to delete the existing rule and create a new one in the Web interface, 

click Yes. 

The Set Email Notifications dialog box displays. 

The e-mail address for your user ID automatically displays in the Email Address field. 

You can also type your e-mail address. 

165


166 

3 From the Type list, select an item type to be notified about. 

4 Click Add. The Set Email Notifications dialog box displays a list of notification options. 

5 Select one or more e-mail notification options: 

New submissions notifies you when a new item is submitted. 

Any modification notifies you when an existing item is modified. 

Item becomes assigned to me notifies you when an item is assigned to you. 

Item is assigned the following states notifies you when an item moves into one or 

more of the selected states, for example, Open and Closed. 

For example, selecting New Submissions and Item becomes assigned to me sends an 

e-mail notification to you when a new item is submitted, when an item becomes 

assigned to you, or when a new item assigned to you is submitted. 

The list of states you can select depends on the workflow implemented by your 

administrator. 

TIP To remove an item type from the notifications page, clear all of the options from 

the type. Click OK to close and save the notifications settings. The next time you 

open the Set Email Notifications dialog box, that item type is no longer visible. 

6 To select another item type to be notified about, repeat steps 4 to 6. 

7 To accept the changes made, 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: 

/config/properties/logger.properties 

where is the path to the directory where you installed the MKS Integrity 


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. 

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 

167


168

C HAPTER FIVE 

Customizing Workflow 

Item Presentation and Configuration 

5 

This chapter contains information on customizing the presentation of MKS Integrity 

items to users, as well as configuring how they appear in reports. Information on 

customizing MKS Integrity admin objects is also provided. 


“Customizing Item Presentation” on page 170 

“Customizing Rich Content Fields” on page 199 

“Customizing Report Presentation Templates” on page 201 

“Configuring Attachment Size Limits” on page 214 

“Configuring Limits for Queries” on page 214 

“Configuring Context Based Text Searching” on page 217 

“Setting Up Electronic Signatures” on page 218 

“Admin Objects” on page 219 

“Using Type Properties” on page 224 

169

Chapter 5: Customizing Workflow 


170 

The following table summarizes the available content for customizing MKS Integrity items: 


Use an item presentation template to customize 

how MKS Integrity items appear to users. 

Customize how reports are rendered through the 

use of report presentation templates. 

Configure how users use attachments for 

MKS Integrity items. 

Configure limits for how MKS Integrity items 

appear in queries. 

Configure how users search for items in 


Ensure confidentiality of electronic records by 

using electronic signatures. 

Learn about and manage MKS Integrity admin 

objects. 

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 MKS Integrity 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 

“Customizing Item Presentation” on page 170 

“Customizing Report Presentation Templates” on 

page 201 

“Configuring Attachment Size Limits” on 

page 214 

“Configuring Limits for Queries” on page 214 

“Configuring Context Based Text Searching” on 

page 217 

“Setting Up Electronic Signatures” on page 218 

“Admin Objects” on page 219 

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 


MKS Integrity saves your presentation template files in XML format under the following 

directory: 

/data/im/issue/templates 


Server. The templates directory is also backed up if you decide to upgrade the 


IMPORTANT The data/im directory, including your presentation templates, is 

automatically saved to a backup directory if you uninstall the MKS Integrity Server. 

To use your presentation templates with a new MKS Integrity Server, you will need 

to copy them to the same mksis/im/issue/templates directory on that server. 

Image files copied to the data/public_html directory are not backed up and 

must be restored manually. Therefore, it is important to retain copies of your 

required image files. 

Understanding Template Designer 

Presentation templates are customizable layouts for displaying items in MKS Integrity. 

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. 

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

NOTE You can only work with MKS Integrity presentation templates from the 

MKS Integrity Administration Client GUI. 

The following shows the main features of the template designer interface. 

171


172 

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 MKS Integrity 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.

Tool Function 

Create a new tab in the layout. 


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

Insert row below selected row. To delete row, select cell in that row and then 

click tool. 

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

Insert column to right of insertion point. To delete inserted column, first select 

cell in that column and then click tool. 

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. 

173


174 

Modifying Template Properties 

The Layout Properties dialog box allows you to configure styles and settings that can be 

applied globally to components of your template. 

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

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

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. 

175


176 

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. 

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 Swatches, HSB (Hue, 

Saturation, Brightness), or RGB (Red, Green, 

Blue). 

By default, background color is default as 


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. 

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. 

177


178 

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 Swatches, HSB (Hue, 

Saturation, Brightness), or RGB (Red, Green, 

Blue). 

By default, background color is default as 


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

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

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 

MKS Integrity 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. 

179


180 

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. 

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 MKS Integrity 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 MKS Integrity 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. 

181


182 

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

7 Add fields to the template (see “Adding Fields” on page 193). 

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 187 

“Working With Labels” on page 189 

“Working With Images” on page 194 

“Working With Tabs” on page 192 

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 

of the template with all your desired changes intact and continue editing. 

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

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. 

183


184 

For more information on templates for viewing, submitting and printing items, see 

“Templates for Viewing, Submitting, and Printing Items” on page 179. 

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 

of the template with all your desired changes intact and continue editing. 

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 196). When editing 

the default template, you can modify or delete the Relationships and Attachments tabs (see 

“Working With Tabs” on page 192). 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 

1 From the MKS Integrity Administration Client, expand the MKS Integrity 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 186 

“Working With Cells” on page 187 

“Working With Labels” on page 189 

“Working With Tabs” on page 192 

“Filtering Fields” on page 193 

“Adding Fields” on page 193 

“Working With Images” on page 194 

185


186 

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

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. 

187


188 

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

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 


189


190 

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

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 


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


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

191


192 

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


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. 

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 193). 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 181 or “Editing Presentation Template” on page 185). 

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 


for the Position property.

Task Operation 

Filtering Fields 


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 


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. 

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

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 

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. 

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

193


194 

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. 

4 Repeat this procedure until all desired fields are added to the grid. 

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

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: 

/data/public_html 


Server.

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: 

/data/public_html 


Server. 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 URL for the image location using 

the following syntax: 

http:// 

For example, an image file named corporate_logo.gif on the xyz-server would 

have the following URL: 

http://xyz-server:7001/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: 

/data/public_html/ 


Server, and is a subdirectory (created by you) 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. 

195


196 

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:// 

For example, the image file named corporate_logo.gif on the xyz-server would 

have the following URL: 

http://xyz-server:7001/corporate_logo.gif 

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

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. 

197


Deleting Presentation Template 

198 

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

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. 

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

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 

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 

Mandatory element that prefaces all elements in a rich content 

field. Other comments are removed. 

to align 

style, align 

 

size, width 

, , style 


200 

Element Attributes 

style, color 

style, align 

 

Converted to . 

 

 

 


 


 

style, align, border, width, cellpadding, cellspacing, 

summary, frame, rules, bgcolor, background 

 

style 

style, rowspace, align, height, width, bgcolor, valign, 

background 

 

CSS Definitions 

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: 

/data/im/richcontent/styles/screen

data/im/richcontent/styles/printer 

Removing and Transforming Style Definitions and Elements 

Customizing Report Presentation Templates 

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. 

You cannot override a rich content field’s CSS using the type field override or report 

definition. 


In MKS Integrity, 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. In MKS Source, 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 an MKS Integrity report, see the MKS Integrity 2007 User Guide. 

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. 

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. 

201


202 

MKS Integrity 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. 

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: 

/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 205. 

5 When you complete the necessary modifications to the template file, move it to: 

/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: 

/data/reports/styles/printer 

b) Place the screen style in: 

/data/reports/styles/screen 

c) Place the screen style sample in: 

/data/reports/styles/screen/samples

Report Elements 

d) Place the printer style sample in: 

/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: 

/data/public_html/images/logos 

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: 

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

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: 

/data/reports/ 

styles/screen 

Printer style CSS files are located in: 


styles/printer 

CSS files must be in CSS format with a .css 

extension. 

203


Element Description Location 

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. 

204 


recipes/images 

Note: Supported image types are GIF, JPEG, 

and PNG. 

logos A logo image to display in report. /data/public_html/ 

images/logos 

Note: Supported image types are GIF, JPEG, 

and PNG.

Report Tags 

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. 

205



206 

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.


Attribute Tags 


Displays Date Format field in Attributes panel of Report Wizard, for example: 

 

MM/dd/yy expands to 01/30/07. 

MMM dd yyyy expands to Jan 30 2007. 

MMMM dd, yyyy expands to January 30, 2007. 

Displays Date Time Format field in Attributes panel of Report Wizard, for 

example: 

MM/dd/yy expands to 01/30/07. 

MMM dd yyyy expands to Jan 30 2007. 

MMMM dd, yyyy expands to January 30, 2007. 

hh:mm:ss expands to hour, minute, and second using 24 hour clock. 

a (or p) expands to a.m. or p.m. 

z expands to time zone. 

Displays current date in report based on selected date format. 


Style Tags 

Displays screen style CSS file in Style panel of Report Wizard. Style can be 

selected for viewing report in browser window, for example: 

 

Displays printer style CSS file in Style panel of Report Wizard. Style can be 

selected for printing report, for example: 

 


/ 

 

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: 



208 

Logo Tag 

Displays logo image in Logo panel of Report Wizard, for example: 

,or 

 


Field Tags 

Display value of specific field, such as State. Replace fieldname with name 

of field. 

You can repeat tag for field name, for example, entering one field name 

instance for displayed text and one for hyperlink. 

Field names are case-sensitive because you can create two fields with same 

name but with varying case. 

You cannot use < (less than) symbol in field tags; otherwise, values for fields 

after < symbol do not appear in report. 

 

 

 

 

 

 


 

/ 

 

 

/ 

/ 

 

/ 

 

Loop all occurrences of value for field specified in , for 

example, report displays all items that have state of Submit. 

iteratefields tag prompts user for list of fields to include in report. 

Information between opening and closing iteratefields tags then 

expanded for each field selected. 

To use fields chosen by user, specify . 

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. 

&attachmentfielddisplayname displays name of attachment fields in 

report. 

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

&timeentryfielddisplayname displays name of time entry fields in 

report. 

&timeentryfieldname displays value of time entry fields in report. 

Required to report on relationship time entry information, with time entry tags 

placed between tags. 

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. 

&relationshipfielddisplayname displays related field name. 

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

 

/ 

 

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. 

209



210 

/ 

 

/ 

 

/ 

 

/ 

 

/ 

 

 

 

 

 


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


 

header_and_or_footer_bl 

ocks 

 

 

 

 

 

group_computation_strin 

g 

 

 

computation_string 

 



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. 

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: 

computedValueDisplayPattern specifies display pattern for computed 

value. 

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. 

211



212 

/ 

 

 

/ 

 

 

/ 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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. 

&genericcpfielddisplayname displays cp attribute name in report. 

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

&genericcpentryfielddisplayname displays cp entry attribute name in 

report. 

&genericcpentryfieldname displays cp entry value in report. 

Display change package details for items included in report. 

These tags provide details for MKS Integrity and MKS Source change 

packages. 

Display change package entry details for items included in report. 

These tags provide details for MKS Integrity and MKS Source change 

packages. 

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.


Computed Expression Tags 


Performs calculation between fields in single item. For information on creating 

computed expressions, see “Computed Expression Types” on page 270. 

 

computation 

 

computation 

 


/ 

 

Performs calculation between fields in group of items. For information on 

creating computed expressions, see “Computed Expression Types” on 

page 270. 

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 “To set possible values for an 

integer data type” on page 108. 

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. 

213



Configuring Attachment Size Limits 

214 

Grouping and Sorting Tags 

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: 

 

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: 

/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 2007 Installation and Configuration Guide. 

Configuring Limits for Queries 

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.

Configuring Limits for Queries 

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 under /config/ 

properties/im.properties 

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. 

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 


215


Query Timeouts for Groups 

216 

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 2007 Installation and Configuration Guide. You can also modify the group 

query timeout setting while editing a group. 

Maximum Query Item Count 

As administrator, you also 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.maxQueryIssueCount in the file: 


The mksis.im.maxQueryIssueCount property governs the computation and return of 

queries run by MKS Integrity, and silently limits the returned item count to the set value. The 

setting applies to queries, reports, and charts. The minimum value is 100, and the maximum 

value is unlimited. By default, mksis.im.maxQueryIssueCount=10000. For more 

information on configuring the property for mksis.im.maxQueryIssueCount, see the 


NOTE Setting the mksis.im.maxQueryIssueCount property controls the total of 

all pages independent of the client’s page size.

Configuring Context Based Text Searching 

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 2007 User Guide. 

The property for configuring context based text searches is mksis.im.contextSearch 

found in file: 



Server. By default, mksis.im.contextSearch is set to true. 

IMPORTANT For information on the databases that support the text search feature, 

see the MKS Integrity Server 2007 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 

2007 Installation and Configuration Guide and the MKS Integrity Server 2007 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 under /config/properties/im.properties as 

follows: 

mksis.im.contextSearch.syncInterval=30 

NOTE This property is ignored for databases that do not require it. Currently only 

the Oracle database uses it. 

217


218 

Setting the syncInterval 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 MKS Integrity event triggers. For general information 

on event triggers and how to use them, see “MKS Integrity Event Triggers” on page 323. The 

electronic signature trigger must be set up as a rule-based 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. 

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.

Admin Objects 

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: 

/data/documentation/javadocs/triggers/index.html 

However, you should not have to change any of the calls to these methods. 

Admin Objects 

Admin objects provide a way to manage specific MKS Integrity objects through the 

MKS Integrity Administration Client, as well as to migrate them using the Admin Migration 

Wizard (see “Testing Workflow With Admin Migration Wizard” on page 147). 

Converting User Objects to Admin Objects 

You may want to convert some user objects to admin objects to control access to them by 

users or so that they can be migrated. Access to admin objects is controlled by the 

CreateSharedAdmin permission. Admin objects are migrated using the Admin Migration 

Wizard (see “Testing Workflow With Admin Migration Wizard” on page 147). 

Note the following about converting user objects to admin objects: 

Once you convert a user object to an admin object, you cannot convert it back. 

The creator of the original user object does not retain any special rights to that object 

after it is converted to an admin object. 

Administrators can modify admin objects in any way. 

You can migrate admin objects as part of the admin migration process. 

Admin objects are subject to the lock when the production server is locked. 

219


220 

Admin objects display in the MKS Integrity Administration Client. 

You can share Admin objects with users who are not administrators to view or edit. 

You can convert user objects queries, charts, reports, and dashboards to admin objects. When 

those objects are created from the MKS Integrity Administration Client, they are always 

admin objects. However, objects created from the MKS Integrity Client can be converted to 

admin objects by editing them in the MKS Integrity Client, and then selecting the Is Admin 

option. For details on editing queries, charts, reports, and dashboards, see the MKS Integrity 


Once the object has been converted to an admin object, it appears in the corresponding 

subview in the MKS Integrity view of the MKS Integrity Administration Client (see “Tree 

Pane” on page 14). For example, admin queries appear in the Queries view that is a subview 

of the MKS Integrity view (see “Queries View” on page 223). 

NOTE If you copy an admin object such as an admin query from the MKS Integrity 

Administration Client, the Is Admin option is selected and cannot be changed. If you 

copy an admin object from the MKS Integrity Client, the Is Admin option is cleared 

by default in the copy. You must select that option for the copied object to be an 

admin object. 

Viewing Admin Object References 

When editing and viewing admin objects in the MKS Integrity Administration Client, you 

can view all objects that reference that object. You can then use that information to minimize 

the impact of editing or deleting that object. 

To determine all objects that reference the object, click the References tab. The References 

panel displays the following information:

Charts View 

Admin Objects 

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. 

Creator displays the user ID that was logged as creating the object reference. 

Using the MKS Integrity Administration Client, you can manage admin charts from one 

convenient location. Managing admin charts is carried out through the Charts view. 

To open the Charts view from the MKS Integrity Administration Client, expand the 

MKS Integrity node, and select Charts. The Charts view displays. 

221


Dashboards View 

222 

By default, the data filter in the Charts view displays all admin charts. You can search for a 

specific chart by typing in the text filter. For more information, see “Filtering Data” on 

page 17. To convert user charts to admin charts, see “Converting User Objects to Admin 

Objects” on page 219. 

From the Chart menu, you can run, create, copy, delete, edit, and view the definition of 

admin charts. For information on performing those tasks, see the MKS Integrity 2007 User 


For information on the using the References tab when editing or viewing Admin Charts, see 

“Viewing Admin Object References” on page 220. 

Using the MKS Integrity Administration Client, you can manage admin dashboards from one 

convenient location. Managing admin dashboards is carried out through the Dashboards 

view. 

To open the Dashboards view from the MKS Integrity Administration Client, expand the 

MKS Integrity node, and select Dashboards. The Dashboards view displays. 

By default, the data filter in the Dashboards view displays all admin dashboards. You can 

search for a specific dashboard by typing in the text filter. For more information, see 

“Filtering Data” on page 17. To convert user dashboards to admin dashboards, see 

“Converting User Objects to Admin Objects” on page 219.

Queries View 

Reports View 

Admin Objects 

From the Dashboard menu, you can run, create, copy, delete, edit, and view the definition of 

admin dashboards. For information on performing those tasks, see the MKS Integrity 2007 

User Guide. 

Using the MKS Integrity Administration Client, you can manage admin queries from one 

convenient location. Managing admin queries is carried out through the Queries view. 

To open the Queries view from the MKS Integrity Administration Client, expand the 

MKS Integrity node, and select Queries. The Queries view displays. 

By default, the data filter in the Queries view displays all admin queries. You can search for a 

specific query by typing in the text filter. For more information, see “Filtering Data” on 

page 17. To convert user queries to admin queries, see “Converting User Objects to Admin 


From the Query menu, you can run, create, copy, delete, edit, and view the definition of 

admin queries. For information on performing those tasks, see the MKS Integrity 2007 User 


For information on the using the References tab when editing or viewing Admin Queries, see 


Using the MKS Integrity Administration Client, you can manage admin reports from one 

convenient location. Managing admin reports is carried out through the Reports view. 

To open the Reports view from the MKS Integrity Administration Client, expand the 

MKS Integrity node, and select Reports. The Reports view displays. 

223


224 

By default, the data filter in the Reports view displays all admin reports. You can search for a 

specific report by typing in the text filter. For more information, see “Filtering Data” on 

page 17. To convert user reports to admin reports, see “Converting User Objects to Admin 


From the Report menu, you can run, create, copy, delete, edit, and view the definition of 

admin reports. For information on performing those tasks, see the MKS Integrity 2007 User 


For information on the using the References tab when editing or viewing Admin Reports, see 


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 91) in 

the MKS Integrity Administration Client GUI. To view type properties, click the Type 

Properties node. 

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 90 or “Creating Types” on page 84) in the MKS Integrity Administration 

Client GUI. To define type properties, click the Type Properties node. 

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. 

Using Type Properties 

Value contains the definition of the type property (see “Defining Type Properties” on 

page 224). 

Description contains an optional description for the type property. 

Operations for Type Properties 

You can perform the following operations on type properties from the type properties pane 

(see “Defining Type Properties” on page 224): 

Operation Procedure 

Create type property Click Create. The Create a type property dialog 

box displays. 

For information on fields, see “Type Property 


Edit type property Select the type property, and click Edit. The 

Edit a type property dialog box displays. 



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. 

225


226

C HAPTER SIX 

Projects 

Using Projects to Manage Change and Source 

6 

This chapter contains information on using projects with MKS Integrity items and 

MKS Source members. It is important to understand that projects in MKS Integrity work 

differently from projects in MKS Source, and that the two kinds of projects do not 

interact with each other. 



“MKS Source Projects” on page 242 

227

Chapter 6: Projects 


228 

The following table contains a summary of what MKS Integrity project information is 

available to you: 


Manage MKS Integrity projects, including 

creating and editing. 

Learn how to work with the MKS Integrity 

projects view. 


“Projects View” on page 229 

Use MKS Integrity project metrics. “Managing Project Metadata” on page 237 

Deactivate MKS Integrity projects that are no 

longer needed or in use. 

Assign an MKS Integrity administrator for a 

project. 

“Deactivating Projects” on page 239 

“Assigning MKS Integrity Project Administrator” 

on page 240 

The following table contains a summary of what MKS Source project information is available 

to you: 


Learn what interfaces are available to you for 

working with and administering MKS Source 

projects. 

“MKS Source Interfaces” on page 242 

Organize your MKS Source projects. “Organizing Your Projects” on page 243 

Work with MKS Source projects, such as 

creating, importing, importing members, 

dropping, restoring to a checkpoint, deleting, and 

restoring deleted projects. 

“Working With Projects” on page 244 

Use MKS Source project metrics. “Using Project Metrics” on page 257 

Use MKS Source subprojects. “Working With Subprojects” on page 260 

Share MKS Source archives with MKS Source 

projects. 

“Sharing Archives With Other Projects” on 

page 265


Projects View 


With MKS Integrity, you can create projects and subprojects (or child projects) as needed. 

Projects allow you to group items according to undertakings that are defined in your 

organization. The MKS Integrity projects created by you then become available for selection 

in the Project field—a default field in MKS Integrity. 

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 MKS Integrity project 

administrators for a specified project. For more information on project administrators, see 

“Assigning MKS Integrity Project Administrator” on page 240. 

Using the MKS Integrity Administration Client, you can manage MKS Integrity projects from 

one convenient location. Managing projects is carried out through the Projects view. 

To open the Projects view from the MKS Integrity Administration Client, expand the 

MKS Integrity 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 17) 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 Projects” on page 232. 

229


230 

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 project name itself. 

NOTE If at least one project is shared with each group, the user and group fields are 

available to users when submitting items. 

If you double click a project, the Project dialog box displays for the selected project 

allowing you to view the properties for that project. For more information on viewing 

projects, see “Viewing Projects” on page 236. 

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. 

When creating an MKS Integrity 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 240. 

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 Projects 

Through the Projects view, you can: 

edit the details for existing projects 

view the details for existing projects 

delete projects 

create new projects for use in MKS Integrity 

create a child project 

reparent an existing project 

create a backing item 

edit the backing item 

view backing item details 

Setting Project Visibility 

Project visibility allows you to control access to information throughout your organization. 

Through MKS Integrity, you can manage 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 MKS Integrity 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 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. 

231


232 

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. 


If at least one project is shared with each group, the user and group fields are available to 

users when submitting items. 

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. 


MKS Integrity project administrators for that project. 

Creating Projects 

You can create projects for use in MKS Integrity. Projects allow you to group items according 

to undertakings that are defined in your organization. MKS Integrity projects created by you 

then become available for selection in the Project field—a default field in MKS Integrity. 


MKS Integrity project administrators for that project. For more information on project 

administrators, see “Assigning MKS Integrity Project Administrator” on page 240.

To create a new project in the GUI 


1 From the Projects view (see “Projects View” on page 229), select Project > Create. The 

Create Project dialog box displays. 

2 In the Name field, type a name for the new 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 Project Metadata” on page 237. 

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 

Projects” on page 239. 

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. 

233


234 

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


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. 

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. 

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


236 

To edit a project in the GUI 

1 From the Projects view (see “Projects View” on page 229), select the 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 Project Metadata” on 

page 237. 

3 Edit the project as necessary. For more information on the fields in this dialog box, see 

“To create a new project in the GUI” on page 233. 

4 To determine all objects that reference the project, click the References tab. For 


page 220. 

5 To view a history of administrative changes for the project, click the History tab. The 

record of changes displays. 


Viewing Projects 

You can view project details. The details are not editable, and you can only view the details 

for one project at a time. 

To view project information in the GUI 


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 new 

project in the GUI” on page 233. 

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 


page 220. 

4 To view a history of administrative changes for the project, click the History tab. The 

record of changes displays. 

5 When you are finished viewing, click Close.

Deleting Projects 


You can delete an MKS Integrity 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 project in the GUI 


delete. 

2 Select Project > Delete. A confirmation dialog box displays. 


Reparenting Projects 

After creating a project, you can move it from one location within your project hierarchy to 

another by reparenting it. 

To reparent a project in the GUI 

1 From the Projects view (see “Projects View” on page 229), select Project > Reparent. The 

Reparent Projects dialog box displays. 

2 Drag the project you want to move to the target folder. 


Managing Project Metadata 

MKS Integrity 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 

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

237


238 

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 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 project with an Item 

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

3 Create a project that you want to link to a Project item (see “Creating Projects” on 

page 232).


4 With the new project selected in the Projects view, select Item > Create Backing Item. The 

Create Item dialog box displays. 

NOTE 

Deactivating Projects 

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 

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

Setting a 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. 

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 project in the GUI 


edit. 

2 Select Project > Edit. The Edit Project dialog box displays. 

3 To deactivate the project, clear the Active check box. 

239


240 

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, 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 objects (see “Viewing Admin 

Object References” on page 220). 

MKS Integrity project administrators are allowed to edit and view 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 2007 Installation and Configuration Guide. 

MKS Integrity 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 MKS Integrity 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 2007 Installation and Configuration 


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 2007 


The following table summarizes the basic functionality available to the project administrator: 

Project administrators can: Project administrators cannot: 

Create new subproject (child project) in 

MKS Integrity project they are assigned to. 

Edit MKS Integrity 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 

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 

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. 

Create top level MKS Integrity project or create 

users, groups, dynamic groups, states, types, 

fields, or triggers. 

Edit any other MKS Integrity objects such as 

users, groups, states, types, fields, or triggers. 

View states, types, fields, or triggers. 

Delete subproject they have created. Delete top level MKS Integrity project. 

Create top level MKS Integrity project (if 

CreateProject permission is allowed). 

Assign another project administrator or view 

administrator information for project they do not 

administer. 

241


242 

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


MKS Source functionality provides projects to manage members. MKS Source projects are 

separate from MKS Integrity projects, and are accessed through all interfaces (see 

“MKS Source Interfaces” on page 242). 

MKS Source Interfaces 

MKS Source is accessible in three interfaces: MKS Integrity Client GUI, Web interface, and 

command line interface (CLI). 

The MKS Integrity Client GUI 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 Source 2007 User Guide. All MKS Source 

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

The MKS Source Web interface allows you to perform key project management tasks. You do 

not need to install the MKS Integrity Client to access the MKS Source Web interface. To open 

the MKS Source 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 Source 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 projects, Sandboxes, and members, and to configure MKS Source. 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 

MKS Source 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 Source to manage the 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 Source is also the easiest. If you follow 

these guidelines, MKS Source 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. 

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 Source 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 Source 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 2007 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 


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. 

243


244 

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 Source 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: 

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 Source 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 

Code 

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 Source 2007 User Guide. 

To create a project, select Project > Create. 

Project 

Directory 

Resource 

Directory 

rcs 

Directory 

rcs 

Directory 

Header 

Directory 

rcs 

Directory

Keep the following points in mind when creating a project: 


When you specify the name of the new project, MKS Source automatically assigns the 

.pj file extension. If you specify a .pj file extension in uppercase or mixed case, 

MKS Source replaces that file extension with the correct lowercase .pj file extension. If 

you specify a file extension other than .pj, MKS Source appends the .pj file extension 

to the file name. For backwards compatibility, you can import projects and subprojects 

that do not have the .pj file extension. 

A single project name can be used only once in the same location. 

For case-insensitive repositories, MKS Source does not distinguish between 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 Source 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 Source 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 Source confirms that the project is created. 

NOTE MKS Source 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 Source 

2007 CLI Reference Guide. 

Importing Projects 

You import projects if you need to do the following: 

restore projects that were dropped in earlier versions of MKS Source (Source Integrity) 

245


246 

migrate projects from Source Integrity Standard (an earlier version of MKS Source) 

Importing a project registers it with the MKS Integrity Server. Once a project is imported, 

MKS Source 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 Source 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 project from an earlier version of MKS Source, once a project has been 

imported you may not perform commands on it using an older version of MKS Source. If for 

some reason you need to use an earlier version of MKS Source 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 Source. 

If you are importing an existing Source Integrity Standard project that includes out-of-tree 

members or subprojects, MKS Source 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 “si diag” on page 386. 

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 project that is already registered. 


For case insensitive repositories, MKS Source does not distinguish between project 

names that differ only in case. For example, if project.pj is already registered in C:/ 

Aurora_Program, you cannot import PROJECT.pj into C:/Aurora_Program. This 

results in an error and MKS Source 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 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 2007 Installation and Configuration 


To import a MKS Source 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 Source 2007 CLI Reference Guide. 

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

or server resident files must be imported to register them with the MKS Integrity Server. 

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 Source 2007 User Guide. 

NOTE The Import Member command is not supported for database repositories. 


The 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 


247


248 

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

Example 

You have a directory that contains numerous files and subdirectories, and you want to add 

this directory to an MKS Source 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 

MKS Source 2007 User Guide. 

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 MKS Source 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 

MKS Deploy. For more information, see the MKS Deploy 2007 Administration Guide. 

9 To modify the Import Member options, click Options. For detailed information on the 

Import Member options, see the MKS Source online help.


10 To complete the operation, click OK. To make changes, click Back. The members display 

in the Project or Sandbox view. 

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 Source to confirm the recurse option, use 

--confirmrecurse) 

NOTE For a complete list of command options, see the MKS Source 2007 CLI 


Dropping Projects 

When a project has outlived its usefulness or just does not belong on the MKS Integrity 

Server anymore, you can remove it. 

To drop a 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. 

249


250 

To drop a 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 project unregisters it from the MKS Integrity Server, but it does not delete the 

project. Dropped projects can be added back into MKS Source. 

For more information on adding projects, see the MKS Source 2007 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 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 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 Source 2007 User 

Guide). 

How Restore Project Command Works 

MKS Source performs the Restore Project command as follows:

A checkpoint is performed on the current project revision. 

The project is restored to the target revision. 

A final checkpoint of the restored revision is made. 


Therefore, for each 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 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 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 2007 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 


251


252 

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 


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. 

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. 

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. 

253


254 

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. 

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 exports marked files from the database to the file system using the 

--dump subcommand. If projects are marked, the command recursively exports the 

projects into file system archives (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. 

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. 

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 “si diag” on page 386. 

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 2007 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 exports the projects into file system archives 

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

255


256 

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

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

command then exports the archives into file system archives.


--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. For more information 

on si migrate, see the Database Repository Migrator document. 

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 Project Metrics 

You can track metrics for top-level MKS Source projects and calculate them through event 

triggers. Calculated metrics can be viewed for an MKS Source project or through a computed 

field on an MKS Integrity project item. Metrics provide information on a project as of a 

specific checkpoint. 

257


258 

MKS Source 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 Provided by MKS Source 

MKS Source 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 MKS Integrity project item that is associated with 

the MKS Source project. The MKS Integrity project item must have an si project data type 

field that links it to the MKS Source 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 MKS Source project in the corresponding MKS Integrity project item, you would create 

a Number of Members field with the following expression: 

SIMetric("siproject-name","Number of Members") 

You could checkpoint the MKS Source 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 

MKS Integrity project item. 

For more information on creating si project fields for MKS Integrity items, see “Creating 

Fields” on page 106. For more information on creating computed fields for MKS Integrity 

items, see “Creating Computed Fields” on page 284. 

Using Third Party Metrics Tool 

You can use a third party tool to track additional MKS Source metrics. Metrics tracked by a 

third party tool must be defined in MKS Source 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 2007 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 /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. 

1 JavaNCSS is supported but not shipped with MKS Source. 

259


260 

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 Source 2007 CLI Reference Guide. 

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 Source allows you to create large 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. 

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 or creating a change package, see the 

MKS Source 2007 User Guide. For detailed information on the Create Subproject options, see 

the online help. 

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. 

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 Source 2007 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 2007 Getting Started Guide. 

Using Change Packages 

For information on the Change Package field and creating a change package, see the 


261


262 

Adding Shared Subprojects 

A shared subproject is a subproject that is a member of more than one project. MKS Source 

allows you to 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 Source 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 Source) are detected as they are accessed by MKS Source 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. 



Guide.


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 2007 Getting Started Guide. 

Specifying Destination Directory 

When you type the subdirectory for the shared subproject, the subproject name must reside 

in the project directory. 




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: 

263


264 

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 Source) are detected as they are accessed by MKS Source 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.




Configuring Subproject Using CLI 

For information on how to configure a subproject in the CLI, see the 

si configuresubproject command in the MKS Source 2007 CLI Reference Guide. 

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 MKS Source 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. 

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 Source allows you to control archive sharing. For more information on the permissions 

required to restrict archive sharing, see the MKS Integrity Server 2007 Installation and 


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 

265


266 

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

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. 

267


268 

Changes to build specifications 

This solution requires changes to build specifications because working file locations are 

changed. 

MKS Source can manage source files anywhere on your server’s repository. MKS Source 

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 270 

“Computed Expression Rules” on page 271 

“Creating Computed Fields” on page 284 

“Calculating Static Computed Fields” on page 287 

“Using Computed Fields to Chart Historical Trends” on page 287 

“Scheduling Computation Times” on page 290 

“Using Computed Fields to Calculate State Metrics” on page 290 

“Security” on page 292 

“Performance and Scalability” on page 293 

269

Chapter 7: Computed Expressions 


270 

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 270 

Construct rules for computed expressions. “Computed Expression Rules” on page 271 

Create a computed field. “Creating Computed Fields” on page 284 

Calculate a static computed field. “Calculating Static Computed Fields” on 

page 287 

Chart historical trends. “Using Computed Fields to Chart Historical 

Trends” on page 287 

Calculate state metrics. “Using Computed Fields to Calculate State 

Metrics” on page 290 

Understand implications on performance and 

scalability of the MKS Integrity Server when 

using computed expressions. 

“Performance and Scalability” on page 293 

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

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

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

271


Boolean Operators 

272 

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. To specify an empty field value as zero, use the isEmpty function. For example: 

isEmpty("QA Time", 0) + isEmpty("Development Time", 0) 

allows you to add two time durations and retrieve a result even if one of the values is empty. 

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

Date expressions accept all standardized date and timestamp formats. 

Timestamp Operations 

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

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. 

273


User and Group Fields 

Data Conversion 

Function Classes 

274 

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: 

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 Functions” on page 275. 

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 “Aggregate 

Functions” on page 276. 

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 “Text Functions” on page 277. 

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 “External Information 

Functions” on page 279. 

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) 

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 

275


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. 

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" 

IsType(typename[, ...]) 

Returns true if item any of types specified in its argument list. 

IsState(statename[, ...]) 

Returns true if item’s state any of states specified in its argument list. 

To specify unspecified state, type "Unspecified", for example, 

IsState("Unspecified"). 

276 

Arithmetic Functions 


DateDiff(starttime, endtime) 

Returns number of seconds between two dates with times. If starttime larger than 

endtime, result positive, otherwise negative. 

Aggregate Functions 

Type in expression 

Timestamp 

Timestamp 

Boolean 

Boolean 

Integer 


sum(numeric-expression) 

Adds expressions calculated against each item aggregation running against. 

avg(numeric-expression) 

Adds expressions calculated against each item aggregation running against, then divide 

by number of non-empty entries. 

Integer or floating point, 

same as expression 

Floating point

min(numeric-expression or timestamp) 

Finds smallest of expressions from each item 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 aggregation running against. 

emptyint() 

Returns an empty value in an interger 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. 

emptygroup() 

Returns an empty value in a group field. 

Text Functions 


Integer, float point, or 

timestamp same as 

expression 

Integer, floating point, 

or timestamp same as 

expression 

Integer 


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. 

Aggregate Functions 


none 

none 

none 

none 

none 

none 

none 

none 

Text 

Integer 

Text 

277


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 

ToText(number-expression) 

Converts number to string. 

278 

Text Functions 


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 

Text 

Integer 

Text 

Text 

Text 

Text 

Text

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 

279


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 MKS Source project. For more information on 

MKS Source metrics, see “Using Project Metrics” on page 257. 

SIMetricCount(siproject-field-name, metric name) 

Returns number of items that make up metric value for MKS Source project. 

DaysInState(state-name) 

Returns number of days item in specific state rounded to nearest day. If item in state 

multiple times, days for each occurrence added together. 


DaysInState("Unspecified"). 

280 



DaysInPhase(phase field name, phase name) 

Returns number of days item in specific phase rounded to nearest day. If item in phase 

multiple times, seconds for each occurrence added together with result rounded to days. 

DaysCurrentState() 

Returns number of days item in current state rounded to nearest day. 


DaysCurrentState("Unspecified"). 

DaysCurrentPhase(phase-field-name) 

Returns number of days item in current phase rounded to nearest day. 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer 

Integer

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. 

dateFirstEntered(state-name) 

Returns date specified state first entered. 

dateLastEntered(state-name) 

Returns date specified state last entered. 


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

RelExists(relationship-field) 

Returns whether relationships exist through specified relationship field. 

Aggregate(relationship-field[, ...], aggregate-expression) 

Aggregate operates against single item using that single item to find multiple items it 

aggregates into for single value. 

Note: Aggregate is not aggregate function. 

At least one relationship field must be specified. Set of items made by following first 

relationship field. Then that set of items augmented by all items that set points at through 

next relationship field and onward for each specified relationship fields. Once set built, 

aggregate expression runs against that set of items. 



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. 

Integer 

Integer 

Integer 

Timestamp 

Timestamp 

Type of specified field 

name 

Integer 

Boolean 

Type of aggregate 

expression 

Integer 

Integer 

281


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. 

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. 


sumTimeEntryByState("Unspecified"). 

282 



Integer 

Integer 

Integer 

Integer 

Integer

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. 


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. 

firstTimeEntryDate() 

Returns earliest date time recorded against item. 

lastTimeEntryDate() 

Returns latest date time recorded against item. 




Integer 

Integer 

Integer 

Integer 

Integer 

Date 

Date 

283


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 previous Query function; however, if source-correlationfield 

same as target-correlation-field, use Query function. 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. 

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. Useful for item backed pick list 

(IBPL) use case. In this use case, you have item type that defines set of something, like 

applications. IBPL links each member of application back to application while query 

backed relationship (QBR) used for linkage between each application to each of its 

members. Can use QueryCorrelated function on application using Item ID from 

Application item correlated with IBPL representing Application on Defect that is member 

of it, for example: 

QueryCorrelated("All Defects", ID, "Application IBPL", count()) 

Creating Computed Fields 

284 

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. 




Integer or float, 

depending on 

aggregation-expression 

Integer or floating point, 

depending on 

aggregation-expression; 

see Query function 

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.

Creating Computed Fields 

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

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

To create a computed field 

1 From the Create Field dialog box, select Date, Floating Point, Integer, Logical, 

Boolean, 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 271. 

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" 

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. 

285


286 

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

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

6 Fill out the remaining fields and tabbed panels as described in “To create a field in the 

GUI” on page 106. 

7 Click OK to save your changes.

Calculating Static Computed Fields 

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. 

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. 

287


288 


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 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: 

Using Computed Fields to Chart Historical Trends 

im analytics --recomputehistory –-starttime=06/01/2002 –-endtime=08/ 

24/2007 –-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/2007 –-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. 

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. 

289


290 

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 

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 “MKS Integrity Event 

Triggers” on page 323 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 


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 

Using Computed Fields to Calculate State Metrics 

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) 

For detailed information on the external information functions applicable to state metrics, see 

“External Information Functions” on page 279. 

If you are using MKS Source with MKS Integrity, 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 MKS Source metrics, see “Using Project Metrics” on page 257. 

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) 

291


Security 

292 

Next, you query on Defects by the Fix Time field. To create a query, see the MKS Integrity 2007 

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 2007 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 2007 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 2007 User Guide. 

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

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 

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. 

293


294

C HAPTER EIGHT 

Change Packages 

Administering and Customizing Change Packages 

8 

This chapter provides information on customizing MKS Integrity change packages for 

use with MKS Integrity and integrations. This chapter also contains information on 

administering MKS Source change packages as part of a review process. 


“MKS Integrity Change Packages” on page 296 

“MKS Source Change Packages” on page 315 

295

Chapter 8: Change Packages 

Where to Go From Here 

296 

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 296 

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 MKS Source change 

packages. 

Manage change packages by implementing a 

review process. 

MKS Integrity Change Packages 

“Modifying Change Package Attributes” on 

page 305 

“Modifying Change Package Entry Attributes” on 

page 309 

“User Operations for Created Change Package 

Types” on page 312 

“Modifying CP Entries for Created CP Types” on 

page 314 

“MKS Source Change Packages” on page 315 

“Using Change Package Reviews” on page 316 

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, the MKS Integrity includes two change package types: MKS Source and 

Implementer. A change package type consists of change package attributes and change 

package entry attributes. 

Users can query and filter MKS Integrity 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 MKS Source and 

Implementer change packages.


The super administrator can customize and view permissions for the MKS Source (si) 

change package type. 

NOTE For information on the Implementer change package type, see the 

MKS Implementer 2007 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 2007 CLI Reference 

Guide or man pages. The commands are also available through the MKS API. For information 

on using the MKS API, see MKS Integrity 2007 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 MKS Integrity 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 17. 

297


298 

To view change package types in the CLI 

From the CLI, type the following command: 

where: 

im cptypes 

[--fields=field1[:width1],field2[:width2]...] 

[--fieldsDelim=value] 

cptypeID1, cptypeID2... 

--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 MKS Integrity, 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 2007 Installation 

and Configuration Guide. 

IMPORTANT By default, the everyone group is allowed to view MKS Source change 

packages. Once new permissions are set for the MKS Source change package type, 

the default settings are overwritten. If you set new permissions where no 

parameters are specified, then no one can view MKS Source change packages. 

NOTE You cannot edit the si (MKS Source) 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 17). 

3 Highlight the change package type you want to edit, and select Change Package Type > 

Edit. The Edit Change Package Type dialog box displays. 

299


300 

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. 


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 “Assigning Administrators to Change Package Types” on page 301. 

To determine all objects that reference the change package type, click the References 

tab. For information on the contents of the tab, see “Viewing Admin Object 

References” on page 220. 

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 


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

where: 


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

--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 MKS Source change 

package type, and also sets the groups QA and Development as the only groups having 

permission to view change packages of the MKS Source type. 

Assigning Administrators to Change Package Types 

1 From the Edit Change Package Type dialog box (see “Editing Change Package Types” on 

page 299), display the Administrators tab. 

301


302 

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. 

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 


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

303


304 


im viewcptype si 

displays information on the MKS Source 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 299. 

To create a change package type in the CLI 


where: 

im createcptype 


--permittedAdministrators=u=user1,user2,…;g=group1,group2,… 

--permittedGroups=group1,group2:modify,… 


--position=|first|last|before:|after: 

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




on using the MKS API, see the MKS Integrity 2007 Integrations Builder Guide. 

305


306 

Viewing Change Package Attributes 

To view change package attributes in the CLI 


where 

im cpattributes 

--cpType=change package type 

--fields=field1[:width1],field2[:width2]... 

--fieldsDelim=value 

cpattributeID1, cpattributeID2... 

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

Viewing Change Package Attribute Details 

To view change package attribute details in the CLI 


im viewcpattribute 




where 

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

307


308 

Editing Change Package Attributes 

To edit a change package attribute in the CLI 


where: 

im editcpattribute 









cpattributeID 






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. 





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 

From the CLI, type the following command:

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 


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. 

309


310 

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. 

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. 

311


312 

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

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 


where: 

im createcp 

--attribute=value 

--issueID=value 

--type=change package type 


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


im editcp 


--filter=type:name 

cpid 

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. 

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

313


314 

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. 

Modifying CP Entries for Created CP Types 





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: 

MKS Source Change Packages 

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

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

315


316 

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. 

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 MKS Source change packages by associating them with 

MKS Integrity items to take advantage of MKS Integrity’s workflow and process 

management. 

For information on enabling the integration with MKS Integrity and setting up MKS Source 

to use change packages, see the MKS Integrity Server 2007 Installation and Configuration Guide. 

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 


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

317


318 

Change Package review process 

The MKS Source 2007 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. For 

information on required policies and permissions, see the MKS Integrity Server 2007 


Review Benefits 

Pending Entries 

and Revisions 

Reviewers 

Developer 

The benefits of using reviews are: 

Submit Change 

Package 

Accept or Reject 

Accept 

Committed 

Reviews provide a formal and enforceable review process. 

Open and Work 

Repository 

Developer 

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. 

Reject

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 Source 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 Source 2007 User Guide. 

If you are using e-mail notification for change package reviews, ensure that triggers are 

enabled in the si.properties file (see “Configuring Event Triggers” on page 348). 

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: 

/data/triggers/events/global.events 

For more information on events, see “Events” on page 340. 

You can modify the trigger script by editing the following file: 

/data/triggers/scripts/samples/ 

changePackageNotification.js 

For more information on scripts provided by MKS, see “Sample Server-side Event Triggers” 

on page 353. 

319


320

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 runs when a predefined 

event occurs. For example, you could set up an event trigger to run every time a new 

item is submitted. 

MKS Integrity executes event triggers in response to an action by the client. Event 

triggers reside on the server machine where the MKS Integrity Server executes them. 

MKS Integrity does not support client-side event triggers. As a result, all references must 

be relative to the server. However, MKS Source supports client-side event triggers as 

documented in this chapter. 

IMPORTANT The date and time stamp presented to users for operations 

performed by server-side event triggers is that of the server time locale, not the 

locale of the MKS Integrity Client. 


“MKS Integrity Event Triggers” on page 323 

“Server-side MKS Source Event Triggers” on page 340 

321

Chapter 9: Event Triggers 


322 

The following table summarizes the steps you should follow to set up MKS Integrity event 

triggers:. 


Understand components of an event trigger, 

including the categories, examples of how to use 

triggers, and the transaction process. 

“MKS Integrity Event Triggers” on page 323. 

Understand how to implement event triggers. “Planning Event Triggers” on page 325. 

Use event triggers, including planning, creating, 

managing, viewing, editing, deleting, and 

resolving event triggers. 

“Using Event Triggers” on page 326. 

Use the MKS Integrity Script Library. “MKS Integrity Script Library” on page 337. 

The following table summarizes the steps you should follow to set up MKS Source event 

triggers:. 


Understand the components of a server-side 

event trigger, including the event, the 

MKS Source command, the types of event 

triggers and their contexts. 

“Server-side MKS Source Event Triggers” on 

page 340. 

Create a server-side event trigger. “Creating Server-side Event Triggers” on 

page 347. 

Understand how MKS Source resolves event 

triggers. 

Refer to sample server-side event triggers, 

including triggers to run custom java code from a 

script. 

“Event Trigger Resolution” on page 352. 

“Sample Server-side Event Triggers” on 

page 353. 

Create a client-side event trigger. “Configuring Client-side Event Triggers” on 

page 355.

MKS Integrity Event Triggers 


An event trigger is a block of code associated with a predefined event. The script performs a 

specified action and is executed whenever the event occurs. For example, you could set up an 

event trigger to run every time a user checks in a file. 

To understand MKS Integrity event triggers, you need to know the following: 

“Event Categories” on page 323 

“How to Use MKS Integrity Event Triggers” on page 323 

“Transactionality of Event Triggers” on page 324 

Event Categories 

An event is a defined point in MKS Integrity’s operation. MKS Integrity operations fall into 

three categories of events: 

Rule based change events run because of an action made by a user. 

Scheduled events run in isolation and do not require an action by a user. 

Other events run when: 

time entry is changed by a user 

item tree is copied 

item is branched 

item is labeled 

How to Use MKS Integrity Event Triggers 

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. 

Populate fields on the same item based on certain field selections. 

When an item’s state changes, change the assigned user. 

When an item is closed, close all of the underlying tasks. 

Enforce mutually exclusive fields. 

323


324 

Create new items and link them to existing items. 

Enforce mandatory fields for a specific state transition. 

The following are some of the ways you can use scheduled triggers: 

Stale items 

If the item is in a state and unchanged for a specified length of time, send e-mails to 

assigned users and relevant managers. 

Change the priority level of an item 

If the priority is at the maximum level, send an e-mail to the manager. 

Unassigned items 

If a critical item has been in a beginning state for a number of days, send an e-mail to the 

project manager. 

Item cleanup 

Clear items that have been in an open state for years, and cancel and close them. 

Missed deadline 

If an item is in a development state after the required completion date has passed, send 

an e-mail to the project manager. 

Avoid missed deadlines 

Send an e-mail to the project manager a day before the required completion date for 

development. 

Repeated escalations 

Send an e-mail to the project manager repeatedly until the item is modified in a specific 

way. 

Recalculating an item’s history 

If an item contains a computed field, specify the frequency at which the computed field 

is recalculated and stored in the item’s history. 

A user can use time entry triggers whenever a time entry is created, edited, or deleted. 

For more information on scripts in the library, see “Available Pre-created Scripts” on 

page 337. 

Transactionality of Event Triggers 

An event trigger is an association between a predefined MKS Integrity 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 can modify the item being changed and prevent changes to an item.


Post-event triggers return information on items in the database and perform actions such 

as sending mail, but they cannot make modifications to items. 

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. 

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. 

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 Event 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 Determine the base tasks the trigger needs to perform, and select the required scripts 

from the library. 

3 Determine what fields, if any, the trigger will change or what information the trigger 

collects from the database. 

325


Using Event Triggers 

326 

4 Identify which user permissions are overridden by the trigger and how that affects 

security. 

5 Identify potential constraint based conflicts, such as mandatory fields for state changes 

or closed change package requirements. 

NOTE To use MKS Integrity event triggers, set the property 

mksis.im.triggers.enable=true in the im.properties file. For more 

information, see the MKS Integrity Server 2007 Installation and Configuration Guide. 

To use MKS Integrity event triggers, you need to know the following: 

“Managing Event Triggers” on page 326 

“Creating Event Triggers” on page 327 

“Viewing Event Triggers” on page 335 

“Editing Event Triggers” on page 336 

“Deleting Event Triggers” on page 336 

“Resolving Event Triggers” on page 337 

“Running the MKS Integrity Server” (for more information, see the MKS Integrity Server 

2007 Installation and Configuration Guide) 

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 MKS Integrity 

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

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

on a schedule (see “Creating Scheduled Triggers” on page 331) 

whenever a time entry is changed (“Creating Other Triggers” on page 334) 

run a scheduled event trigger (see “Running Scheduled Triggers” on page 335) 

edit an event trigger (see “Editing Event Triggers” on page 336) 

view an event trigger’s details (see “Viewing Event Triggers” on page 335) 

delete an event trigger (see “Deleting Event Triggers” on page 336) 

change the order of event trigger resolution (see “Resolving Event Triggers” on 

page 337) 

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. 

327


328 

The general steps required to create a rule-based change trigger are as follows: 

1 Select the rule-based change trigger type. 

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

Keep in mind the following when creating a rule-based change trigger: 

Permissions are validated 

Ensure each field the user is required to update is legally updateable by that user. 

Workflow validation 

If the state of an item is being changed, ensure the state transition is valid. 

Change package closed 

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. 

Mandatory fields 

Ensure all fields that are mandatory for the final state in the workflow contain values. 

NOTE 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 MKS Source and are not applicable to 

MKS Integrity.

To create a rule-based change trigger in the GUI 


1 In the Triggers view (see “Managing Event Triggers” on page 326), 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. 

Remove deletes the selected 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 41. 

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 

329


330 

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

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: 

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 “MKS Integrity Script 

Library” on page 337. 

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 “MKS Integrity 

Script Library” on page 337. 

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) 

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. MKS Source 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 17. 

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. 

331


332 

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 Project Visibility” on page 230 and 

“Setting Field Visibility for Types” on page 101. 

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

NOTE You must specify a user in the Run As list or you cannot save the trigger. 




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. 

333


334 

Creating Other Triggers 

In addition to schedule- and rule-based triggers, you can create triggers that run when one of 

the following MKS Integrity actions occur: 

time entry is changed 

item tree is copied 

item is branched 

item is labeled 

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. 

To create an other trigger 




3 Enable Other. 

4 From the Run triggers whenever list, select an option.





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. 

Running Scheduled Triggers 

Once you have created a scheduled trigger, you can run it. You can only run scheduled 

triggers manually by this method. 

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

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

2 Select Trigger > View Definition. The View Trigger dialog box displays. 

3 Click a tab to view its contents. 

4 To finish, click Close. 

335


336 

Editing Event Triggers 

You can edit the details of an MKS Integrity 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 326. 

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 327 and see “Creating Scheduled Triggers” on page 331. 

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 an MKS Integrity 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 326. 

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. 

MKS Integrity Script Library 

MKS Integrity 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. 

Event triggers are scripted using JavaScript 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.ecmainternational.org/). 

Detailed information on the JavaScript input elements—such as tokens, line terminators, 

comments, and white space—is beyond the scope of this guide. However, for further 

information on the JavaBeans exposed by MKS Integrity, refer to the Javadocs installed on 

the server at: 


TIP Javadocs are available from the MKS Integrity Server home page. 

Available Pre-created Scripts 

MKS Integrity provides pre-created scripts, which are available in the script library found in: 

/data/triggers/scripts 

The list of pre-created scripts provided may vary depending on the server implementation of 

an organization. The following pre-created scripts are available: 

337


338 

assignedUserOnly.js restricts item editing to the assigned user only. 

assignment.js automatically assigns an item based on a file-driven set of criteria. 

count.js maintains an integer field to be set as equal to the number of related items 

through a given relationship field. 

dependentStatus.js creates a status dependency on related items. 

echo.js prints the event type, name, and context to the /log/ 

server.log file. 

email.js sends an e-mail notification from a scheduled trigger. 

escalate.js escalates an item from a scheduled trigger. 

hello.js prints the event type, name, and context (if run from a scheduled trigger, it 

prints the item numbers of the matched items). 

javamail.js uses the Java mail API to send simple e-mail notifications in both plain 

text and HTML. 

mandatoryFieldsOnStateTransition.js enforces mandatory fields on a state 

transition. 

postLinkedIssue.js posts a new item based on a state change for a source item. 

PromoteIssue.js enables generating and promoting Implementer requests from 

within MKS Integrity. For more information, see the MKS Implementer 2007 Installation 

and Administration Guide. 

signatureRequired.js requires an electronic signature for changes to items. For more 

information, see “Setting Up Electronic Signatures” on page 218. 

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. 

Adding Scripts to Library 

Although the details of JavaScript programming are outside the scope of this guide, the 

following provides a general approach to writing event triggers: 

Prepare your event trigger script using JavaScript in ECMA-compliant syntax. The 

following affects how the script information displays in the GUI: 

The first set of commented text before the first list starting with @param displays as a 

description field for the script. You can use HTML tags for paragraph and character 

formatting. 

NOTE Do not use HMTL comment tags of the form in your 

scripts.


A commented line starting with @param describes a single parameter. The first word 

after @param is the field type and can be String, Boolean, or MultiString. The 

words that follow until the end of the line are used as the name of the parameter 

field (displays on the left field of the GUI). The name of the field also displays as the 

key used to review parameter values in the parametersBean class by calling the 

getParameter method. 

Text on the subsequent commented lines until the next @param (or, if no @param, 

then end of text block) appear as tooltips for the parameter field in the GUI. 

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. 

Reference the applicable Bean or Beans you want to perform an operation on. For details 

on the method for calling the necessary Beans, refer to the installed Javadocs under: 


To identify the name a Bean can be referenced by, review the documentation for the 

method GetExposedName in the serverBean class. 

NOTE When a date is set in a JavaScript using IssueDeltaBean. 

setDeltaFieldValue() based on the value of a data/time field, the time portion 

is not truncated in the database. For example, if datetime_1 field has a value of 

Apr 1, 2007 4:51:24 PM and it is assigned to date_1 field, the date_1 field 

displays a value of Apr 2, 2007. If date_1 field is assigned to datetime_2 field, 

the datetime_2 field displays a value of Apr 1, 2007 4:51:24 PM. 

Look up the Bean or Beans: 

var environmentBean = bsf.lookupBean 

("siEnvironmentBean"); 

View the source for the available pre-created scripts for examples on how to set up a 

script. For more information, see “Available Pre-created Scripts” on page 337. 

When the script has been completed and tested, save it in: 


NOTE You can also set another location for the script library by modifying the 

is.properties file. For more information, see the MKS Integrity Server 2007 


339


Server-side MKS Source Event Triggers 

Member Events 

340 

This section assumes familiarity and experience with JavaScript, your specific operating 

system, and MKS Source. Do not attempt to implement event triggers without experience. 

The samples provided may not necessarily be configured for use at your site. They are 

designed as examples only. 

Events 

An event is a defined point in MKS Source’s operation. The four categories of events 

connected with MKS Source operations are: 

member 

project 

revision 

server 

The global.events definition file is contained in: 

/data/triggers/events 


Server. For more information on the events definition file, see “Updating Events Definition 

File” on page 351. 

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 

Project Events 

checkpoint.pre checkpoint.post 

restore.pre restore.post 

addMember.pre addMember.post 

dropMember.pre dropMember.post 

moveMember.pre moveMember.post 

newSubproject.pre newSubproject.post 

addSubproject.pre addSubproject.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 


341


Server Events 

342 

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 

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 

MKS Deploy Events 

These events are only applicable if you are licensed to use MKS Deploy. For more information, see the MKS Deploy 

2007 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

MKS Deploy Events 

Project.restoreStage.pre Project.restoreStage.post 

Project.deployRequestStateChange.post 

Project.deployTargetConnectionStatusChange.post 

MKS Source Commands 


The following tables list the available MKS Source 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.addSubproject 

si createsubproject Project.importSubproject 

si movesubproject Project.moveSubproject 

343


Project Command Project Event Identifier 

344 

si drop Project.dropSubproject 

si createdevpath Project.newVariant 

si dropdevpath Project.deleteVariant 

si setprojectdescription Project.setDescription 

si dropprojectattr Project.dropProjectAttribute 

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

Event Triggers 


An event trigger is an association between a pre-defined MKS Source event and the script that 

is to be executed when that event occurs. The operation occurs in the following sequence: 

Integrity Client initiates a command that will be run on the MKS Integrity Server. 

Before event begins, pre-event is posted. 

Event occurs. 

MKS Integrity Server polls its registry of events to determine if the event has an 

associated script. 

If script is found, the MKS Integrity Server executes the resolved script. 

Command executes. 

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. 

MKS Source event triggers are scripted using JavaScript and are declared using the IBM 

Alphaworks Beans Scripting Framework (BSF). Event trigger variables are declared as 

JavaBeans in the following syntax: 

var environmentBean = bsf.lookupBean ("siEnvironmentBean"); 

The functionality of MKS Source is available through Beans that are exposed to the 

JavaScript. Once the JavaBean has been referenced, you can perform operations on that Bean. 

The following provides an example of a Bean that could be used to abort a script and provide 

the user with a message: 

var environmentBean = bsf.lookupBean ("siEnvironmentBean"); 

environmentBean.abortScript ("Your revision description 

is incomplete",true); 

To obtain build and development path information for the current project from a Bean, use 

the following methods in the project Bean: 

isNormal(), isVariant(), isBuild()getVariantName(), 

getBuildRevisionBean() 

345


346 

For further details on the specific Beans available with MKS Source, refer to the installed 

Javadocs in: 


and review the documentation for the method GetExposedName. 

Event Trigger Contexts 

MKS Source 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. 

NOTE When working with shared subprojects, MKS Source uses the actual name of 

the subproject in the file system rather than its relative name in the project hierarchy. 

This enhances the portability of change packages across different projects. 

Therefore, when returning query information resulting from a script, MKS Source 

uses the actual file system name of the shared subproject. 

Global Context 

Global event triggers are available and active for all MKS Source operations. As 

administrator, you use the global context for any JavaScript elements used to define 

additional procedures for all MKS Source users. 

Project Context 

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 MKS Source 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 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 /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. 

Components of Event Triggers 

Creating an event trigger in MKS Source requires three primary components: 

Properties files: 

/config/properties/si.properties 


to configure MKS Source so that event triggers may take place. The files include 

properties that define the directories for both the events definition files and event trigger 

scripts. 

Events definition files listing all events defined in MKS Source 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: 


Creating Server-side Event Triggers 

Event triggers in MKS Source are scripted using JavaScript and follow the standard 

established by the European Computer Manufacturers Association (ECMA) in ECMAScript. 

Additional information on ECMAScript is available at ECMA’s Web site (http:// 

www.ecma-international.org/). To view examples of scripted event triggers, see 

“Sample Server-side Event Triggers” on page 353. 

347


348 

Detailed information on the JavaScript input elements—such as tokens, line terminators, 

comments, and white space—is beyond the scope of this guide. However, for further 

information on the JavaBeans exposed by MKS Source, refer to the Javadocs installed on the 

server at: 


The following steps are required to create an event trigger: 

“Configuring Event Triggers” on page 348 

“Planning Event Triggers” on page 349 

“Writing Event Triggers” on page 350 

“Updating Events Definition File” on page 351 

“Restarting MKS Integrity Server” on page 352 

The next sections describe the detailed procedures required to complete each of these steps. 

Configuring Event Triggers 

MKS Source is pre-configured with event triggers enabled by default. To disable event 

triggers, you must modify the required properties in: 



Server-side event triggers are enabled using properties in the si.properties file: 

si.triggers.enable=true enables event triggers. Can be either true or false. If 

false, all other trigger properties are ignored. 

si.triggers.events=triggers/events/ points to the directory that MKS Source 

searches for event definition files. The default is: 


This is a relative path to the MKS Integrity Server directory and should always contain 

forward slashes. 

si.triggers.disabled=triggers/disabled.txt points to a file that lists serverside 

project paths. Each of the projects listed has its event triggers disabled. Disabling 

also disables global event triggers. Property uses a relative path to the MKS Integrity 

Server directory and should always contain forward slashes. 

si.triggers.disableSubProjects=true indicates whether a trigger for a subproject 

should be disabled because its parent project has disabled triggers. 

si.triggers.resolution=chained describes the resolution type: singlescript, 

singlecontext, or chained.


si.triggers.resolutionOrder=global,project specifies the order the trigger 

scripts are resolved in. By default, it is a comma-delimited list containing keywords for 

global and project events. 

The following global trigger properties are also set in /config/ 

properties/is.properties: 

triggers.scripts=triggers/scripts/ points to the directory that MKS Source 

searches for script files. The default directory is: 


Property uses a relative path to the MKS Integrity Server directory and should always 

contain forward slashes. 

By default, triggers.script=triggers/script. 

triggers.mailServer= specifies the address of the mail server used by the event 

trigger environment Bean method sendMail(). The mail server is specified as either a 

server name (triggers.mailServer=smtpgate.xyzBusiness.com) or an IP address 

(triggers.mailServer=1.2.34.56). 

triggers.environmentVariables=triggers/env.properties points to a Java 

properties file that can be populated with variables that are available during runtime. 

Variables are accessible by using: 

var props = ScriptEnvironmentBean.getEnvironmentVariables(); 

props.getProperty("myVariable"); 

Property uses a relative path to the MKS Integrity Server directory and should always 

contain forward slashes. If given, the variables defined here are shared by all 

MKS Integrity and MKS Source triggers. 

Planning Event Triggers 

You can set event triggers in MKS Source in several ways. 

First choose the scope of the event trigger. Event triggers that you want to apply to all 

operations should be set in the global context. Event triggers that are related only to a specific 

project should be set in the project context. 

You can then consider whether your event triggers should occur as a pre-event or post-event. 

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. Post-event triggers are more 

349


350 

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 project context. 

Consider two additional issues when planning event triggers: 

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. 

Writing Event Triggers 

Although the details of JavaScript programming are outside the scope of this guide, the 

following provides a general approach to writing event triggers: 

Prepare your event trigger script using JavaScript in ECMA-compliant syntax. For 

examples of completed JavaScripts, see “Sample Server-side Event Triggers” on 

page 353. 

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. 

Reference the applicable Bean, or Beans, you want to perform an operation on. For 

details on the method for calling the necessary Beans, refer to the installed Javadocs in: 


To identify the name a bean can be referenced by, review the documentation for the 

method GetExposedName. 

Look up the Bean, or Beans: 

var environmentBean = bsf.lookupBean ("siEnvironmentBean")


Save your script in the directory specified for the triggers.script property in 

is.properties file. By default, this directory is: 


Update events definition file. 

Restart MKS Integrity Server. 

MKS Source runs the 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. 

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 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 MKS Source operation, for example, checkIn, checkOut, 

setAttribute, or checkpoint (for a complete list of MKS Source events, see 

“Events” on page 340) 

351


352 

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 MKS Source 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: 

/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 2007 


Event Trigger Resolution 

MKS Source resolves event triggers according to the resolution order configured in the 

si.properties file. For example, if the order is global,projects, the global events file is 

searched for scripts, followed by the projects event file. When MKS Source finds a script with 

a matching name, it runs the script. 

MKS Source is pre-configured to first resolve global event triggers followed by project event 

triggers. The variable is: 

si.triggers.resolutionOrder=global,project 

The default setting can be reconfigured to suit your environment.

To change the order of event trigger resolution 

1 Open the file: 


2 Edit the property: 

si.triggers.resolutionOrder=global,project 

to reverse the sequence of the global and project contexts: 

si.triggers.resolutionOrder=project,global 


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. 

Sample Server-side Event Triggers 

Sample event triggers are provided in: 

/data/triggers/scripts/samples 



Sample Scripts 

Under /data/triggers/scripts, the /samples directory includes the 

following event trigger scripts: 

Script Name Function of Script 

Break Lock 

breakLockNotification.js 

Change Package Notification 

changePackageNotification.js 

Deploy Request Notification 

deployRequestNotification.js 

Sends e-mail if one user removes or downgrades lock held by 

another user. E-mail notifies lock holder and provides information: 

file and revision lock broken on, full path of file archive, server lock 

broken on, user who broke lock, and whether lock downgraded or 

removed. 

Script set on Revision.unlock.post event. 

Sends e-mail to change package creator, reviewer, or watcher 

during a change package review (see “Change Package Review Email 

Notification” on page 319). 

Sends e-mail to administrators for deploy target that deploy 

request sent to. 

Script set on Project.deployRequestStateChange.post 

event. 

Script used for MKS Deploy. For more information, see 

MKS Deploy 2007 Administration Guide. 

353


Script Name Function of Script 

Deploy Target Notification 

deployTargetNotification.js 

Dynamic Updating of Linked Member 

Revisions 

ClientLink.js 

Enforce Revision Description 

enforceRevisionDescription.js 

Enforce Tabs 

enforceTabs.js 

Force Merge 

forceMerge.js 

Metrics 

metrics.js 

Project Mirror Tree 

mirrorTree.js 

354 

When deploy target status changes to offline, sends e-mail to 

administrators for deploy target. 

Script set on 

Project.deployTargetConnectionStatusChange.post 

event. 

Script used for MKS Deploy. For more information, see 

MKS Deploy 2007 Administration Guide. 

Dynamically updates linked member revisions (member revisions 

specified using -rlink: symbolic member revision rule). For 

more information on using member rule, see “Updating a Member’s 

Revision” and “Setting a Member Rule” in MKS Source 2007 User 


Enforces revision description of length greater than 0 on checkin. 

Scans file during checkin to verify whether indentation uses tabs or 

spaces (assuming tab stops set every eight spaces). 

Scan looks for lines that start with eight spaces. To avoid confusion 

for spaces contained within quoted strings, contents of line not 

examined. Files ending in .java , .c, or .cpp examined; others 

silently accepted. 

Note: Script does not have correct results if program includes 

strings ending in backslash and continuing on next line with leading 

spaces; however, such entries generally discouraged as poor 

programming practice. 

Stops user from performing checkin if file in Sandbox not same as 

revision being checked in. Use script when not using strict locking 

to prevent overwriting member revision. 

Script set on Member.checkIn.pre event. 

Calculates metrics for project. For more information, see “Using 

Project Metrics” on page 257. 

Maintains mirror of project files in destination specified by 

mirrorRoot variable. Script useful for keeping document root of 

Web server up to date. 

Mirror project tree event trigger does not actually mirror files from 

Sandbox in that it removes all carriage returns from your file and 

uses line feeds instead. 

Note: Script uses native line terminator. To use different line 

terminator, modify script. 

Script set for following events in global.events or 

project.events file: 

Project.dropMember.post 

Project.addMember.post 

Member.checkIn.post 

Member.rename.post

Running Custom Java Code 


You can also use server-side event triggers to run custom Java code from a script. 

Your custom Java code can be put into the /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. 

Additional Information 

Additional information on server-side event triggers is provided in the installed Javadocs in: 


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. 

Configuring Client-side Event 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 

commands that operate on directories, projects, Sandboxes, or change packages. 

355


356 

Client-side triggers can be configured in the following file on the MKS Integrity Server: 

/config/policies/si.policy 



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. 

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 si.policy file on the 

MKS Integrity Server 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 project commands that operate on members, including commands launched from the 

MKS Source Web client. The second table lists the applicable member commands. 

NOTE The si echo command is available for echoing strings to the GUI. 

Project Commands for Members 

Project Command Command Expression 

si add AddMembers 

si dropproject DropProjectTypeElement 

si edit EditCurrentOrFormerProjectTypeElements 

si import ImportMembers 

si mergebranch MergeBranch 

si add ProjectAddMembers 

si ci ProjectCheckInMembers 

si co ProjectCheckOutMembers 

si promote PromoteMembers 

si resync ResyncCurrentOrFormerProjectTypeElements 

si revert RevertCurrentOrFormerProjectTypeElements 

si submit SubmitCurrentOrFormerProjectTypeElements 

357


358 

Sample Client-side Triggers 

This section provides examples of client-side event triggers that you can use for: 

displaying Sandbox information 

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 

si rename RenameMember 

si viewrevision RevisionContentsView 

si revisioninfo RevisionInformationView 

si thaw ThawMember 

si unlock UnlockRevisionOfMember 

si updaterevision UpdateRevisionOfMembers 

si updatearchive UpdateArchiveAttributesOfMembers

posting a revision description reminder 

launching a text editor 

posting a notification reminder to a specified group 

confirming the presence of specific files in a Sandbox 

Displaying Sandbox Information 


The following sample trigger—ALpre—runs a KornShell script that displays Sandbox 

information prior to the addition of a label and, in this way, helps users to assign appropriate 

label names. 

To configure the trigger, the following information is added to the si.policy file on the 


si.AddLabel.pre=ALpre 

si.trigger.ALpre.command=sh -w -c "si sandboxinfo -S $MKSSI_SANDBOX" 

Posting Revision Description Reminder 

This sample client-side trigger—CIpre—runs a KornShell script that prompts the user to add 

a revision description for the member they are checking in. 



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

Launching Text Editor 

This sample client-side trigger prompts users to update a member list text file whenever a 

new member is added to the project. When the member is successfully added to the project, a 

post event trigger launches the vi text editor and opens the text file so that the user can enter 

the required information. 

For example, an administrator may want users to record the date and purpose information in 

a text file each time a new member is added to the project. To do this, the administrator sets a 

client-side trigger that posts a reminder for users each time an add member operation is 

initiated. Upon starting the add member operation, the trigger posts a message such as: 

After adding the project member, please update the NewMembers.txt 

file with the date and purpose of the new member. 

Upon successful completion of the add member operation, the trigger opens the 

NewMembers.txt file in a vi text editor. Users enter the date and purpose information for the 

newly added member and then save the text file. 



359


360 

si.AddMembers.pre=AMpre 

si.trigger.AMpre.command=sh -w -c 'echo After adding the project 

member, please update the NewMembers.txt file with the date and 

purpose of the new member.' 

si.AddMembers.post=AMpost 

si.trigger.AMpost.command=sh -w -c 'vi c:/NewMembers.txt' 

Posting Notification Reminder 

This sample client-side trigger—CIMpost—posts a reminder to notify team members when 

significant changes are checked in to a member revision. In this way, the administrator can 

endorse increased communication between team members, and team members are kept up to 

date on project work. This type of trigger is effective when set to a checkin operation. 



si.CheckInMembers.post=CIMpost 

si.trigger.CIMpost.command=sh -w -c 'echo If you have made 

significant changes to this project member, please notify your team 

members about the changes.' 

This client-side trigger can also be configured to post a reminder only for a specified group. 

The following example shows a client-side trigger configured to post a reminder only to 

those people working in a development group: 

si.CheckInMembers.post=CIMpost 

si.trigger.CIMpost.command=sh -w -c 'echo If you have made major 

changes to this member, please notify your team members regarding 

those changes.' 

si.trigger.CIMpost.group=Development 

NOTE The specified group must be a valid group on your system. 

Confirming Files in Sandbox 

This trigger confirms that each .C file in the user’s Sandbox has a corresponding .OBJ file, 

and that each .JAVA file has a corresponding .CLASS file. The check only confirms the 

presence of the files and does not validate any compiling of the associated files. 

NOTE MKS Toolkit® is required to run this trigger. 

To configure the trigger for the development group, the following information is added to 

the si.policy file on the MKS Integrity Server operating on a Windows network drive: 

si.CheckInMembers.pre=CIMpreFiles 

si.trigger.CIMpreFiles.command=sh //server/scripts/trigger.ksh 

si.trigger.CIMpreFiles.group=Development 

Sample code for the trigger.ksh script is:

function display { 

case "$MKSSI_UI" in 

web) 

# Not supported 

;; 

cli) 

sig echo --presentername "$MKSSI_PRESENTER" 

sig echo --presentername "$MKSSI_PRESENTER" "$*" 

;; 

gui|*) 

} 

sig mks.ic.common.commands.EchoCommand -g "$*" 

;; 

esac 

if [ "$MKSSI_WINDOW" != "trigger" ] 

then 

display "Improper call of script $0" 

exit 1 

fi 

# 

# Actual trigger code 

# 

if [ "$MKSSI_WORKINGFILE" = "" ] 

then 

display "Working file does not exist." 

exit 1 

fi 

case "$MKSSI_WORKINGFILE" in 

*.c) 

obj="${MKSSI_WORKINGFILE%%.c}.obj" 

;; 

*.java) 

obj="${MKSSI_WORKINGFILE%%.java}.class" 

;; 

*) 

exit 0 

;; 

esac 


if [ ! -f "$obj" ] 

then 

display "The file $obj does not exist. Before \ checking in, make 

sure that you have compiled the \ object in your sandbox." 

exit 1 

fi 

exit 0 

361


362 

To add client-side trigger information to the si.policy file 

1 From the MKS Integrity Server MKS Integrity Administration Client, open the 

MKS Source 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 

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. 

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.

Environment Variable Function 


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 

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

j 

MKSSI_PROJECT=server-path-to-project MKSSI_PROJECT set to server path to 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 

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 

MKSSI_PROJECT_TYPE=sandbox|project MKSSI_PROJECT_TYPE sets one or other keyword to 

indicate whether operation runs in Sandbox or 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. 

363


364 

Sample Configuration Using Environment Variables 

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 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" 

Modifying MKS Integrity Item Fields 

To integrate an MKS Source change package state with an MKS Integrity item state, you can 

configure MKS Source event trigger scripts to invoke MKS Integrity event trigger scripts. 

More specifically, you can automatically modify MKS Integrity item field values when a 

MKS Source event occurs. 

The following examples show how you can enhance change package centered workflow 

using this functionality: 

If a change package is accepted, the state of the corresponding item is automatically 

moved to Code Review Done. 

If a change package is rejected, the state of the corresponding item is automatically 

moved back to In Development. 

If you enforce change package reviews, an MKS Source close change package trigger 

automatically changes the state of the related item to Development Done. 

A submit change package trigger prevents a change package from being submitted until 

the Reviewer field is filled out. 

To accommodate the use of dynamic parameters in event triggers, methods have been added 

to the following Beans (for more information on the methods for each Bean, consult the Event 

Trigger Java Documentation): 

ScriptParametersBean obtains static configuration arguments set up by the script 

author when the trigger was created. 

SI ScriptServersBean exposes methods that allow you to get the 

ScriptParametersBean, and it also invokes an MKS Integrity trigger with the given 

populated ScriptParametersBean. After the MKS Integrity trigger finishes running, 

the MKS Source script obtains another instance of ScriptParametersBean that 

contains any return values that the MKS Integrity trigger script may have set.


IM ScriptServersBean allows you to get the invocation arguments in addition to the 

configuration parameters (an instance of ScriptServerBean). 

NOTE Dynamic invocation arguments are not defined or exposed in the 

MKS Integrity Administration Client, since these are the concrete arguments that 

scripts obtain from the CLI or from MKS Source (when MKS Source invokes an 

MKS Integrity trigger). 

The im runtrigger command also allows you to specify invocation arguments to manually 

run scheduled triggers. The data types that can be passed to the MKS Integrity trigger 

include integers, floats, strings, Booleans, Java dates, and arrays of these. These dynamic 

arguments are passed to the triggers in addition to any static configuration parameters that 

may have been set up when the trigger was created. 

where 

im runtrigger --invocationArgs=key1=value1 

key=value is an invocation argument for the manually scheduled triggers. For example, 

the following could be passed as arguments: 

issueID=item ID is the ID of the MKS Integrity item that you want to make changes 

to 

field=item field is the field of the MKS Integrity item that you want to make 

changes to 

arg=value is the value that you want to set field=item field to 

trigger is the MKS Integrity trigger created to use the script 

Example 

NOTE You cannot delimit the invocation arguments with commas. You must specify 

the --invocationArgs option additional times as necessary. 

Within the main body of code, the following MKS Source script calls an MKS Integrity event 

trigger called “test”, using several change package events to automate change package 

workflow: 

var environment = bsf.lookupBean("siEnvironmentBean"); 

var server = bsf.lookupBean("siServerBean"); 

var eventID = environment.getEventID(); 

var eventType = environment.getEventType(); 

var imArgs; 

var invocArgs = server.getInvocationArgumentsBean(); 

var argsBean; 

365


366 

var cpBean; 

// Boolean Array to control aspects of the IM Trigger 

// 0:Log Messages 1:Run Equivalent tests 2:Log Data Type Variables 

var testControlArray = [true,true,false]; 

// long data variables for testing. 

var longTypeTest = new java.lang.Long(999999).longValue(); 

var longArrayTypeTest = [new 

java.lang.Long(-922337203).longValue(),new 

java.lang.Long(999999).longValue(),new 

java.lang.Long(92233720).longValue()]; 

// double data variables for testing. 

var doubleTypeTest = 19.73; 

var doubleArrayTypeTest = 

[-494065645841246544.1973,19.73,179769313486231570.1973]; 

// int data variables for testing. 

var intArrayTypeTest = [-2147483648,1973,2147483647]; 

try{ 

invocArgs.setStringParameter("msgField","Notes"); 

printToLog("\nEvent : "+eventID); 

printToLog("\nEvent Type: "+eventType); 

// Submitted change package event 

if (eventID.equals("submitChangePackage")) { 

argsBean = bsf.lookupBean 

("siSubmitChangePackageArgumentsBean"); 

invocArgs.setDateParameter("submitDate",java.util.Date()); 

invocArgs.setDateParameter("startDate",java.util.Date(java.util. 

Date().getTime()+(7*24*60*60*1000))); 

printToLog("Java Object Date : 

"+java.util.Date(java.util.Date().getTime()+(7*24*60*60*1000)). 

toString()); 

printToLog("Argument Object Date : 

"+invocArgs.getDateParameter("startDate").toString()); 

invocArgs.setDateParameter("finishDate",java.util.Date(java.util. 

Date().getTime()+(365*24*60*60*1000))); 

invocArgs.setStringParameter("nextState","Development Done");

Accepted change package event 

} else if (eventID.equals("acceptChangePackage")) { 


("siAcceptChangePackageArgumentsBean"); 


invocArgs.setDateParameter("acceptDate",java.util.Date()); 

invocArgs.setStringParameter("nextState","Built"); 

// Rejected change package event 

} else if (eventID.equals("rejectChangePackage")) { 


("siRejectChangePackageArgumentsBean"); 

invocArgs.setDateParameter("rejectDate",java.util.Date()); 

invocArgs.setStringParameter("nextState","Development"); 

// Closed change package event 

} else if (eventID.equals("closeChangePackage")) { 


("siCloseChangePackageArgumentsBean"); 

testControlArray[1] = false; 

// Commit failed change package event 

} else if (eventID.equals("commitChangePackage")) { 


("siCommitChangePackageArgumentsBean"); 


} else if (eventID.equals("discardChangePackage") ){ 


("siDiscardChangePackageArgumentsBean"); 


} else if (eventID.equals("discardChangePackageEntry") ){ 


("siDiscardChangePackageEntryArgumentsBean"); 

}else { 

} 


testControlArray[2] = true; 

printToLog("Event not recognized."); 

invocArgs.setStringParameter("type",eventID); 

367


368 

cpBean = server.getChangePackageBean 

(argsBean.getChangePackageID()); 

var mapInvocArgs = invocArgs.getParameters(); 

mapInvocArgs.put("entriesArray",convertEntryListToStringArray 

(cpBean.getEntries())); 

invocArgs.setParameters(mapInvocArgs); 

invocArgs.setStringParameter("cpID",argsBean.getChangePackageID()); 

invocArgs.setIntParameter("issueID",getIssueID(cpBean.getID()) ); 

invocArgs.setBooleanArrayParameter("testControl",testControlArray); 

if(testControlArray[2] == true){ 

invocArgs.setLongParameter("longTypeTest",longTypeTest); 

invocArgs.setLongArrayParameter("longArrayTypeTest", 

longArrayTypeTest); 

invocArgs.setDoubleParameter("doubleTypeTest",doubleTypeTest); 

invocArgs.setDoubleArrayParameter("doubleArrayTypeTest", 

doubleArrayTypeTest); 

invocArgs.setIntArrayParameter("intArrayTypeTest",intArrayTypeTest); 

} 

// Call "test" trigger with Arguments set. 

imArgs = server.runIMTrigger("test",invocArgs); 

var modDate = imArgs.getDateArrayParameter("refDates"); 

printToLog("Issue Modified : "+modDate[1].toString()); 

}catch(e){ 

printToLog(e); 

} 

The main body of code for the test script is as follows: 

var environment = bsf.lookupBean("siEnvironmentBean"); 

var server = bsf.lookupBean("imServerBean"); 

var paramArgs = server.getInvocationArguments(); 

var retInvocArgs = server.getReturnValueBean(); 

var argsBean; 

var testControlArray = 

paramArgs.getBooleanArrayParameter("testControl"); 

if (paramArgs.contains("issueID")){

}else{ 

} 

var CP_ID = paramArgs.getStringParameter("cpID"); 

abort("\n****\nIssue ID not supplied.\n****\n"); 

var msgField = paramArgs.getStringParameter("msgField"); 

var msg = "\n"; 

// Array of objects 


// 0:Create Date 1:Modified Date 2:Start Date 3:Finish Date 

var dateArray = new Array(); 

try{ 

var cpDeltaBean = 

server.getIssueDeltaBean(paramArgs.getIntParameter("issueID")); 

if(cpDeltaBean.isSecondaryIssueChange()){ 

printToLog("Secondary Issue Delta."); 

var type = paramArgs.getStringParameter("type"); 

// Submitted change package event 

if (type.equals("submitChangePackage") && (testControlArray[1] 

== true)) { 

msg += "\nSubmitted Change Package "+CP_ID; 

msg += " [ "+paramArgs.getDateParameter("submitDate")+" ]"; 

if(paramArgs.contains("entriesArray")){ 

var tmpStrArray = 

paramArgs.getParameters().get("entriesArray"); 

msg += "\nSubmitted : \n" 

+convertArrayToString(tmpStrArray); 

cpDeltaBean.setFieldValue("State",paramArgs.getStringParameter 

("nextState")); 

cpDeltaBean.setFieldValue("Start Date", 

paramArgs.getDateParameter("startDate")); 

cpDeltaBean.setFieldValue("Finish Date" 

,paramArgs.getDateParameter("finishDate")); 

// Accepted change package event 

} else if (type.equals("acceptChangePackage") && 

(testControlArray[1] == true)) { 

msg += "\nAccepted Change Package"+CP_ID; 

369


370 

msg += " [ "+paramArgs.getDateParameter("acceptDate")+" ]"; 




msg += "\nCommitted : \n" 




// Rejected change package event 

} else if (type.equals("rejectChangePackage") && 


msg += "\nRejected Change Package"+CP_ID; 

msg += " [ "+paramArgs.getDateParameter("rejectDate")+" ]"; 




msg += "\nRejected : \n" 




// Closed change package event 

} else if (type.equals("closeChangePackage") && 


msg += "\nClosed Change Package "+CP_ID; 

// Commit failed change package event 

} else if (type.equals("commitChangePackage") && 

(testControlArray[1] == true)){ 

msg += "\nCommitted Change Package "+CP_ID; 

} else if (type.equals("discardChangePackage") && 

(testControlArray[1] == true)){ 

msg += "\nDiscarded Change Package "+CP_ID; 

} else if (type.equals("discardChangePackageEntry") && 

testControlArray[1]){ 

}else { 

msg += "\nDiscarded Change Package Entries "+CP_ID;

printToLog("Event received not recognized."); 

cpDeltaBean.setFieldValue(msgField,msg); 

if(testControlArray[0]){ 

printToLog(msg); 


dateArray[0] = cpDeltaBean.getNewFieldValue("Created Date"); 

dateArray[1] = cpDeltaBean.getNewFieldValue("Modified Date"); 

dateArray[2] = cpDeltaBean.getNewFieldValue("Start Date"); 

dateArray[3] = cpDeltaBean.getNewFieldValue("Finish Date"); 

retInvocArgs.setDateArrayParameter("refDates",dateArray); 

retInvocArgs.setBooleanParameter("result",true); 

if(testControlArray[2]){ 

var longArray = 

paramArgs.getLongArrayParameter("longArrayTypeTest"); 

var longType = paramArgs.getLongParameter("longTypeTest"); 

printToLog("long Data Type :"+longType); 

printToLog("long Data Type Min :"+longArray[0]); 

printToLog("long Data Type Max :"+longArray[2]); 

var doubleType = 

paramArgs.getDoubleParameter("doubleTypeTest"); 

var doubleArray = 

paramArgs.getDoubleArrayParameter("doubleArrayTypeTest"); 

printToLog("double Data Type :"+doubleType); 

printToLog("double Data Type Min :"+doubleArray[0]); 

printToLog("double Data Type Max :"+doubleArray[2]); 

var intArray = 

paramArgs.getIntArrayParameter("intArrayTypeTest"); 

printToLog("double Data Type :"+intArray[1]); 

printToLog("double Data Type Min :"+intArray[0]); 

printToLog("double Data Type Max :"+intArray[2]); 

server.setReturnValue(retInvocArgs); 

}catch(e){ 

} 

printToLog(e); 

371


372

A PPENDIX 

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 374 

“Running MKS Integrity Server as Application” on page 377 

“Differencing MKS Integrity Server Properties Files” on page 378 

“MKS Integrity Server Logs” on page 379 

“MKS Integrity Client Logs” on page 379 

“MKS Integrity Server Logging Levels” on page 380 

“Miscellaneous Logging Properties” on page 381 

“FLEXnet Logs” on page 384 

“Dr. Watson Logs” on page 384 

“Creating Integrations Log” on page 385 

“si diag” on page 386 

“im diag” on page 387 

“runstacktrace” on page 387 

“mksis” on page 388 

“isutil” on page 389 

“Starting Server in Safe Mode” on page 390 

“Troubleshooting Database Repository” on page 391 

“Troubleshooting Kerberos and Kerberos Single Sign-On” on page 392 

“Troubleshooting MKS Source Reporting” on page 394 

373

Appendix A: Troubleshooting 

Gathering Important Information 

374 

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

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: 

Gathering Important Information 


MKS Integrity Server Version 

To determine your MKS Integrity Server version, do one of the following: 

Browse to http://:. The version and build number appear at the 

bottom of the MKS Integrity Server home page. 

Right click \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 MKS Source) 

im about (for MKS Integrity) 

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 or 

. 

where 

is the directory that the MKS Integrity Server is 

installed in 

is the directory that the MKS Integrity Client is 

installed in 

375


376 

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\IntegrityServer and the default is 

c:\Program Files\MKS\IntegrityClient. 

Is MKS Integrity Server Running? 

1 On the MKS Integrity Server, open: 

\log\server.log 

2 Look for lines of the following form: 

INFO [IntegrityServer] GENERAL(0): Listening on clear port 

 

INFO [IntegrityServer] ApplicationState(0): Integrity Server 

(Build:, Service Pack: ) started 

where 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 

 

where 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 379) 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 

Running MKS Integrity Server as Application 

NOTE If FLEXnet is unavailable, MKS Integrity Server shuts down and displays an 

error message. 

1 To start the FLEXnet configuration utility, start: 

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

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

377


378 

To run the MKS Integrity Server as an application 

1 Stop the MKS Integrity Server service from a command line by changing to 

\bin, and typing the following: 

/bin/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 \bin and type the 

following: 

/bin/mksis[.bat] console 

The command output is sent to the startup.log file. For more information on the 

command, see “mksis” on page 388. 

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. 

Differencing MKS Integrity Server Properties 

Files 

If you change properties files 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 \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.

MKS Integrity Server Logs 

MKS Integrity Server Logs 

The following MKS Integrity Server log files can be useful in diagnosing server errors: 

\log\server.log records server errors and events. 

A new log is automatically started after the previous log reaches 4 MB. Versions of 

server.log are named incrementally, for example, server.log.1, server.log.2 ... 

server.log.n. No more than 25 previous server.log versions are stored. 

\uninstall\.com.zerog.registry.xml records 

all the activities that occurred during the installation of the MKS Integrity Server. 

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

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

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

MKS Integrity Client Logs 

\bin\IntegrityClient.log is the main 

MKS Integrity Client log file. It logs information messages, warnings, and errors. 

\uninstall\.com.zerog.registry.xml records 

all activities that occurred during the MKS Integrity Client installation. 

379


MKS Integrity Server Logging Levels 

380 

The \config\properties\logger.properties file 

allows you to adjust the level of logging information presented by the server. Ten (10) is the 

highest level of logging, and zero (0) disables logging. 

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. The MKS Integrity 

Server must be restarted after each change. The logging output displays in 

server.log file. 

For example, you can adjust the level of logging information for the following property: 

# 

# SI transaction logging for user operations. 

# e.g. To enable logging of SI transactions for user "jdoe": 

# mksis.logger.message.includeCategory.TRANSACTION-jdoe=10 

# 

#mksis.logger.message.includeCategory.TRANSACTION-username=10 

# 

Client Logging Levels 

To increase the level of logging on the MKS Integrity Client, add the following lines to 

\IntegrityClientSite.rc: 

# 

# Turn up logging. 

# 

IntegrityClient.log.message.includeCategory.CACHE=1 

IntegrityClient.log.exception.includeCategory.CACHE=10 

IntegrityClient.log.message.includeCategory.EVENT=10 

IntegrityClient.log.exception.includeCategory.EVENT=10 

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.defaultFormat={2}({3})\: {4}\n 

IntegrityClient.log.exception.defaultFormat={2} {4}\: {6}\n 

IntegrityClient.log.message.includeCategory.WARNING=10 

IntegrityClient.log.message.includeCategory.DEBUG=10 

IntegrityClient.log.message.includeCategory.ERROR=10 

IntegrityClient.log.message.includeCategory.GENERAL=10 

# 

# You can log to the terminal 

# 

#logFileName=stdout 

# 

# You can specify a filename other than the default of

# \bin\IntegrityClient.log. 

# Note the use of escaped backslashes 

# 

#logFileName=c:\\IntegrityClient.log 

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

3 Save your changes. 

4 Restart the MKS Integrity Server. 

381


382 

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.

Category Description 

IM-NOTIFICATION Logs MKS Integrity e-mail notification. 


ACL Logs permission checking to server.log. For example, add label 

command logs following: 

2007-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 MKS Integrity and MKS Source, 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 MKS Requirements commands (rq). For information on available 

commands, see the MKS Integrity for Requirements Management 

Solution Guide. 

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. 


im logging --category=value --level=value 

383


384 

where 

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

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

Creating Integrations Log 

1 Add the following lines to the \IntegrityClient.rc file: 

integrations.debugLogFile=c\:\\\\ 

integrations.debugLogLevel=5 

where \\ is the directory and log file name chosen by you. 

NOTE On Windows 2000, IntegrityClient.rc is located in c:\Documents 

and Settings\. On Windows NT, IntegrityClient.rc is 

located in c:\WINNT\profiles\. 

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. 

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. 

385


si diag 

386 

The si diag command displays license and heap information, outputs properties files, and 

can be used to reclaim the name of a dropped project. 

NOTE You must have the AdminServer or DebugServer ACL permission to run 

this command. 


si diag --diag=value 

where value specifies the diagnostic name. Acceptable diagnostic values for value are as 

follows: 

Diagnostic Description 

backupdatabase a 

Backs up PointBase database to /backup. 

connections Displays list of all server connections. List includes user name, host name, 

port, and time connection established. 

collectsupportpackage a Allows you to assemble 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. 

heap Performs garbage collection and displays memory in use, free memory, and 

total memory in bytes. 

licenses a 

Displays each type of license (MKS Integrity, MKS Source, 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. 

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. 

reclaimprojectname Reclaims project name specified in param option. 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.

Diagnostic Description 

param Specifies project path for project being reclaimed by reclaimproject 

option. Path case sensitive. 

showrepdir Displays list of projects, archives, and directories contained in database 

repository. Requires si.repositoryBrowsingEnabled property to be 

true in si.properties file. 

a AdminServer permission must be used. Admin permission not required. 

im diag 

im diag 

The im diag command also displays license and heap information, and outputs properties 

files. 

NOTE You must have the AdminServer or DebugServer ACL permission to run 

this command. 


im diag --diag=value 

where value specifies the diagnostic name. Acceptable diagnostic values for value are as 

outlined for the si diag command. 

runstacktrace 

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. 

To generate a stack trace, create a file called: 

/data/runstacktrace 

where is the path to the directory where you 

installed the MKS Integrity Server. 

Once you create the runstacktrace file, the MKS Integrity Server then automatically 

creates the /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 /data directory. 

387


mksis 

388 

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 /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: 

/bin/mksis[.bat] 

where is the MKS Integrity Server installation directory. 

The following is the syntax for the command: 

mksis 

where is one of the following: 

console starts the MKS Integrity Server in console mode as an application only without 

the service as specified in: 

/config/mksservice.conf 

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

start starts the MKS Integrity Server service (Windows) or daemon (UNIX) 

stop stops the MKS Integrity Server service (Windows) or daemon (UNIX)

isutil 

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. The isutil utility is installed with the MKS Integrity 

Server in the /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: 

aclexists tests whether the ACL table exists 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. 

cmdbmigrate migrates the MKS Source 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 Source, 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. 

imdbgetversion retrieves the current MKS Integrity database schema version. 

imdbmigrate migrates the MKS Integrity database tables to the current Schema. 

isutil 

389


390 

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 

[ [ []]]). 

An example of isutil command usage is as follows: 

C:\Program Files\MKS\IntegrityServer\bin\isutil -c aclcreate 

Starting Server in Safe Mode 

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 MKS Source or MKS Integrity 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 388). The following is the command syntax for starting the MKS Integrity Server in safe 

mode: 

where 

/bin/mksis console safemode 

is the MKS Integrity Server installation directory 

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: 

/config/mksservice.conf 

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 

2007 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 MKS Source, 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 Source 2007 

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. 

391


392 

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 

MKS Source project names. 

IMPORTANT If the installer cannot alter an existing MKS Integrity database due to 

case mismatches, MKS Integrity and MKS Source 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 

393


394 

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 MKS Source Reporting 

For clients to be able to run MKS Source reports, you must specify Microsoft Access as the 

report application in the \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 MKS Source 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 

Glossary 

Definitions of Common Terms 

B 

This glossary provides a glossary of common terms and definitions for MKS Integrity 

Server, MKS Integrity, and MKS Source. 

administrator The administrator installs and configures the MKS Integrity Server, 

MKSIntegrity, and MKSSource. ForMKSIntegrity, 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. 

aggregate expression An inter-item or aggregate expression use aggregation functions, 

such as sum or average, to perform calculations against fields in a list of items. For 

example, using the sum(field) aggregation function in a report, you can add the 

Estimated Cost field in a list of Project items to produce a total estimated cost. 

aggregate function 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. 

arithmetic function 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. 

change package review A change package review is a review of changes by specified 

reviewers before the changes are committed to the server repository. 

change package reviewer 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. 

change package watcher 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. 

395

Appendix B: Glossary 

396 

change package 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 are added when you specify a change package 

while performing member operations. 

charts 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. Trend charts may 

be displayed as line graphs or bar graphs. Distribution charts may be displayed as pie graphs 

or bar graphs. Data may also be displayed in tabular form. 

command line interface (CLI) 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. 

computed expression 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. 

computed field A computed field allows 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. 

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

following components: charts, reports, images, labels, and links to reports, queries and Web 

sites. 

drop (a project) To drop a 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. 

event trigger An event trigger is a block of code associated with a predefined event. The 

script performs a specified action and is executed whenever the event occurs. For example, 

you could set up an event trigger to run every time a user checks in a file. 

external information function 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. 

graphical user interface (GUI) 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

Glossary 

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. 

importing (a project or member) Importing a project or member registers it with the 

MKS Integrity Server. Once a project or member is imported, MKS Source commands can be 

performed upon it. 

inter-item expression An inter-item or aggregate expression use aggregation functions, such 

as sum or average, to perform calculations against fields in a list of items. For example, using 

the sum(field) aggregation function in a report, you can add the Estimated Cost field in a 

list of Project items to produce a total estimated cost. 

intra-item expression An intra-item expression performs 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). 

presentation template Presentation templates are customizable layouts for displaying items 

in MKS Integrity. 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. 

production server When migrating MKS Integrity administrative objects, the MKS Integrity 

Server that users connect to is known as the production server. 

project administrator MKS Integrity project administrators are allowed to edit and view 

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 In MKS Integrity, a project contains labels that help you sort and organize items in a 

hierarchical structure. 

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

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. 

reports In MKS Integrity, 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. In 

MKS Source, reports provide an analysis of projects, members, or individual archives. 

Reports and graphs can be printed or viewed on screen. 

397


398 

shared subproject A shared subproject is a subproject that is a member of more than one 

project. MKS Source allows you to 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. 

staging server For the purpose of migrating MKS Integrity administrative objects, the 

separate server for testing your configuration is called a staging server (while the 

MKS Integrity Server that users connect to is called the production server). It is possible to 

have two staging servers (a development and a test server) with a production server. 

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 was in the In Development state. The computed value is then 

stored in the computed field. 

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. 

subproject MKS Source allows you to create large 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. 

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 MKS Integrity projects and types to a project administrator 

and type administrator. 

super reviewer A super reviewer is a user with permission to vote on change packages, but 

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. 

text function 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. 

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. 

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

Glossary 

ViewSet 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 

workflow Each MKS Integrity 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 the following states: submitted, work started, 

tested, reviewed, and closed. Items and their current states provide change management 

information necessary to support business decisions. 

399


400

Index 

A 

access keys 

MKS Integrity Administration Client 16 

admin migration 

copying database 152 

e-mail notification 151 

managing admin locks 154 

staging server startup 152 

testing IM configuration 153 

using admin locks 155 

wizard 147–160 

using 156 

admin object 

converting to 219 

references 220 


application window 12 

command line interface 41 

connecting to an Integrity Server 28 

disconnecting from an Integrity Server 29 


Change Package Types view 297 

Fields view 104 

Projects view 229 

States view 77 

Types view 82 

opening the interface 10 

preferences 

setting 37 

shutting down the interface 12 

administrator 

assigning 74–77 

described 4 


project 74, 240 

super 74 

type 93 

project 

assigning 241 

super 4 

role 5 

super, described 74 

type 

assigning 95 

aggregated function 

described 274 

aggregation expression 

described 271 

allow 

branching 89 

labels 89 

project backing 88 

time entries 88 

arithmetic function 

described 274 

arithmetic operators 

computed expression 271 

assessing process 70 

attachment data type 

described 107 

attachment size 

configuring in MKS Integrity 214 

Authorization Administration 

preferences, setting 39 

B 

boolean operators 


branching 

enabling 89 

building block 


deleting 161 

C 

calculate 

computed field 

dynamic 286 

static 287 

state metrics 290 

capabilities, state-based 79, 100 

cell properties, default 177 

401

Index 

change package 

allowing 79, 80, 85, 100 

described 296, 315 

review process 

how it works 317 

type 296 

customizing 299 

viewing 303 

Change Package Types view 


Administration Client 297 

changing 

MKS Source event trigger resolution order 

353 

order of states 81 

character sets 

controlling 163 

chart 

described 214 

historical trends using computed fields 

287 

checkmark, tab 193 

choose 

groups 21 

MKS Integrity projects 22 

principals 21 

users 21 

client 

Administration 10 

Administration window 12 

logging 

HTTP messages 381 

client-side 

event triggers, MKS Source 355 

environment variables 362 

closing 

client 11 

collecting 

properties and log files 30 

command 

im logging 383 

si createproject 245 

si dropproject 250 

si import 249 

si importproject 247 

si logging 382 

command line interface 


described 41 

common project 

potential problems 267 

402 

components 

MKS Source event trigger 347 

subproject 260 

computed expression 

described 269 

function classes 274 

group fields 274 

rules 271 

types 270 

user fields 274 

computed field 

charting historical trends 287 

computation times 

scheduling 290 

creating 284 

performance 293 

scalability 293 

security 292 

state metrics 

calculating 290 

static 

calculating 287 

conditions 

defining 41 

configuration management 244 

configuring 

attachment size, MKS Integrity 214 

preferences 32 

query limit 

group timeout 216 

maximum item count 216 

query limit, MKS Integrity 214 


text searching, MKS Integrity 217 

connecting 

to an Integrity Server 28 

context based text search 

in MKS Integrity 217 

converting 

user objects to admin 219 

copy 

item tree 89 

copying 

item presentation template 196 

type 91 

create 

computed field 284 

state metrics 290 

creating 

a support package 30 

event triggers 

MKS Integrity 327

field 106 

field relationships 134 


project 232 

using CLI 245 

state 78 

type 84 

workflow 140 

custom reports, MKS Integrity 201 

images 204 

report tags 205 

template files 203 

customize 

rich content fields 199 

customizing item presentation 170 

cells 187 

designer 171 

grids 186 

images 194 

labels 189 

logos 195 

previewing 179 

properties 174 

default cell 177 

default grid 176 

default text style 176 

general 174 

text style 175 

setting template 183 

D 

dashboard 

described 6 

data 

filtering 17 

searching 17 

data conversion 


data type 

attachment 

described 107 

date 

described 112 

field value attribute 

described 109 

floating point 

described 111 

group 

described 117 

integer 

described 108 

item backed picklist 

described 108 

logical 

described 112 

long text 

described 114 

phase 

described 120 

pick 

described 110 

query backed relationship 

described 121 

range 

described 122 

relationship 

described 117 

short text 

described 113 

SI project 

described 124 

user 

described 116 

database 

copying for admin migration 152 

date data type 

described 112 

date operations 


deactivating 

pick list values 130 

project 239 

default cell properties 177 

default grid properties 176 

default text style properties 176 

defining logical conditions 41 

deleting 

building block 161 

field 131 


item 161 


project 237 

state 81 

type 92 

designing 

custom presentation template 170 

project 266–268 


diagnostics 

client logging level 380 

Index 

403

Index 

differencing files 378 

environment information 374 

FLEXNet logs 384 

IDE log 385 

log files 379 

running server as application 377 

tools 386 

dialog box 

option prompts 33 

directory tree 243 

hierarchical structures 243 

disconnecting 

from an Integrity Server 29 

from server 11 

display 

type workflow 88 

display pane 

graphical user interface 15 

display pattern 27 

Dr. Watson logs 384 

drop project, described 249 

E 

ECMAScript 347 

editing 

field 129 



project 235 

state 80 

type 90 

electronic signatures 218 

customizing triggers 218 

e-mail 

controlling character sets 163 

notification 5 

permission 163 

notification of admin lock break 151 

empty fields 


enable 

branching 89 

labels for items 89 

project backing 88 

time entries 88 

encrypted archives 246 

env.properties file 349 

environment information, for diagnostics 374 

environment variables 

MKS Source triggers 362 

404 

event 

in MKS Source 340 

event trigger 

client-side 355 

described 323 


adding script to library 338 

creating 327 

creating rule based change trigger 

327 

creating scheduled trigger 331 

creating time entry trigger 334 

defining rule based change trigger 

329 

deleting 336 


disable scheduled 333 

editing 336 

how to use 323 

managing 326 

planning 325 

post-event 325 

pre-created scripts 337 

pre-event 324 

resolution order 337 

rule based event 323 

running a scheduled trigger 335 

schedule event 323 

schedule frequency 333 

schedule query 333 

schedule running using CLI 333 

schedule running using GUI 335 

script library 337 

selecting scripts 330 

time entry event 323 

viewing 335 

writing 338 

MKS Source 340–355 

changing resolution order 353 


components 347 

env.properties file 349 

event definition files 347 

event trigger scripts 347 

global context 346 

information 355 

member event 340 

planning 349, 350 

post-test 345 

pre-configured as enabled 348 

pre-test 345 

project context 346

project event 341 

properties file 347 

referencing Beans 350 

resolution 352 

revision event 341 

saving your script 351 

scripts 347 

sequence of operations 345 

server event 342 

si.triggers.disabled 348 

si.triggers.disableSubProjects 348 

si.triggers.enable 348 

si.triggers.environmentVariables 349 

si.triggers.events 348 

si.triggers.mailServer 349 

si.triggers.resolution 348 

si.triggers.resolutionOrder 349 


triggers.scripts 349 

type 346 

updating global events definition 

template 352 

using JavaScript 345 

variable declared as JavaBeans 345 

writing 350 

external information function 

described 275 

F 

favorites 

selecting 26 

field 

computed 

creating 284 

creating 106 

deleting 131 

editing 129 

managing 102 

moving 132 

pick, multiple values 110 

rich content 


setting field relevance 124 

viewing 130 

visibility 101 

field relationships 

creating 134 

default columns 124 

deleting 137 

editing 137 

managing 132 

field value attribute data type 

described 109 

Fields view 



file 

importing 247 

importing using CLI 248, 249 

filter 

data 17 

groups 21 


principals 21 

users 21 

finding 

properties and log files 30 

FLEXlm 

log files 384 

floating point data type 

described 111 

format 

numeric values 27 

function 

aggregate 

described 274 

arithmetic 

described 274 

external information 

described 275 

text 

described 274 

function classes 


FVA field 

described 109 

G 

general 

template properties 174 

graphical user interface 

described 10 

display pane 15 

menu bar 13 

shortcut menu 14 

status bar 16 

title bar 13 

toolbars 14 

tooltips 16 

tree pane 14 

Index 

405

Index 

workspace 16 

grid properties, default 176 

group 

deleting 161 

project permission 230 

selecting 21 

group data type 

described 117 

group fields 


H 

hide 

data 17 

I 

IBPL field 

described 108 

im diag 

command 387 

im logging command 383 

im recomputehistory command 287 

image, saving workflow 146 

images for reports 204 

importing 

files 247 

project 

using CLI 247 

viewset 50 

integer data type 

described 108 

Integrity Client 

logging level 380 

logs 379 

preferences 

setting 33 

version number 375 

Integrity Server 

connecting to 28 

disconnecting from 29 

logging levels 380 

version number 375 

intra-item expression 


is.properties file 

controlling character sets 163 

isutil 

command 389 

406 

item 

copying tree 89 

copying tree heirarhcy 89 

deleting 161 

linking with a project 237 

item backed picklist data type 

described 108 

item presentation template 170, 171 

cells 187 

copying 196 

creating 181 

deleting 198 

editing 185 

grids 186 

images 194 

labels 189 

logos 195 



default cell 177 


default text style 176 

general 174 


setting 183 

tabs 192 

viewing 197 

K 

kerberos 

troubleshooting 392 

L 

labels 

enabling 89 

launching 

the Administration Client 10 

limit 

query 



lock 

managing admin 154 

using admin 155 

log files 

collecting 30 

Dr. Watson 384 

FLEXNet server 384 

for diagnostics 379

integrations 385 

Integrity Client 379 

logging 

HTTP messages 381 

levels 


Integrity Server 380 

MKS Integrity 383 

MKS Source 382 

logging on 


logical conditions 

defining 41 

logical data type 

described 112 

logo 

adding to custom template 195 

long text data type 

described 114 

long text fields 


M 

manage 

project metadata 237 

managing 

field 102 

creating 106 

editing 129 

moving 132 

viewing 130 


pick list values 

deactivating 130 

project 229 

creating 232 


deleting 237 

editing 235 

moving 237 

reparenting 237 

viewing 236 

state 77–81 

creating 78 

deleting 81 

editing 80 

metrics 81 

moving 81 

viewing 80 

type 82 

copying 91 

creating 84 

deleting 92 

editing 90 

moving 93 

repositioning 93 

viewing 91 

maximum item count, query timeout 216 

member 

event, in MKS Source 340 

importing 247 

importing using CLI 249 

importing using GUI 248 

menu bar 


messages 

HTTP-related 381 

metrics 

state 81 

creating 290 

tracking for projects 257 


attachment size 214 

custom reports 201 

images 204 

report tags 205 



event trigger 

creating rule based change trigger 

327 

creating scheduled trigger 331 

creating time entry trigger 334 

defining rule based change trigger 

329 

deleting 336 


disable scheduled 333 

editing 336 

how to use 323 

managing 326 

planning 325 

post-event 325 

pre-created scripts 337 

pre-event 324 


rule based event 323 

running a scheduled trigger 335 

schedule event 323 

schedule frequency 333 

schedule query 333 

Index 

407

Index 

schedule running using CLI 333 

schedule running using GUI 335 


selecting scripts 330 

time entry event 323 

viewing 335 

printing views 30 

project administrator 74, 240 

query limit 214 



setting up 4–7 

states 

described 77 

super administrator 74 

time entry 

allowing 79, 80, 100 

type administrator 93 

understanding 4–7 

using 4–7 

workflow 5 

workflow migration 


summary steps 148, 149 


access keys 16 

ACLs 39 

shortcut keys 16 

MKS Integrity Server 

serial number 374 

MKS Source 

change package 

allowing 79, 80, 85, 100 

client-side triggers 

environment variables 362 

event 340 

event trigger 340–355 


information 355 

member event 340 

planning 349, 350 

post-test 345 

pre-configured as enabled 348 

pre-test 345 

project context 346 

project event 341 

properties file 347 



revision event 341 

408 


sequence of operations 345 

server event 342 


type 346 

using JavaScript 345 

variable declared as JavaBeans 345 

writing 350 

event trigger property 

si.triggers.disabled 348 

si.triggers.disableSubProjects 348 

si.triggers.enable 348 

si.triggers.events 348 

si.triggers.resolution 348 

si.triggers.resolutionOrder 349 

si.triggers.scripts 349 

triggers.environmentVariables 349 

triggers.mailServer 349 

events definition file 347 

global event trigger 346 

project 244–250 

reporting 

troubleshooting 394 


mksis 

command 388 

moving 

field 132 

project 237 

state 81 

type 93 

multiple servers 

configuring 35 

multiple value 

pick field 110 

N 

notification 

e-mail 5 


numeric values 

formatting 27 

O 

opening the Administration Client 10 

logging on 10 

organizing projects 243

P 

performance 

computed fields 293 

permission 


phase data type 

described 120 

pick data type 

described 110 

pick field 

allowing multiple values 110 

pick list values 


planning MKS Source event trigger 

performance 350 

pre- or post-event 349 

system security 349 

post-test MKS Source event trigger 345 

preferences 


setting 37 

Authorization Administration 

setting 39 

Integrity Client 

setting 33 

server 

setting 35 

setting 32 

toolbar 

setting 37 

presentation template 170 

cells 187 

copying 196 

creating 181, 185, 197, 198 

described 171 

designer 171 

grids 186 

images 194 

labels 189 

logos 195 




general 174, 176, 177 


setting 183 

tabs 192 

presentation templates 

reports 201 

pre-test MKS Source event trigger 345 

principal 

selecting 21 

printing 

MKS Integrity views 30 

workflow 146 

process 

assessing 70 

production server 

installing and starting 150 

project 244–250, 257 

administrator 

assigning 241 

administrator, described 240 

administrator, MKS Integrity 240 

browsing MKS Source projects 25 

common 266 

creating 232 


deleting 161, 237 

designing 266 

directory 243 

editing 235 


linking with an item 237 

managing 229 

member 

sharing 265 

metadata 

managing 237 

moving 237 

organization 243 


reparenting 237 

restoring 

in CLI 251 

restoring to a previous checkpoint 250 

selecting MKS Integrity projects 22 

selecting MKS Source projects 25 

sharing archive 265 

sharing member 265 

single directory 243 

viewing 236 

visibility 230 

project backing 

enabling 88 

Projects view 



prompts 

dialog boxes 33 

properties 

collecting 30 

Index 

409

Index 

proxy server 

preferences 

setting 35 

Q 

quantify 

numeric values 27 

query 

described 214 

limit 




query backed relationship data type 

described 121 

quick access keys 


access keys 16 

shortcut keys 16 

R 

range data type 

described 122 

RCS 

directory 244 

references, viewing 220 

relationship data type 

default columns 124 

described 117 

relevance 124 

described 124 

reparenting 

project 237 

reports 201 

described 201 

images 204 

tags 205 


repositioning 

type 93 

resolution 

MKS Source event triggers 352 

restoring project 

in CLI 251 

restoring project to a previous checkpoint 250 

review 

process 

change packages, how it works 317 

410 

revision 


rich content fields 


role 

super administrator 5 

rule selection 45 

rules 

computed expressions 271 

selecting 45 

S 

saving workflow, as image 146 

scalability 


schedule 

computed field computations times 290 


search 

data 17 

groups 21 


principals 21 

users 21 

searching 

context based 217 

secure sockets layer 7 

security 


realm 

debugging 381 

select 

favorites 26 

group 21 


user 21 

selecting 

rules 45 

serial number 

locating 374 

server 

disconnecting 11 


preferences, setting 35 

session 

closing client 11 

shutting down client 12 

setting 

administrators 74–77 

preferences 32

setting up 

MKS Integrity 4–7 

shared subproject 

adding 262 

sharing 

archive 

with other project 265 

member 265 

file ownership 265 

solution 266 

update/compatibility concerns 265 

short text data type 

described 113 

shortcut 

keys 


16 

menu 


show 

data 17 

shutting down 



si command 

createproject 245 

diag 386 

dropproject 250 

import 249 

importproject 247 

logging 382 

si diag 

command 386 

SI project data type 

described 124 

si.properties file 347 

signatures 

electronic 218 

customizing triggers 218 

SSL 

See secure sockets layer 

staging server 

installing and starting 150 

starting 152 

starting 

the Administration Client 10 

the Integrity Server 

in Safemode 390 

using mksis 388 

state 

capabilities 79, 100 

creating 78 

deleting 81 

described 

MKS Integrity 77 

edit workflow 145 

editing 80 

managing 77–81 

metrics 81 

moving 81 

transitions 

workflow 144 

viewing 80 

state metrics 

creating 290 

States view 



status bar 



adding 261 

adding shared 262 

components 260 

configuring 263 

creating 260 

defined 260 

designing 266 

event triggers 346 

super administrator, described 74 

support package 

creating 30 

syntax 


T 

tab 

checkmark 193 


tags, for reports 205 

template 

designer 

cells 187 

grids 186 

images 194 

images, logo 195 

labels 189 

files, for reports 203 

item presentation 

copying 196 

creating 181 

deleting 198 

Index 

411

Index 

designer 171 

editing 185 



tabs 192 

viewing 197 

text fields 


text function 

described 274 

text searching 


text style properties 175 

time entry 

allowing 79, 80, 100 

enabling 88 

timeout 

query 

group 216 


timestamps 


title bar 


toolbar 


preferences 

setting 37 

tools 

diagnostic 386 

si diag command 386 

tooltips 


tracking metrics for 257 

tree pane 


troubleshooting 

client logging level 380 

differencing files 378 

environment information 374 

FLEXNet logs 384 

IDE log 385 

kerberos 392 

log files 379 

MKS Source 

reporting 394 

running server as application 377 

tools 386 

type 

administrator 

assigning 95 

described 93 

412 

administrator, MKS Integrity 93 

branching 

enabling for type 89 

change package 296 


viewing 303 

copying 91 

creating 84 

deleting 92, 161 

editing 90 

field visibility 101 

labelling for items 89 

managing 82 

moving 93 

project backing 

enabling 88 

repositioning 93 

time entries 

enabling 88 

viewing 91 

workflow 

displaying 88 

Types view 



U 

understanding MKS Integrity 4–7 

updating MKS Source global events 

definition template 352 

user 

deleting 161 

described 4 

group 

project permission 230 

selecting 21 

user data type 

described 116 

user fields 


user objects 

converting to admin 219 

using MKS Integrity 4–7 

V 

variables 

environment 

client-side triggers 362

version number 


Integrity Server 375 

viewing 

admin object references 220 

change package types 303 

field 130 


project 236 

state 80 

type 91 

workflow 142 

views 

printing 30 

viewset 

importing 50 

managing 50 

visibility 101, 230 

fields 101 

project 230 

W 

workflow 5, 139 

creating 140 

described 138 

edit 

state 145 

managing (editing) 143 

printing 146 

save as image 146 

state transitions 144 

type 

displaying 88 

view 138 

described 138 

viewing 142 

workflow migration 147–160 

coping database 152 


installing 

production server 150 

staging server 150 

managing admin locks 154 

staging server startup 152 

summary steps 148, 149 

testing IM configuration 153 

using admin locks 155 

using wizard 156 

workspace 


writing MKS Source event triggers 350 

looking up the Bean 350 



Index 

413

Index 

414

Product Notices 

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

U.S. Government Restricted Rights. The software and 

documentation provided to you (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 in the applicable acquisition 

regulations. If you are the U.S. Government or any agency or 

department thereof (collectively referred to as the 

“Government”), 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 to the extent that such 

rights are consistent with this paragraph. If you are any agency of 

the Department of Defense of the Government, the following 

notice is given: The Software and Documentation are provided 

with RESTRICTED RIGHTS. You shall not use, duplicate or 

disclose the Software or Documentation in any way not 

specifically permitted by MKS Software Inc. or mandated by U.S. 

law. Manufacturer is MKS Software Inc., 410 Albert Street, 

Waterloo, Ontario Canada N2L 3V3. 

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 Jakarta Commons Logging 1.0.3 

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 


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:/ 

/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 includes the Extreme! Computing XPP3-1.1.3.2. 

software developed by the Indiana University Extreme! Lab 

(http://www.extreme.indiana.edu/). Copyright © 2002 

Extreme! Lab, Indiana University. 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 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 University” 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– 

2005, publicobject.com, O'Dell Engineering Ltd. 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 Bean Scripting Framework Version 2.2 

developed by The Apache Software Foundation (http:// 

www.apache.org/). Licensed under the Apache License, Version 

1.1. Copyright © 2002 The Apache Software Foundation. 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 disclaimer in the documentation and/or other 




software developed by the Apache Software Foundation (http:/ 

/www.apache.org/).”; 4. The names “BSF” “Apache” 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 WARRANTIES, INCLUDING, 

BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 

MERCHANTABILITY AND FITNESS FOR A PARTICULAR


PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 

APACHE SOFTWARE FOUNDATION 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 IBM Toolbox for Java software. 

Copyright © up to and including 2006, 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 DIRECT, INDIRECT, INCIDENTAL, 









POSSIBILITY OF SUCH DAMAGE 

This product contains ICU v. 1.8.1. Copyright © 1995–2003 

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. All trademarks and registered trademarks 

mentioned herein are the property of their respective owners. 

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 © 

1999–2001 The Apache Software Foundation. All rights reserved. 












/www.apache.org/).”; Alternately, this acknowledgement may 

appear in the software itself, if and wherever such third-party 

acknowledgements 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 





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 


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 

above copyright notice, this list of conditions and the following 

disclaimer. Redistributions in binary form must reproduce the 


disclaimer in the documentation and/or other materials provided 

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 


conditions are met: Redistributions of source code must retain the 





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 

NOT LIMITED TO, THE IMPLIED WARRANTIES OF 

MERCHANTABILITY AND FITNESS FOR A PARTICULAR 


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 software 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 

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. 

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 or implied. See the License for the specific language 

governing 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 © 1997–1999 

Netscape Communications Corporation. All Rights Reserved. 

Contributor(s): Norris Boyd 

This product contains JBoss version 4.0.4. Copyright © 2004–2007 

JBoss, Inc. 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 Jdesktop Integration Components. 

Copyright © 2004 Sun Microsystems, Inc. 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 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 




License for more details. You should have received a copy of the





This product contains Xerces 2.6.0 developed by The Apache 

Software Foundation (http://www.apache.org/) licensed 

under the Apache License, Version 1.1. Copyright © 2000–2002 

The Apache Software Foundation. All rights reserved. 












/www.apache.org/).; 4. The names “Xerces”, “Apache“ and 

“Apache Software Foundation“ must not be used to endorse or 




not be called “Apache”, nor may “Apache“ appear in their name, 


















This product contains jTDS Drivers version 1.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 




PARTICULAR PURPOSE. See the GNU Lesser General Public 





Copyright © 1998, 1999, JXML, Inc. All rights reserved. 



conditions are met: Redistributions of source code must retain the 





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 


IN NO EVENT SHALL JXML OR CONTRIBUTORS BE LIABLE 

FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 

EXEMPLARY, OR CONSEQUENTIAL DAMAGES 









This product includes Log4J software developed by The Apache 

Software Foundation (http://www.apache.org/) licensed 

under the Apache Software License, Version 1.1. Copyright © 

1999 The Apache Software Foundation. All rights reserved. 












/www.apache.org/).”; Alternately, this acknowledgment may 


acknowledgments normally appear. 4. The names “log4j“ and 























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 © 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–2007 The OpenSSL Project. All rights reserved. 



conditions are met: 1. Redistributions of source code must retain





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 




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. 

This package is an SSL implementation written by Eric Young 

(eay@cryptsoft.com). Redistribution and use in source and binary 



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, 










SUCH DAMAGE. 


This product contains Sapia Ubik software developed by Sapia 

Open Source Software. Copyright © 2002, 2003 Sapia Open 

Source Software. 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 reproduce the above 

copyright notice, this list of conditions and the following 


with the distribution. The end-user documentation included with 

the redistribution, if any, must include the following 

acknowledgment: “This product includes software developed by 

Sapia Open Source Software Organization (http://www.sapiaoss.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 





IN NO EVENT SHALL THE SAPIA OSS ORGANIZATION OR 

ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 










SUCH DAMAGE. 

This product contains JDOM software. Copyright © 2000–2004 

Jason Hunter & Brett McLaughlin. All rights reserved. 




the above copyright notice, this list of conditions, and the 


reproduce the above copyright notice, this list of conditions, and 

the disclaimer that follows these conditions in the documentation 

and/or other materials provided with the distribution. 3. The 

name “JDOM“ must not be used to endorse or promote products 


written permission, please contact 

. 4. Products derived from this 

software may not be called “JDOM", nor may “JDOM“ appear in 

their name, without prior written permission from the JDOM 

Project Management . In addition, 

we request (but do not require) that you include in the end-user 

documentation provided with the redistribution and/or in the 

software itself an acknowledgement equivalent to the following: 

“This product includes software developed by the JDOM Project 

(http://www.jdom.org/).”; Alternatively, the acknowledgment 

may be graphical using the logos available at http:// 

www.jdom.org/images/logos. THIS SOFTWARE IS 





IN NO EVENT SHALL THE JDOM AUTHORS OR THE 

PROJECT CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 





INTERRUPTION) HOWEVER CAUSED AND ON ANY






SUCH DAMAGE. 

Portions of this product are Copyright 2007, Microsoft 

Corporation. All rights reserved. 

This product contains W3C Sirpac. This work (and included 

software, documentation such as READMEs, or other related 

items) is being provided by the copyright holders under the 

following license. By obtaining, using and/or copying this work, 

you (the licensee) agree that you have read, understood, and will 

comply with the following terms and conditions. Permission to 

copy, modify, and distribute this software and its documentation, 

with or without modification, for any purpose and without fee or 

royalty is hereby granted, provided that you include the 

following on ALL copies of the software and documentation or 

portions thereof, including modifications: The full text of this 

NOTICE in a location viewable to users of the redistributed or 

derivative work. Any pre-existing intellectual property 

disclaimers, notices, or terms and conditions. If none exist, the 

W3C Software Short Notice should be included (hypertext is 

preferred, text is permitted) within the body of any redistributed 

or derivative code. Notice of any changes or modifications to the 

files, including the date changes were made. (We recommend you 

provide URIs to the location from which the code is derived.) 

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED 

“AS IS,“ AND COPYRIGHT HOLDERS MAKE NO 

REPRESENTATIONS OR WARRANTIES, EXPRESS OR 

IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES 

OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR 

PURPOSE OR THAT THE USE OF THE SOFTWARE OR 

DOCUMENTATION WILL NOT INFRINGE ANY THIRD 

PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER 

RIGHTS. COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR 

ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL 

DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE 

OR DOCUMENTATION. The name and trademarks of copyright 

holders may NOT be used in advertising or publicity pertaining 

to the software without specific, written prior permission. Title to 

copyright in this software and any associated documentation will 

at all times remain with copyright holders. 

This product contains XML Parsing Library for C version 2.6.7. 

Copyright © 1998–2003 Daniel Veillard. All Rights Reserved. 


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 


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 




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. 

This product contains the Sun Java 1.5.0 Update Platform which 

may include the following software: 

The following software may be included in this product: CS 

CodeViewer v1.0; Use of any of this software is governed by the 

terms of the license below: Copyright 1999 by CoolServlets.com. 

This software is distributed under the terms of the BSD License. 








materials provided with the distribution. Neither name of 

CoolServlets.com 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 COOLSERVLETS.COM AND CONTRIBUTORS 

“AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, 




SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 

ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 

EXEMPLARY, OR CONSEQUENTIAL DAMAGES 









The following software may be included in this product: Crimson 

v1.1.1; Use of any of this software is governed by the terms of the 

license below: / The Apache Software License, Version 1.1 

Copyright © 1999–2000 The Apache Software Foundation. All 












/www.apache.org/).“; Alternately, this acknowledgment may 


acknowledgments normally appear. 4. The names “Crimson“ and 























The following software may be included in this product: Xalan J2; 

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.

The following software may be included in this product: NSIS 

1.0j; Use of any of this software is governed by the terms of the 

license below: Copyright © 1999–2000 Nullsoft, Inc. This software 

is provided “as-is”, without any express or implied warranty. In 

no event will the authors be held liable for any damages arising 

from the use of this software. Permission is granted to anyone to 

use this software for any purpose, including commercial 

applications, and to alter it and redistribute it freely, subject to the 

following restrictions: 1. The origin of this software must not be 

misrepresented; you must not claim that you wrote the original 

software. If you use this software in a product, an 

acknowledgment in the product documentation would be 

appreciated but is not required. 2. Altered source versions must 

be plainly marked as such, and must not be misrepresented as 

being the original software. 3. This notice may not be removed or 

altered from any source distribution. Justin Frankel 

justin@nullsoft.com“ Some Portions licensed from IBM are 

available at: http://oss.software.ibm.com/icu4j/ Portions 

Copyright Eastman Kodak Company 1992 Lucida is a registered 

trademark or trademark of Bigelow & Holmes in the U.S. and 

other countries. Portions licensed from Taligent, Inc. 

The following software may be included in this product: IAIK 

PKCS Wrapper; Use of any of this software is governed by the 

terms of the license below: Copyright © 2002 Graz University of 

Technology. 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 disclaimer in the documentation 


end-user documentation included with the redistribution, if any, 

must include the following acknowledgment: “This product 

includes software developed by IAIK of Graz University of 

Technology.“ Alternately, this acknowledgment may appear in 

the software itself, if and wherever such third-party 

acknowledgments normally appear. 4. The names “Graz 

University of Technology“ and “IAIK of Graz University of 

Technology“ must not be used to endorse or promote products 

derived from this software without prior written permission. 5. 

Products derived from this software may not be called “IAIK 

PKCS Wrapper”, nor may “IAIK“ appear in their name, without 

prior written permission of Graz University of Technology. THIS 

SOFTWARE IS PROVIDED “AS IS” AND ANY EXPRESSED OR 




IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY 










SUCH DAMAGE. 

The following software may be included in this product: 

Document Object Model (DOM) v. Level 3; Use of any of this 

software is governed by the terms of the license below: W3C® 

SOFTWARE NOTICE AND LICENSE http://www.w3.org/ 

Consortium/Legal/2002/copyright-software-20021231 

This work (and included software, documentation such as 

READMEs, or other related items) is being provided by the 

copyright holders under the following license. By obtaining, 

using and/or copying this work, you (the licensee) agree that you 

have read, understood, and will comply with the following terms 

and conditions. Permission to copy, modify, and distribute this 

software and its documentation, with or without modification, 

for any purpose and without fee or royalty is hereby granted, 

provided that you include the following on ALL copies of the 


software and documentation or portions thereof, including 

modifications: 1. The full text of this NOTICE in a location 

viewable to users of the redistributed or derivative work. 2. Any 

pre-existing intellectual property disclaimers, notices, or terms 

and conditions. If none exist, the W3C Software Short Notice 

should be included (hypertext is preferred, text is permitted) 

within the body of any redistributed or derivative code. 3. Notice 

of any changes or modifications to the files, including the date 

changes were made. (We recommend you provide URIs to the 

location from which the code is derived.) THIS SOFTWARE AND 

DOCUMENTATION IS PROVIDED “AS IS,“ AND COPYRIGHT 

HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, 

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, 

WARRANTIES OF MERCHANTABILITY OR FITNESS FOR 

ANY PARTICULAR PURPOSE OR THAT THE USE OF THE 

SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE 

ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS 

OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE 

LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR 

CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF 

THE SOFTWARE OR DOCUMENTATION. The name and 

trademarks of copyright holders may NOT be used in advertising 

or publicity pertaining to the software without specific, written 

prior permission. Title to copyright in this software and any 

associated documentation will at all times remain with copyright 

holders. This formulation of W3C’s notice and license became 

active on December 31, 2002. This version removes the copyright 

ownership notice such that this license can be used with materials 

other than those owned by the W3C, reflects that ERCIM is now a 

host of the W3C, includes references to this specific dated version 

of the license, and removes the ambiguous grant of “use”. 

Otherwise, this version is the same as the previous version and is 

written so as to preserve the Free Software Foundation’s 

assessment of GPL compatibility and OSI's certification under the 

Open Source Definition. Please see our Copyright FAQ for 

common questions about using materials from our site, including 

specific terms and conditions for packages like libwww, Amaya, 

and Jigsaw. Other questions about this notice can be directed to 

site-policy@w3.org. 

The following software may be included in this product: Xalan, 

Xerces; Use of any of this software is governed by the terms of the 

license below: / The Apache Software License, Version 1.1 

Copyright © 1999–2003 The Apache Software Foundation. All 












/www.apache.org/).“ Alternately, this acknowledgment may 


acknowledgments normally appear. 4. The names “Xerces“ and 

















PROFITS; OR BUSINESS INTERRUPTION) HOWEVER







The following software may be included in this product: W3C 

XML Conformance Test Suites v. 20020606; Use of any of this 

software is governed by the terms of the license below: W3C® 

SOFTWARE NOTICE AND LICENSE Copyright © 1994–2002 

World Wide Web Consortium, (Massachusetts Institute of 

Technology, Institut National de Recherche en Informatique et en 

Automatique, Keio University). All Rights Reserved. http:// 

www.w3.org/Consortium/Legal/ This W3C work (including 

software, documents, or other related items) is being provided by 

the copyright holders under the following license. By obtaining, 

using and/or copying this work, you (the licensee) agree that you 


and conditions: Permission to use, copy, modify, and distribute 

this software and its documentation, with or without 

modification, for any purpose and without fee or royalty is 

hereby granted, provided that you include the following on ALL 

copies of the software and documentation or portions thereof, 

including modifications, that you make: 1. The full text of this 

NOTICE in a location viewable to users of the redistributed or 

derivative work. 2. Any pre-existing intellectual property 

disclaimers, notices, or terms and conditions. If none exist, a short 

notice of the following form (hypertext is preferred, text is 

permitted) should be used within the body of any redistributed 

or derivative code: “Copyright © up to and including 2006 World 

Wide Web Consortium, (Massachusetts Institute of Technology, 

Institut National de Recherche en Informatique et en 

Automatique, Keio University). All Rights Reserved. http:// 

www.w3.org/Consortium/Legal/“ 3. Notice of any changes or 

modifications to the W3C files, including the date changes were 

made. (We recommend you provide URIs to the location from 

which the code is derived.) THIS SOFTWARE AND 

DOCUMENTATION IS PROVIDED “AS IS,“ AND COPYRIGHT 


EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, 

WARRANTIES OF MERCHANTABILITY OR FITNESS FOR 

ANY PARTICULAR PURPOSE OR THAT THE USE OF THE 

SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE 

ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS 

OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE 

LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR 

CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF 

THE SOFTWARE OR DOCUMENTATION. The name and 

trademarks of copyright holders may NOT be used in advertising 

or publicity pertaining to the software without specific, written 

prior permission. Title to copyright in this software and any 

associated documentation will at all times remain with copyright 

holders. This formulation of W3C’s notice and license became 

active on August 14 1998 so as to improve compatibility with 

GPL. This version ensures that W3C software licensing terms are 

no more restrictive than GPL and consequently W3C software 

may be distributed in GPL packages. See the older formulation 

for the policy prior to this date. Please see our Copyright FAQ for 

common questions about using materials from our site, including 

specific terms and conditions for packages like libwww, Amaya, 

and Jigsaw. Other questions about this notice can be directed to 

site-policy@w3.org. 

The following software may be included in this product: W3C 

XML Schema Test Collection v. 1.16.2; Use of any of this software 

is governed by the terms of the license below: W3C DOCUMENT 

NOTICE AND LICENSE Copyright © 1994-2002 World Wide 

Web Consortium, (Massachusetts Institute of Technology, Institut 

National de Recherche en Informatique et en Automatique, Keio 

University). All Rights Reserved. http://www.w3.org/ 

Consortium/Legal/ Public documents on the W3C site are 

provided by the copyright holders under the following license. 

The software or Document Type Definitions (DTDs) associated 

with W3C specifications are governed by the Software Notice. By 

using and/or copying this document, or the W3C document from 

which this statement is linked, you (the licensee) agree that you 


and conditions: Permission to use, copy, and distribute the 

contents of this document, or the W3C document from which this 

statement is linked, in any medium for any purpose and without 

fee or royalty is hereby granted, provided that you include the 

following on ALL copies of the document, or portions thereof, 

that you use: 1. A link or URL to the original W3C document. 2. 

The pre-existing copyright notice of the original author, or if it 

doesn't exist, a notice of the form: “Copyright yyyy [$date-ofdocument] 

World Wide Web Consortium, (Massachusetts 

Institute of Technology, Institut National de Recherche en 

Informatique et en Automatique, Keio University). All Rights 

Reserved. http://www.w3.org/Consortium/Legal/“ 

(Hypertext is preferred, but a textual representation is permitted.) 

3. If it exists, the STATUS of the W3C document. When space 

permits, inclusion of the full text of this NOTICE should be 

provided. We request that authorship attribution be provided in 

any software, documents, or other items or products that you 

create pursuant to the implementation of the contents of this 

document, or any portion thereof. No right to create 

modifications or derivatives of W3C documents is granted 

pursuant to this license. However, if additional requirements 

(documented in the Copyright FAQ) are satisfied, the right to 

create modifications or derivatives is sometimes granted by the 

W3C to individuals complying with those requirements. THIS 

DOCUMENT IS PROVIDED “AS IS,“ AND COPYRIGHT 


EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 

PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; 

THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE 

FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF 

SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY 

PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. 

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY 

DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL 

DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT 

OR THE PERFORMANCE OR IMPLEMENTATION OF THE 

CONTENTS THEREOF. The name and trademarks of copyright 

holders may NOT be used in advertising or publicity pertaining 

to this document or its contents without specific, written prior 

permission. Title to copyright in this document will at all times 

remain with copyright holders. This formulation of W3C’s notice 

and license became active on April 05 1999 so as to account for the 

treatment of DTDs, schema's and bindings. See the older 

formulation for the policy prior to this date. Please see our 

Copyright FAQ for common questions about using materials 

from our site, including specific terms and conditions for 

packages like libwww, Amaya, and Jigsaw. Other questions 

about this notice can be directed to site-policy@w3.org. 

webmaster (last updated by reagle on 1999/04/99.) 

The following software may be included in this product: 

Common Unix Printing System API Libraries (CUPS API library); 

This library is free software; you can redistribute it and/or 

modify it under the terms of the GNU Library General Public 

License as published by the Free Software Foundation; either 

version 2 of the License, or (at your option) any later version. This 




PARTICULAR PURPOSE. See the GNU Library General Public 


GNU Library 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. 

The following software may be included in this product: Mesa 

3-D graphics library v. 5; Use of any of this software is governed 

by the terms of the license below: core Mesa code include/GL/ 

gl.h Brian Paul Mesa GLX driver include/GL/glx.h Brian Paul 

Mesa Ext registry include/GL/glext.h SGI SGI Free B include/ 

GL/glxext.h Mesa license: The Mesa distribution consists of 

several components. Different copyrights and licenses apply to

different components. For example, GLUT is copyrighted by 

Mark Kilgard, some demo programs are copyrighted by SGI, 

some of the Mesa device drivers are copyrighted by their authors. 

See below for a list of Mesa's components and the copyright/ 

license for each. The core Mesa library is licensed according to the 

terms of the XFree86 copyright (an MIT-style license). This allows 

integration with the XFree86/DRI project. Unless otherwise 

stated, the Mesa source code and documentation is licensed as 

follows: Copyright © 1999–2003 Brian Paul All Rights Reserved. 


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 


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 




FITNESS FOR A PARTICULAR PURPOSE AND 

NONINFRINGEMENT. IN NO EVENT SHALL BRIAN PAUL 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. SGI FREE SOFTWARE LICENSE B 

(Version 1.1 [02/22/2000]) Except to the extent portions of this 

file are made subject to an alternative license as permitted in the 

SGI Free Software License B, Version 1.1 (the “License“), the 

contents of this file are subject only to the provisions of the 

License. You may not use this file except in compliance with the 

License. You may obtain a copy of the License at Silicon Graphics, 

Inc., attn: Legal Services, 1600 Amphitheatre Parkway, Mountain 

View, CA 94043-1351, or at: http://oss.sgi.com/projects/ 

FreeB Note that, as provided in the License, the Software is 

distributed on an “AS IS” basis, with ALL EXPRESS AND 

IMPLIED WARRANTIES AND CONDITIONS DISCLAIMED, 

INCLUDING, WITHOUT LIMITATION, ANY IMPLIED 

WARRANTIES AND CONDITIONS OF MERCHANTABILITY, 

SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR 

PURPOSE, AND NON-INFRINGEMENT. Original Code. The 

Original Code is: [name of software, version number, and release 

date], developed by Silicon Graphics, Inc. The Original Code is 

Copyright © [dates of first publication, as appearing in the Notice 

in the Original Code] Silicon Graphics, Inc. Copyright in any 

portions created by third parties is as indicated elsewhere herein. 

All Rights Reserved. Additional Notice Provisions: [such 

additional provisions, if any, as appear in the Notice in the 

Original Code under the heading “Additional Notice 

Provisions”] 

The following software may be included in this product: Byte 

Code Engineering Library (BCEL) v. 5; Use of any of this software 

is governed by the terms of the license below: Apache Software 

License / The Apache Software License, Version 1.1 Copyright © 

2001 The Apache Software Foundation. All rights reserved. 












/www.apache.org/).“ Alternately, this acknowledgment may 


acknowledgments normally appear. 4. The names “Apache“ and 

“Apache Software Foundation“ and “Apache BCEL“ 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”, “Apache BCEL”, 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. 

The following software may be included in this product: Regexp, 

Regular Expression Package v. 1.2; Use of any of this software is 

governed by the terms of the license below: The Apache Software 

License, Version 1.1 Copyright © 2001 The Apache Software 

Foundation. 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 disclaimer in the documentation 


end-user documentation included with the redistribution, if any, 

must include the following acknowledgment: “This product 

includes software developed by the Apache Software Foundation 

(http://www.apache.org/).“ Alternately, this acknowledgment 

may appear in the software itself, if and wherever such thirdparty 

acknowledgments normally appear. 4. The names 

“Apache“ and “Apache Software Foundation“ and “Apache 

Turbine“ must not be used to endorse or promote products 


written permission, please contact apache@apache.org. 

5. Products derived from this software may not be called 

“Apache”, “Apache Turbine”, nor may “Apache“ appear in their 

name, without prior written permission of the Apache Software 

















The following software may be included in this product: CUP 

Parser Generator for Java v. 0.10k; Use of any of this software is 

governed by the terms of the license below: CUP Parser 

Generator Copyright Notice, License, and Disclaimer Copyright 

1996–1999 by Scott Hudson, Frank Flannery, C. Scott Ananian 

Permission to use, copy, modify, and distribute this software and 

its documentation for any purpose and without fee is hereby 

granted, provided that the above copyright notice appear in all 

copies and that both the copyright notice and this permission 

notice and warranty disclaimer appear in supporting 

documentation, and that the names of the authors or their 

employers not be used in advertising or publicity pertaining to


distribution of the software without specific, written prior 

permission. The authors and their employers disclaim all 

warranties with regard to this software, including all implied 

warranties of merchantability and fitness. In no event shall the 

authors or their employers be liable for 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. 

The following software may be included in this product: JLex: A 

Lexical Analyzer Generator for Java v. 1.2.5; Use of any of this 

software is governed by the terms of the license below: JLEX 

COPYRIGHT NOTICE, LICENSE AND DISCLAIMER. Copyright 

1996–2003 by Elliot Joel Berk and C. Scott Ananian Permission to 

use, copy, modify, and distribute this software and its 

documentation for any purpose and without fee is hereby 

granted, provided that the above copyright notice appear in all 

copies and that both the copyright notice and this permission 

notice and warranty disclaimer appear in supporting 

documentation, and that the name of the authors or their 

employers not be used in advertising or publicity pertaining to 

distribution of the software without specific, written prior 

permission. The authors and their employers disclaim all 

warranties with regard to this software, including all implied 

warranties of merchantability and fitness. In no event shall the 

authors or their employers be liable for 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. Java is a trademark 

of Sun Microsystems, Inc. References to the Java programming 

language in relation to JLex are not meant to imply that Sun 

endorses this product. 

The following software may be included in this product: SAX v. 

2.0.1; Use of any of this software is governed by the terms of the 

license below: Copyright Status SAX is free! In fact, it's not 

possible to own a license to SAX, since it's been placed in the 

public domain. No Warranty Because SAX is released to the 

public domain, there is no warranty for the design or for the 

software implementation, to the extent permitted by applicable 

law. Except when otherwise stated in writing the copyright 

holders and/or other parties provide SAX “as is“ without 

warranty of any kind, either expressed or implied, including, but 

not limited to, the implied warranties of merchantability and 

fitness for a particular purpose. The entire risk as to the quality 

and performance of SAX is with you. Should SAX prove 

defective, you assume the cost of all necessary servicing, repair or 

correction. In no event unless required by applicable law or 

agreed to in writing will any copyright holder, or any other party 

who may modify and/or redistribute SAX, be liable to you for 

damages, including any general, special, incidental or 

consequential damages arising out of the use or inability to use 

SAX (including but not limited to loss of data or data being 

rendered inaccurate or losses sustained by you or third parties or 

a failure of the SAX to operate with any other programs), even if 

such holder or other party has been advised of the possibility of 

such damages. Copyright Disclaimers This page includes 

statements to that effect by David Megginson, who would have 

been able to claim copyright for the original work. SAX 1.0 

Version 1.0 of the Simple API for XML (SAX), created collectively 

by the membership of the XML-DEV mailing list, is hereby 

released into the public domain. No one owns SAX: you may use 

it freely in both commercial and non-commercial applications, 

bundle it with your software distribution, include it on a CD- 

ROM, list the source code in a book, mirror the documentation at 

your own web site, or use it in any other way you see fit. David 

Megginson, sax@megginson.com 1998-05-11 SAX 2.0 I hereby 

abandon any property rights to SAX 2.0 (the Simple API for 

XML), and release all of the SAX 2.0 source code, compiled code, 

and documentation contained in this distribution into the Public 

Domain. SAX comes with NO WARRANTY or guarantee of 

fitness for any purpose. David Megginson, 

david@megginson.com 2000-05-05. 

The following software may be included in this product: Cryptix; 

Use of any of this software is governed by the terms of the license 

below: Cryptix General License Copyright © 1995–2003 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 


the copyright notice, this list of conditions and the following 

disclaimer. 2. Redistributions in binary form must reproduce the 



with the distribution. THIS SOFTWARE IS PROVIDED BY THE 

CRYPTIX FOUNDATION LIMITED AND CONTRIBUTORS 

“AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, 




SHALL THE CRYPTIX FOUNDATION LIMITED OR 











SUCH DAMAGE. 

This product contains DOM4J 1.6.1. Copyright 2001-2005 © 

MetaStuff, Ltd. All Rights Reserved. Redistribution and use of 

this software and associated documentation (“Software“), with or 



copyright statements and notices. Redistributions must also 

contain a copy of this document. 2. Redistributions in binary form 



materials provided with the distribution. 3. The name “DOM4J“ 

must not be used to endorse or promote products derived from 

this Software without prior written permission of MetaStuff, Ltd. 

For written permission, please contact dom4jinfo@metastuff.com. 

4. Products derived from this Software may 

not be called “DOM4J“ nor may “DOM4J“ appear in their names 

without prior written permission of MetaStuff, Ltd. DOM4J is a 

registered trademark of MetaStuff, Ltd. 5. Due credit should be 

given to the DOM4J Project - http://www.dom4j.org. THIS 

SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND 

CONTRIBUTORS “AS IS” AND ANY EXPRESSED OR IMPLIED 




IN NO EVENT SHALL METASTUFF, LTD. OR ITS 











SUCH DAMAGE.

MKS Integrity Server Administration Guide

Create successful ePaper yourself

Delete template?

Save as template?